Cards overview
The cards service issues debit and credit cards, decides authorizations, posts clearings and settles with each network. The card networks, the issuer-processor, the card bureau and the HSM are simulators today.
What a card is
A card is issued on visa, mastercard or discover. The BINs in the code are placeholders until each network assigns the bank its ranges. Every card has a kind and a form.
- A
debitcard draws on a deposit account, itsaccount_id. Acreditcard draws on a revolving facility in lending, itsfacility_id, and itsaccount_idis the facility's settlement account. virtualis the default form. Aphysicalcard is ordered from a card bureau.
The card number is generated on the network's BIN with a Luhn check digit and encrypted at rest. Card endpoints return pan_token and last4, never the number. Revealing the number needs a step-up within five minutes, is recorded, and is limited to ten reveals per staff member per hour.
How card traffic arrives
Two paths reach the same decision, hold, clearing and settlement logic.
- JSON from the issuer-processor:
POST /authorizations, then the clear, increment and reverse routes,POST /clearingsandPOST /refunds. - ISO 8583 over the card switch, one link per network: authorization and financial requests (0100, 0200), advices (0120, 0220), reversals (0400, 0420) and network management (0800).
GET /cards/switch/linksshows each link.
The only link adapter is simulator, and it is refused in the production environment. When the core cannot decide within the response deadline, five seconds by default, the switch answers from stand-in parameters that one staff member proposed and another approved. In the sandbox, /simulate/cards/purchase and /simulate/cards/clearing play the processor, and /simulate/cards/switch/messages takes one packed ISO 8583 message.
Card security
PIN blocks, card verification codes, EMV cryptograms and 3-D Secure values are verified through an HSM adapter. Both adapters, software and network, are simulators and are refused in the production environment. With no adapter configured, the switch declines any message that carries a credential with response code 05, and the PIN and key routes answer 409 cards.hsm_not_configured. A PIN never leaves the HSM: only the IBM 3624 offset or the Visa PVV is stored. Keys are created, imported, exported, rotated and retired in key ceremonies that a second staff member approves. GET /cards/security/hsm reports the adapter in use.
The objects
| Object | What it is |
|---|---|
| Card | The card, its status, its controls and the token that stands for its number. It names one account, one cardholder and, for credit, one facility. |
| Cardholder Authority | Reviewed evidence that a person who does not own the funding account may hold a card on it. |
| Authorization | The decision on one purchase: card_id, response_code, the hold_id it placed, and the journal_id or draw_id of the clearing that posted it. |
| Card Security | The key registry, key ceremonies and the HSM adapter. Each card's personalization and PIN record sit under the card. |
| Sanctioned Jurisdiction | The countries and areas in which authorizations are declined. |
| Merchant Screening and Merchant Block | The sanctions screening of every cleared merchant, and the block a screening that was not clear places on that merchant. |
| ATM | Bank-owned terminals and shared-network ATM traffic. The network and PIN security simulators are refused in production. |
The Card resource also carries 3-D Secure, network tokens, card production, clearing files, scheme cases and network settlement finance.
Who may call
Issuing a card, changing its status or controls and revealing its number need a verified staff token with cards:write and an authentication within the last five minutes. Reads need cards:read or cards:write. The issuer-processor's service identity can authorize, clear, reverse, settle and read authorizations. It cannot issue or manage cards. See Authentication.