Controls

Every authorization is checked against the card's own controls and against the bank's. This page lists both, and the response code each decline carries.

Controls on the card

PUT /cards/{id}/controls replaces the whole set, so send every field you want to keep. A channel left out is false, and a purchase on it is declined. A new card starts with every channel on, 500000 per transaction and 1000000 per day. Each change publishes cards.card.controls_changed.

channelsobjectRequired

Four booleans: pos, ecommerce, atm and contactless.

per_transaction_limit_amountintegerRequired

The most one authorization may be, in minor units. 0 turns the limit off.

daily_limit_amountintegerRequired

The most the card may spend in one cardholder day. The day is a calendar day in the bank's cardholder time zone, America/New_York by default, not the banking date. It counts authorizations that are authorized or cleared. 0 turns the limit off.

blocked_mccsarray of stringsOptional

Merchant category codes the card refuses, matched exactly against the authorization's mcc.

allowed_countriesarray of stringsOptional

Empty means any country. Otherwise the authorization's country must equal one entry as sent.

single_usebooleanVirtual only

The card approves one purchase. It cannot change after an approved or unfinished authorization: 409 conflict.

merchant_idstringVirtual only

Locks the card to one processor merchant identity, up to 200 visible ASCII characters.

valid_from, valid_untilstring · date-timeVirtual only

The window in which the card approves. The end is exclusive.

A virtual-only control on a physical card is 400 validation_failed, and so is a negative limit.

The bank's controls

Sanctioned jurisdictions. The merchant's country, merchant_region and merchant_postal_code are compared with the list in force. The country may arrive as ISO 3166 alpha-2, alpha-3 or numeric. Sanctions outrank the card's own rules. A country or region that cannot be read, or a list that cannot be loaded, declines rather than approves.
Merchant blocks. Every cleared merchant is screened against the sanctions lists. A screening that is not clear blocks that merchant identity and raises a compliance alert.
The account or facility. An account that is not open or has a debit block declines as account_frozen.
The cardholder. A cardholder who is no longer eligible declines as do_not_honor.

Changes to the bank's controls take two staff members. One proposes a jurisdiction change, asks for a block to be cleared or proposes stand-in parameters. A different person decides. The error code cards.dual_control (422) belongs to key ceremonies: it refuses the opener entering a key component, a custodian entering a second one, and an approver who took part in the ceremony.

Decline reasons and response codes

A decline is not an HTTP error. POST /authorizations answers 200 with decision, reason and the ISO 8583 response_code, and the same three are kept on the authorization. A malformed request, such as an amount that is not positive, is 400 validation_failed and records nothing.

Reason	Code	When
`approved`	`00`	Approved for the amount asked.
`approved`	`10`	Approved for less than asked: a partial approval.
`control_declined`	`57`	A blocked MCC, a country not allowed, a channel that is off, a used single-use card, or a virtual card outside its merchant or window.
`limit_exceeded`	`61`	Over the per-transaction or the daily limit.
`insufficient_funds`	`51`	The account or the credit line cannot carry the amount.
`card_not_active`	`78`	The card is `inactive`.
`card_paused`	`62`	The card is `paused`.
`account_frozen`	`62`	The account is not open, has a debit block, or the facility cannot be drawn.
`card_lost`	`41`	The card was reported lost.
`card_stolen`	`43`	The card was reported stolen.
`card_closed`	`46`	The card is closed.
`card_expired`	`54`	Past the end of the expiry month.
`restricted_jurisdiction`	`93`	The merchant is in a sanctioned country or area.
`restricted_merchant`	`93`	The merchant is under a block.
`screening_unavailable`	`05`	The country could not be read or the lists could not be loaded.
`do_not_honor`	`05`	A currency other than USD, a cardholder who is not eligible, or a hold that did not stand.
`do_not_honor`	`14`	The `pan_token` matches no card.

The ISO 8583 switch adds codes of its own, among them 55 and 75 for a wrong PIN and used-up PIN tries, 63 for a card code, cryptogram or 3-D Secure value that did not verify, and 91 when the bank could not decide in time and no stand-in parameters applied.