Skip to content
rigid.fi

Transition card lifecycle state

POST/v1/cards/{id}/transitions

Requires an API client bearer token.

Transition a card through its legal state machine (unactivated → active, active → suspended, etc.). Requires an Idempotency-Key header. Emits card.transition.

Parameters

Path parameters

NameRequiredDescription
idrequired

Header parameters

NameRequiredDescription
Idempotency-Keyrequired

Client-chosen. An identical retry with the same key returns the stored response; reusing the key with a different payload returns 409.

Request body

to"unactivated" | "active" | "suspended" | "terminated" | "lost" | "stolen"required

Example

curl -X POST https://api.rigid.fi/v1/cards/{id}/transitions \
  -H "Authorization: Bearer $RIGID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "to": "unactivated"
}'

Responses

200

Updated card after the transition.

idstring (uuid)required
programme_idstring (uuid)required
card_product_idstring (uuid)required
cardholder_idstring (uuid)required
pan_refstringrequired
last4stringrequired
iinstringrequired
exp_monthintegerrequired
exp_yearintegerrequired
state"unactivated" | "active" | "suspended" | "terminated" | "lost" | "stolen"required
controlsarray of one ofrequired
+ show properties

One of

mcc_allow

kind"mcc_allow"required
valuesarray of stringrequired

mcc_deny

kind"mcc_deny"required
valuesarray of stringrequired

country_allow

kind"country_allow"required
valuesarray of stringrequired

country_deny

kind"country_deny"required
valuesarray of stringrequired

channel_allow

kind"channel_allow"required
valuesarray of stringrequired

channel_deny

kind"channel_deny"required
valuesarray of stringrequired

per_txn_cap

kind"per_txn_cap"required
amountstringrequired

per_day_cap

kind"per_day_cap"required
countintegerrequired

per_day_amount_cap

kind"per_day_amount_cap"required
amountstringrequired
funding_account_idstring | nullrequired
cvk_generationstringrequired
created_atstringrequired
currency"EUR" | "GBP" | "USD"required
cardholder_namestringrequired
cardholder_emailstringrequired
400

Validation error — including illegal_transition (the requested from→to transition is not permitted), or a missing/blank Idempotency-Key header

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
401

Authentication required

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
403

Forbidden — the caller may not act on this programme, or (code `live_mode_card_read_only`) live mode refuses every legal move except one into terminated, lost or stolen and the freeze active → suspended, pending scheme certification

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
404

Card not found

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
409

Idempotency-Key reused with a different payload

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
500

Internal server error

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring