Card state model
A card has two separate attributes: status controls its use; stage describes physical fulfillment. Read and store both. A delivered card can be deactivated, and an active card can still be in digital stage.
Status and stage together
Select a scenario to see the two attributes and the action they support.
An active digital card is eligible for use subject to normal controls. A delivered card in deactivated status is temporarily disabled. Fulfillment does not activate the card.
Card status
Use a temporary status to pause a card. Use a permanent status to retire it or report a condition that requires replacement.
token_status | Effect and next action |
|---|---|
new | Not yet activated. Activate through the supported product flow. |
active | Eligible for use, subject to funds, limits and transaction controls. |
deactivated | Temporary pause. Change back to active when use should resume and the product permits it. |
blocked | Use is blocked. Resolve the block through the supported issuer/product process before reactivation. This is different from permanent closure. |
referral | Contact between the client and issuer is required. Follow that process; this is not a delivery state or permanent closure. |
closed | Permanent closure. Cannot return to active.Use this to close the card permanently. |
compromized | Permanent. Cannot reactivate. Card is compromised; follow the replacement process. Keep this exact API spelling. |
damaged | Permanent. Cannot reactivate. Card is damaged; follow the replacement process. |
lost | Permanent. Cannot reactivate. Card is reported lost; follow the replacement process. |
stolen | Permanent. Cannot reactivate. Card is reported stolen; follow the replacement process. |
The permanent statuses are closed, compromized, damaged, lost and stolen. Future card use requires a new card under the product's issuance or replacement flow. Do not use one of these statuses for a temporary pause.
Card stage
token_stage | Meaning |
|---|---|
digital | Card is in digital stage. |
plastic_not_delivered | Orders the physical card and records that delivery is pending. Use this in the agreed physical-card issuance flow. |
plastic_delivered | Physical card has been delivered. This value can be read from the card. |
Track fulfillment separately from authorization eligibility. Updating stage does not itself request a status change.
Values by operation
Use the values accepted by the specific operation. A value returned by a read operation may not be accepted by an update request.
| Operation | Accepted or returned values |
|---|---|
Create card: token_status | new, active |
Create card: token_stage | digital, plastic_not_delivered |
Read card: token_status | All ten status values above. |
Read card: token_stage | digital, plastic_not_delivered, plastic_delivered |
Update status: token_status | active, blocked, closed, compromized, damaged, deactivated, lost, referral, stolen.new is not an accepted update value. |
Update stage: token_stage | digital, plastic_not_delivered.The current request schema does not accept plastic_delivered. |
Use Card API for the exact request/response contract and provisioned path prefixes. The examples below use the schema reference paths.
Common actions
Activate a new card, or resume a temporarily deactivated card when allowed for the product:
PATCH /v1/update-card-status/99000000000000000001
This does not reactivate a permanently closed, compromised, damaged, lost or stolen card. Status and physical delivery remain separate.
PATCH /v1/update-card-status/99000000000000000001
Use this for a temporary pause. To resume later, use active through the supported status flow.
PATCH /v1/update-card-status/99000000000000000001
After the successful update, this card cannot return to active. Use a new card for future activity. Continue processing outstanding authorizations, reversals and presentments; closure does not refund a purchase or release every hold automatically.
PATCH /v1/update-card-stage/99000000000000000001
This orders the physical card under the product's fulfillment flow. Delivery is pending; the value does not mean it has shipped or arrived. It does not change token_status.
The token is fictional and preserves the API's 20-digit format. Confirm a successful API response before displaying an action as completed.
Card state and transactions
Use current status for new transaction controls. Continue handling already received authorizations, reversals and presentments under their lifecycle rules: a later card status change does not cancel a hold or reverse an existing posting by itself.
Continue with Issuing cards, Authorization flow and Webhook amounts.