Cards
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.
A 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.
A 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.
Core Capabilities
1. Listing & Filtering
Retrieve a paginated list of cards, ordered by identifier ascending unless the
sortparameter says otherwise.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.
Order the results with the
sortparameter, as described under Filtering & Ordering.
2. Full CRUD
Register a card with its bank, card type, payment type and terminal assignments.
Fully or partially update an existing card.
Delete a card.
DELETEpermanently 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.
3. Two Independent Uniqueness Rules
A bank may hold only one card per card type and payment type combination.
Within a bank, the
slugcode of a card must not repeat. The two rules fail differently — see Uniqueness.
Card Fields
pk
integer
The unique identifier of the card. Assigned by the server; supplying it in a request body has no effect.
name
string
The display name of the card. Required on create and on full update. Maximum 64 characters.
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.
bank
integer
The identifier of the bank the card belongs to. Required on create and on full update.
card_type
integer
The identifier of the card type — the scheme or programme of the card. Required on create and on full update.
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.
cash_payment
integer
The identifier of the POS terminal a single, non-installment payment is sent through. Required on create and on full update.
installment_payment
integer
The identifier of the POS terminal an installment payment is sent through. Required on create and on full update.
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.
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.
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.
The 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.
Uniqueness
A card is subject to two separate rules, and they fail in different ways:
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.One code per bank. The
slugcode must not already belong to another card of the same bank. A request that would repeat one is rejected with406 Not Acceptableand the message<code> already exists, carrying the stable codecard_100. The same code may be used by cards of different banks.
The 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.
On 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.
The Code of a Card
The slug code is required on create and on full update, so those operations always store exactly what was sent.
On 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.
The 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.
Filtering & Ordering
Cards 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.
Every 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.
A 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.
Results 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.
Deleting a Card
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.
A 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.
Dynamic Settings & Environment Variables
Which 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.
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.
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.
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.
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.
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:
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.
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.
Last updated
Was this helpful?

