Card lifecycle
A card moves through a small number of states during its lifetime. Some states can change, while others are permanent.
Before you begin
There's nothing to set up. Read this before building anything that displays card status or lets someone take action on a card.
The important distinction is between a card that's temporarily blocked and one
that's permanently finished. frozen can be reversed; expired and closed
cannot.
How it works
| State | Meaning | Can it authorize? | Reversible? |
|---|---|---|---|
pending | The request was accepted and the processor has not issued the card yet. The card leaves this state by itself, usually within minutes | No | |
inactive | The card has been issued and is waiting for you to activate it with POST /v1/cards/{id}/activate | No | |
active | Card can be used | Yes | |
frozen | Card is temporarily blocked | No | Yes, by unfreezing |
expired | Card has passed its expiry date | No | No |
closed | Card has been permanently terminated | No | No |
Every card needs to be activated
Virtual and physical cards follow the same flow: pending, then inactive when
card.issued comes in, and finally active once you call POST /v1/cards/{id}/activate. You make this call from your server, and it returns
the card. There’s no hosted page — the card won't be usable until you activate
it.
The two terminal states
expired and closed are final. There is no API call that can bring either
state back. An expired card can still be closed, which is the only change
left to it.
Closing a card also invalidates every network token created for it, including tokens used by mobile wallets. Once a card is closed, the only way to continue using a card is to issue a replacement.
Freeze is reversible
If a cardholder has lost or misplaced their card, freeze it first. New authorizations are blocked, but the card itself remains intact and can be unfrozen later.
Unfreezing takes effect immediately.
Use close when the card is permanently finished, such as when it has been
compromised, is no longer needed, or belongs to a cardholder who has left.
Closing a card that only needed to be frozen means the cardholder will need a replacement and another delivery cycle.
Common errors
| Status | code | Meaning |
|---|---|---|
422 | card_invalid_state | The card's status doesn't allow the operation. This covers freezing a card that isn't active, freezing one that is already frozen, unfreezing one that isn't frozen, activating one that is pending, frozen or expired, and any operation on an expired card except closing it. The message names the state |
422 | card_already_activated | Activation was called on a card that is already active |
422 | card_closed | The card is permanently closed, including closing it a second time. Issue a replacement |
422 | card_not_provisioned | The processor hasn't issued the card yet, so the operation can't reach it. Wait for card.issued |
These errors aren't retryable. They describe the card's current state, and retrying the same request won't change that state.
Related
- Operations by card status — which operations are available in each state and the errors returned when they're not
- Freeze, replace, close
- Core concepts
- Card issuing events