> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/cards/retrieve-a-card.md).

# Retrieve a card

Returns a single card by its identifier. The bank, the card type and the four terminal fields are returned as identifiers rather than nested objects.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Cards","description":"Administrative endpoints for **cards** — the records that describe a payment card the store accepts and decide which POS terminal each kind of payment made with it is sent through. A card belongs to a bank, carries a card type and states whether it is a credit or a debit card.\n\nA card is never chosen by the customer, and it is not a stored card of a customer either. It is a configuration record: when a payment is taken, the first six digits of the card number are matched against the registered bin numbers, the matching bin number points at one of these cards, and the terminals stored on that card determine where the payment request goes.\n\nA card holds four terminal assignments — one for a single payment, one for an installment payment, and optionally one for each of those when the payment is redirected to 3D secure verification. The one that is used is chosen in that order of precedence, and an assignment that is missing is skipped: a payment that is redirected to verification but whose card has no 3D secure terminal falls back to the ordinary one rather than failing. The installment options offered to the customer are attached to the card as well. Finally, when the currency of the payment matches one of the card's multi-currency records, that record stands in for the card and its terminals are used in place of the ones stored here.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* Retrieve a paginated list of cards, ordered by identifier ascending unless the `sort` parameter says otherwise.\n* Filter by identifier, bank, card type or payment type. Each filter matches the whole value, and each also has a negated form — see **Filtering & Ordering**.\n* Order the results with the `sort` parameter, as described under **Filtering & Ordering**.\n\n**2. Full CRUD**\n* Register a card with its bank, card type, payment type and terminal assignments.\n* Fully or partially update an existing card.\n* Delete a card. `DELETE` **permanently removes** the record — there is no soft delete, and a card cannot be deactivated through this API. See **Deleting a Card** for when a deletion is refused.\n\n**3. Two Independent Uniqueness Rules**\n* A bank may hold only one card per card type and payment type combination.\n* Within a bank, the `slug` code of a card must not repeat. The two rules fail differently — see **Uniqueness**.\n\n## Card Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `pk` | integer | The unique identifier of the card. Assigned by the server; supplying it in a request body has no effect. |\n| `name` | string | The display name of the card. Required on create and on full update. Maximum 64 characters. |\n| `slug` | string | The code that identifies the card within its bank. Required on create and on full update, optional on a partial update — but an omitted value is regenerated rather than kept. See **The Code of a Card**. Maximum 64 characters, and may contain only letters, digits, underscores and hyphens. |\n| `bank` | integer | The identifier of the bank the card belongs to. Required on create and on full update. |\n| `card_type` | integer | The identifier of the card type — the scheme or programme of the card. Required on create and on full update. |\n| `card_payment_type` | string | Either `credit` or `debit`. Required on create and on full update, even though a card that is stored without one is treated as a credit card. Beyond the uniqueness rule it takes part in, marking a card `debit` lets a payment that already requests 3D secure verification skip the 3D secure rules — see **Dynamic Settings & Environment Variables**. |\n| `cash_payment` | integer | The identifier of the POS terminal a single, non-installment payment is sent through. Required on create and on full update. |\n| `installment_payment` | integer | The identifier of the POS terminal an installment payment is sent through. Required on create and on full update. |\n| `three_d_payment` | integer or `null` | The identifier of the POS terminal used when a single payment is redirected to 3D secure verification. Optional; `null` when the card has none. Only used while 3D secure verification is switched on. |\n| `installment_three_d_payment` | integer or `null` | The identifier of the POS terminal used when an installment payment is redirected to 3D secure verification. Optional; `null` when the card has none. |\n| `is_commerce_card` | boolean or `null` | Marks the card as the store's own commerce card. Optional. Omitting it from a JSON body stores `false`; omitting it from a form-encoded request stores `null` instead. The two read the same way — anything other than `true` counts as not a commerce card — so a client does not have to tell them apart. On its own the field changes nothing: it is read by the commerce-card installment filters, and only takes effect while those are in the filter chain. See **Dynamic Settings & Environment Variables**. |\n\nThe bank, the card type and the four terminal fields are given and returned as identifiers, never as nested objects. An identifier that does not belong to an existing record fails validation. Fields that are not part of the card are ignored rather than rejected.\n\n## Uniqueness\n\nA card is subject to two separate rules, and they fail in different ways:\n\n* **One card per bank, card type and payment type.** The three fields together must be unique across all cards. A request that would repeat an existing combination fails validation with `400 Bad Request`, and the message names the three fields as a set.\n* **One code per bank.** The `slug` code must not already belong to another card of the same bank. A request that would repeat one is rejected with `406 Not Acceptable` and the message `<code> already exists`, carrying the stable code `card_100`. The same code may be used by cards of different banks.\n\nThe wording of that second answer is translated, so it is not the same text in every deployment: it is rendered in the language the deployment is configured for. An `Accept-Language` header does **not** change it — the platform drops that header unless the request also carries an Omnitron session header, and that behaviour is itself controlled by a dynamic setting (see **Dynamic Settings & Environment Variables**). Match on the `error_code` value rather than on the message text.\n\nOn an update the code is checked among the cards of the bank the card belonged to **before** the request. When the same request also moves the card to another bank, the code is not checked against the cards of that new bank, so a collision there is not caught.\n\n## The Code of a Card\n\nThe `slug` code is required on create and on full update, so those operations always store exactly what was sent.\n\nOn a **partial update** the code is optional, and this is where care is needed: an omitted code is not left alone but **derived again from the name** — from the name sent in the request if there is one, and from the stored name otherwise. A partial update that changes only `is_commerce_card`, for example, still rewrites the code to the derived form of the card's current name, which replaces spaces and other separators with hyphens and lower-cases the rest.\n\nThe practical consequence: if a card's code does not already match the derived form of its name, include the code in every partial update. Otherwise the card silently ends up with a different code, and any integration that refers to it by code loses the reference.\n\n## Filtering & Ordering\n\nCards can be filtered with the `id`, `bank`, `card_type` and `card_payment_type` query parameters. Each is an **exact** match on a whole value; partial and multi-value forms are not available. `bank` and `card_type` take the identifier of the referenced record, and `card_payment_type` takes `credit` or `debit`.\n\nEvery one of these also has a **negated form**, written by appending an exclamation mark to the parameter name. `?card_payment_type!=debit` returns the cards that are not debit cards, and `?bank!=3` returns the cards of every bank except that one.\n\nA value that cannot be used — a non-numeric identifier, an identifier that matches no record, or a payment type outside the two listed above — fails the request with `400 Bad Request` rather than returning an empty page. Query parameters that are not listed here are ignored rather than rejected, so check the response `count` before assuming a filter was applied.\n\nResults can be ordered with the `sort` parameter on `pk`, `name`, `slug`, `bank`, `card_type`, `card_payment_type`, `cash_payment`, `installment_payment`, `three_d_payment`, `installment_three_d_payment` and `is_commerce_card`. Prefix a field with a hyphen for descending order, and separate several fields with commas. Any other value — including the creation and modification timestamps, which are not part of the card representation — is ignored and the default ordering by identifier ascending is kept. Note that ordering on the bank, the card type or any of the terminal fields sorts by the referenced identifier, not by the name of that record.\n\n## Deleting a Card\n\n> **Warning:** Deletion is permanent. There is no soft delete and no way to deactivate a card instead, so a card that should stop being used has to be pointed at a different terminal rather than removed.\n\nA deletion is refused while the card is still referenced elsewhere — by a bin number that resolves to it, by one of its installment options, by one of its multi-currency records, or by an order that was paid with it. Because an order keeps its reference for as long as it is retained, a card that has ever been used in a completed payment is in practice not deletable. Remove the bin numbers, installments and multi-currency records that point at the card first; if an order still refers to it, keep the card in place.\n\n## Dynamic Settings & Environment Variables\n\nWhich cards these endpoints return, and which requests they accept, does not depend on any dynamic setting: listing, filtering, creation, update and deletion behave identically regardless of how the settings are configured. One setting does affect what a response *reads like*, and the rest determine how the cards managed here are **used when a payment is taken**. Each is referenced again where it relates to a field of the card.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `IGNORE_ACCEPT_LANGUAGE_HEADER` | boolean | `true` | Decides whether a client may influence the language the business error message under **Uniqueness** is rendered in. While it is on, which is the default, an `Accept-Language` header is discarded unless the request also carries an Omnitron session header, and the message comes back in the deployment's default language. Turning it off lets the header take part in the choice — but only among the languages the deployment is configured for, so on a single-language deployment the message does not change either way. It changes no other part of these endpoints. |\n| `THREE_D_SECURE_ENABLED` | boolean | the server configuration value of the same name, and `false` if that is unset | The master switch for 3D secure verification. While it is off, no payment is redirected to verification, so the `three_d_payment` and `installment_three_d_payment` terminals stored on a card are never used. While it is on and the terminal handling the payment does not itself request verification, the configuration of the card's `three_d_payment` terminal decides whether the payment is redirected. |\n| `THREE_D_SECURE_RULES` | array of objects, each holding a rule and its parameters | the server configuration value of the same name, and empty if that is unset | The rules that decide, per payment, whether a card that requests 3D secure actually redirects. While the list is empty, the terminal configuration alone decides; once it is populated, a redirect additionally requires at least one rule to match. |\n| `INSTALLMENT_FILTERS` | array of objects, each holding a filter and its parameters | the server configuration value of the same name, and empty if that is unset | The chain of filters the installment options offered for a card are passed through, in the order given. Two of the available filters read the `is_commerce_card` flag of the card the options belong to, and both behave the same way for a card that is **not** marked: they pass the options through untouched and let the chain continue. For a card that **is** marked, both **stop the chain**, so the options survive whatever filters were configured after them — but they differ in what they leave behind. The plain commerce-card filter passes the options through unchanged. The category variant first narrows them to the installment counts the categories of the products in the basket allow, read from a `max_commerce_card_installment_options` setting on each category, and only then stops the chain. While neither filter is in the chain, `is_commerce_card` has no visible effect on what the customer is offered. |\n\n**Environment variables:** No environment variables are read by these endpoints. The related server configuration values are `THREE_D_SECURE_ENABLED`, `THREE_D_SECURE_RULES` and `INSTALLMENT_FILTERS`, which seed the defaults of the dynamic settings above, and two further values that are read directly at payment time:\n\n| Variable | Default | Effect |\n|----------|---------|--------|\n| `THREE_D_VALIDATE_CARD_TYPE` | off | While on, a payment is redirected to 3D secure verification only if the card number also passes the card-type check, so a card configured with a 3D secure terminal may still be paid without verification. |\n| `THREE_D_REDIRECT_DEBIT` | on | While on, a payment whose card number resolves to a card marked `debit` is redirected to 3D secure verification **without the 3D secure rules being consulted** — the rules that would otherwise be able to veto the redirect are skipped. It does not request verification on its own: verification must already have been asked for, either by the terminal handling the payment or by the card's own `three_d_payment` terminal. A debit card whose terminals ask for no verification is still paid without it. The `card_payment_type` stored here is what the debit decision is read from. |"}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"Card":{"type":"object","description":"A card returned by the API — the record that describes a payment card the store accepts and states which POS terminal each kind of payment made with it is sent through. The bank, the card type and the four terminal fields are returned as identifiers rather than nested objects.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the card."},"name":{"type":"string","maxLength":64,"description":"Display name of the card."},"slug":{"type":"string","maxLength":64,"description":"The code that identifies the card within its bank. Unique among the cards of the same bank, but the same code may be used by cards of other banks."},"bank":{"type":"integer","description":"Identifier of the bank the card belongs to."},"card_type":{"type":"integer","description":"Identifier of the card type — the scheme or programme of the card."},"card_payment_type":{"$ref":"#/components/schemas/CardPaymentType"},"cash_payment":{"type":"integer","description":"Identifier of the POS terminal a single, non-installment payment is sent through."},"installment_payment":{"type":"integer","description":"Identifier of the POS terminal an installment payment is sent through."},"three_d_payment":{"type":["integer","null"],"description":"Identifier of the POS terminal used when a single payment is redirected to 3D secure verification, or `null` when the card has none. Never used while `THREE_D_SECURE_ENABLED` is off."},"installment_three_d_payment":{"type":["integer","null"],"description":"Identifier of the POS terminal used when an installment payment is redirected to 3D secure verification, or `null` when the card has none."},"is_commerce_card":{"type":["boolean","null"],"description":"Whether the card is the store's own commerce card. Read by the commerce-card installment filters, and without effect while none of them is configured through `INSTALLMENT_FILTERS`."}},"required":["pk","name","slug","bank","card_type","card_payment_type","cash_payment","installment_payment","three_d_payment","installment_three_d_payment","is_commerce_card"]},"CardPaymentType":{"type":"string","description":"Whether a card is a credit or a debit card.\n* `credit` — a credit card. A card stored without a payment type is treated as one.\n* `debit` — a debit card. While `THREE_D_REDIRECT_DEBIT` is on, which is the default, every payment matched to a card marked this way is redirected to 3D secure verification.","enum":["credit","debit"]},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}},"responses":{"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"CardNotFound":{"description":"The requested card does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/cards/{id}/":{"get":{"tags":["Cards"],"operationId":"retrieveCard","summary":"Retrieve a card","description":"Returns a single card by its identifier. The bank, the card type and the four terminal fields are returned as identifiers rather than nested objects.","responses":{"200":{"description":"The requested card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Card"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/CardNotFound"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/cards/retrieve-a-card.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
