Card lifecycle

A card is the tenant's physical or virtual payment instrument. This page describes how a card moves from creation to a terminal state, as the caller observes it. How to call each step is in endpoints → cards.

Card state machine

The platform does not store card status — each read reports the card's current state, and an operation that isn't valid for the current state is rejected with CAR009001.

DAMAGED cancel is a special case: calling cancel with reason = DAMAGED on a PROVISIONED, ACTIVE, or LOCKED card does not move it to CANCELED. The existing card stays ACTIVE and a replacement card is issued; the response reflects the original card's unchanged state.

State descriptions

State	Description	Available transitions
NEW	Physical card requested; not yet provisioned. PAN/expiry may not be available yet.	PROVISIONING (async)
PROVISIONING	The card is being provisioned (intermediary; asynchronous).	PROVISIONED (async)
PROVISIONED	Ready to activate. Applies to physical cards; virtual cards skip to ACTIVE.	ACTIVE, CANCELED
ACTIVE	Active and usable for transactions.	LOCKED, CANCELED
LOCKED	Temporarily locked; cannot be used for transactions.	ACTIVE, CANCELED
CANCELED	Permanently cancelled; cannot be used.	— (terminal)

Card formats and initial states

Format	Initial state	Notes
PHYSICAL	NEW	Requires activation after provisioning
VIRTUAL	ACTIVE	Usable immediately on creation
PHYSICAL_AND_VIRTUAL	ACTIVE	Virtual component active immediately; physical follows

End-to-end caller journey

A typical journey: create → activate → lock → unlock → cancel.

State guard errors

An operation that isn't valid for the card's current state is rejected:

Operation	Required state	Error on violation
activate	PROVISIONED	409 CAR009001
lock	ACTIVE	409 CAR009001
unlock	LOCKED	409 CAR009001
cancel	PROVISIONED, ACTIVE, or LOCKED	409 CAR009001
updateTransactionSettings	any non-terminal	409 CAR009001