For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 sort parameter 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 sort parameter, 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. 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.

3. Two Independent Uniqueness Rules

  • A bank may hold only one card per card type and payment type combination.

  • Within a bank, the slug code of a card must not repeat. The two rules fail differently — see Uniqueness.

Card Fields

Field
Type
Description

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 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.

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.

Key
Type
Default
Effect

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:

Variable
Default
Effect

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?