Cards overview

A card belongs to one account, so most card endpoints are scoped by both the customer and the account. Not every program has cards, secure details, 3DS, or cardholders. If a feature is off for your program you get a clear error rather than a result. Check program capabilities first.

​

Lifecycle

A new card starts as created and has to be activated before it works. Blocking is temporary and reversible. Cancelling is permanent; issue a new card if the customer needs one again.

​

What you can do

​

Issue a card

Get card options lists the card products this account can have. Don’t hard-code product names; they depend on the account’s tier and your program’s setup. Create a card issues one, virtual or physical. Send an idempotency key: creation charges a setup fee and provisions a card at the issuer, so a blind retry can leave the customer with two cards and two fees. Then activate it. Some providers ask for the card’s last four digits at activation.

​

Read cards

Get cards lists the account’s cards and Get card details returns one. The card number is masked and the CVV hidden in both; see secure details for the real values. List card transactions returns the card’s spend, newest first, with merchant details. For the whole account’s history, use transactions.

​

Block, unblock, cancel, reset PIN

Block declines every transaction until you unblock. Cancel closes the card for good. Reset card PIN sets the PIN the customer types at an ATM or terminal. It’s unrelated to the security PIN used to confirm sensitive actions.

​

Limits

A program edits card limits one of two ways, and cards.limits.mode on the account in program capabilities says which. Calling the wrong one fails cleanly, so branch on the capability rather than trying both.

• Custom. The cardholder sets their own limits per card, anywhere below the program’s ceiling: amounts and transaction counts by channel, merchant categories, countries, and transaction types. Get this card’s policy, update it, and the options they can pick from. The card limits walkthrough shows a full read-change-save round trip and the rules behind it.
• Preset. The cardholder picks one of the limit profiles the program offers with Update card limit group.

​

Secure details

The card object never exposes the real card number or CVV. To show them, use the secure flow. It’s encrypted end to end and gated by a step-up confirmation, the same passkey, 2FA code, or PIN used elsewhere in the API.

1. Get secure key: you get a key to decrypt with and a cipher to send back.
2. If the customer confirms with a passkey, request a secure details passkey challenge and complete it on the device. For a 2FA code or PIN, skip this step.
3. Get secure card details with the cipher and the confirmation.
4. Decrypt the response with the key, render it, and discard it. Never log or store the decrypted values.

​

3D Secure

When a card payment triggers 3D Secure, a challenge is created for the customer to approve or reject. Receive challenges in real time over WebSockets (recommended) or poll Get recent 3DS notifications, which spans every account the customer holds. Show the transaction, then confirm the challenge with the customer’s answer.

​

Cardholders

Someone who isn’t the account owner can hold a card on it: an employee with a company card, a family member with a supplementary one. See Cardholders.