Operations by card status
Here's what you can do with a card in each status, and what happens when the
card is used.
Read across a row to see what a card in that state can do. Read down a column to
see when an operation is refused and which code comes back.
Key
| Mark | Meaning |
|---|---|
| ✓ | Succeeds. Any condition in the footnote still applies |
✗ code | Refused with 422 and that code. Retrying won't change the result |
↓ reason | The card is presented and declined. The authorization contains the decline_reason; no API error is returned |
The matrix
| Status | Activate | Request physical | Lock | Unlock | Close | Replace | Set PIN | Show card details | Credit / debit wallet | Online payment | Apple Pay / Google Pay |
|---|---|---|---|---|---|---|---|---|---|---|---|
pending | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state | ✓ | ✗ card_not_provisioned | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state ² | ↓ card_not_active | ↓ card_not_active |
inactive | ✓ → active ³ | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state | ✓ | ✓ | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state ² | ↓ card_not_active | ↓ card_not_active |
active | ✗ card_already_activated | ✓ ⁵ | ✓ → frozen | ✗ card_invalid_state | ✓ | ✓ | ✓ ⁴ | ✓ | ✓ ² | ✓ ¹ | ✓ ¹ |
frozen | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state | ✓ → active | ✓ | ✓ | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state ² | ↓ card_not_active | ↓ card_not_active |
expired | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state | ✓ | ✓ | ✗ card_invalid_state | ✗ card_invalid_state | ✗ card_invalid_state ² | ↓ card_expired | ↓ card_expired |
closed | ✗ card_closed | ✗ card_closed | ✗ card_closed | ✗ card_closed | ✗ card_closed | ✗ card_closed | ✗ card_closed | ✗ card_closed | ✗ card_invalid_state ² | ↓ restricted_card | ↓ restricted_card |
¹ For a payment to go through, the funding account must be active, otherwise the payment is declined as blocked, and the available balance must cover the amount, otherwise it is declined for insufficient funds. Each decline carries the same reason on the authorization at the processor.
² Value can only be added to or removed from the account while its card is active. In any other status the call is refused with an invalid state error. The account itself must also be active, otherwise the call is refused as blocked, and a debit also fails when the available balance is too low.
³ The cardholder must still be approved, otherwise activation is refused. If the call fails, the card stays inactive and can be activated again.
⁴ A PIN is set on a physical card, and the card must be active. A virtual card is refused with an invalid state error in every status.
⁵ Only a card that is still virtual. A card that is already physical is
refused with an invalid state error in every status, which is also what a second
request gets. The program must issue physical cards too, otherwise the refusal
is unsupported_form_factor; and where the program's processor cannot have
plastic made for a card already issued, the endpoint isn't mounted and the path
returns 404.
What each column is
| Operation | API call | Notes |
|---|---|---|
| Activate | POST /v1/cards/{card_id}/activate | Moves inactive → active. A server-to-server call with no body and no hosted page, for virtual and physical cards alike. Call it after card.issued |
| Request physical | POST /v1/cards/{card_id}/request-physical | Orders plastic for a card issued without it. No body, and it returns the same card — form_factor becomes physical and fulfillment.status pending. status is unchanged, so the card keeps spending online. See issuing a physical card |
| Lock | POST /v1/cards/{card_id}/freeze | Moves active → frozen. Reversible; everything else about the card stays the same |
| Unlock | POST /v1/cards/{card_id}/unfreeze | Moves frozen → active. The next presentation can be approved |
| Close | POST /v1/cards/{card_id}/close | Permanent. Invalidates the card's network tokens. If you only need a temporary block, lock it instead |
| Replace | POST /v1/cards/{card_id}/replace | Issues a new card and closes this one. Refused for a card the processor hasn't issued yet. See freeze, replace, close |
| Set PIN | POST /v1/cards/{card_id}/pin | Sets the PIN from a PIN encrypted on the device. See PIN management |
| Show card details | POST /v1/cards/{card_id}/secrets | Returns the card number and security code encrypted to a public key you send. See displaying PAN and CVV securely |
| Credit / debit wallet | POST /v1/accounts/{account_id}/credit and /debit | Adds or removes value on the account the card spends from. Held funds aren't available to debit |
| Online payment | An e-commerce authorization | Decided when the card is presented. A completed purchase reaches you later as a settled transaction |
Some operations aren't in the matrix because they work in every status: GET /v1/cards/{card_id} and the card list endpoints.
A new card is pending, then inactive once it has been issued (card.issued),
and only becomes active when you activate it. See Issuing a virtual
card.
Related
- Card lifecycle — the card states and how they change
- Freeze, replace, close — the operations step by step
- Accounts and funding