Platform endpoints — cards

How to call the cards routes. The formal schema is the OpenAPI specification (openapi/source/platform/cards/cards.yml); this page is the call contract. Card state and lifecycle are in card lifecycle.

Auth

All routes require a bearer token (B2B JWT) with the CLIENT role and an ACTIVE party context. Unauthenticated callers receive 401 GEN001002 (INVALID_TOKEN); forbidden callers receive 403 AUT003001 (cross-tenant) or 403 PAR003001 (party not authorised). The cards controller does not raise CAR001001 / CAR003003 itself — those constants exist but the auth chain in front of the controller emits the generic auth codes.

Route summary

Method	Path	Code	Purpose
GET	/v1/cards	200	List the party's cards
GET	/v1/cards/{cardId}	200	Card detail
POST	/v1/cards	201	Issue a card on an account
POST	/v1/cards/{cardId}/activate	200	Activate a provisioned card
POST	/v1/cards/{cardId}/cancel	200	Cancel or replace a card
POST	/v1/cards/{cardId}/lock	204	Temporarily lock a card
POST	/v1/cards/{cardId}/unlock	204	Remove a lock from a card
PATCH	/v1/cards/{cardId}/update-pin	204	Update card PIN
GET	/v1/cards/{cardId}/transaction-settings	200	Read transaction controls
PATCH	/v1/cards/{cardId}/transaction-settings	204	Update transaction controls

Notes for callers

GET /v1/cards — list

Returns the party's cards, or { cards: [] } if there are none. If a backing-provider call errors, the whole request fails rather than returning a partial list.

POST /v1/cards — create

Takes an accountId in the body. The platform verifies that the product is mapped for the caller's clientId/brandId before issuing. Both pre-flight checks can fail before the provider is called (see Errors below).

Card formats and their immediate states:

• PHYSICAL — starts NEW; requires activation after provisioning.
• VIRTUAL — active immediately upon creation.
• PHYSICAL_AND_VIRTUAL — active immediately.

POST /v1/cards/{cardId}/activate — activate

Requires the card to be in state PROVISIONED. Returns the full card detail (200) after activation. Returns 409 CAR009001 if the card is not in the required state.

POST /v1/cards/{cardId}/cancel — cancel or replace

Takes a cancellation reason: CANCEL, LOST, STOLEN, or DAMAGED. CANCEL/LOST/STOLEN move the card to CANCELED. DAMAGED is the replacement path — the card stays ACTIVE and a replacement is issued (no state transition for the original card). Returns full card details (200).

POST /v1/cards/{cardId}/lock and unlock

Both return 204 No Content. Returns 409 CAR009001 if the card is not in the required state (lock requires ACTIVE, unlock requires LOCKED).

PATCH /v1/cards/{cardId}/update-pin — update PIN

Sends { pin: "..." } in the body. Returns 204 No Content. The pin field is a beta operation pending end-to-end encryption; use with awareness of your security posture.

GET /v1/cards/{cardId}/transaction-settings

Returns CardTransactionControls — a controls[] array of { feature, enabled } pairs. Read-only; nothing is changed.

PATCH /v1/cards/{cardId}/transaction-settings

Updates transaction controls on the card. The platform validates the request body before applying the change:

• CAR000004 — unrecognised feature value.
• CAR000005 — the same feature appears more than once in controls[].
• CAR000006 — DOMESTIC_TAP_GO or INTERNATIONAL_TAP_GO is enabled but PHYSICAL_PURCHASES is disabled (TAP_AND_GO requires physical purchases).

Returns 409 CAR009001 if the card is not in a state that permits updating settings (e.g. cannot update settings on a canceled card).

Errors

HTTP	Code	When
400	GEN000000	Request body or params fail schema validation
400	CAR000004	Unrecognised card control feature
400	CAR000005	Duplicate card control feature in controls[]
400	CAR000006	TAP_AND_GO enabled while PHYSICAL_PURCHASES is disabled
401	GEN001002 / GEN001006 / AUT001001	Missing/invalid bearer; missing role; missing tenant
403	AUT003001 / PAR003001	External-app access denied; party not authorised
404	CAR004001	Card not found
404	CAR004003	Card transaction settings not found
404	CAR004004	Account not found (during POST /v1/cards pre-flight)
404	CAR004005	Product mapping not found for the account's product (during POST /v1/cards)
409	CAR009001	Invalid card state for activate / lock / unlock / cancel
409	CAR009001	Invalid card state for update transaction settings
500	CAR100001	Internal server error
500	CAR100002	Unexpected error from the core banking provider