UDA endpoints — cards

How to call the cards routes. The formal schema is the OpenAPI specification (openapi/source/connector/cards/); this page is the call contract. Internal processing is in the architecture reference; caveats in the implementation notes.

All routes require a bearer token and party context (partyId), which the connector uses to resolve the customer in ULTRACS. cardId in the path is the Ark card id.

Method	Path	Code	Purpose
GET	/v1/cards	200	List the party's cards
GET	/v1/cards/{cardId}	200	Card detail
GET	/v1/cards/{cardId}/transaction-settings	200	Current transaction controls
POST	/v1/cards	201	Order a card
POST	/v1/cards/{cardId}/lock	204	Lock a card
POST	/v1/cards/{cardId}/unlock	204	Unlock a card
POST	/v1/cards/{cardId}/activate	200	Activate a card
POST	/v1/cards/{cardId}/cancel	200	Cancel or replace a card
PATCH	/v1/cards/{cardId}/transaction-settings	204	Update transaction controls

Notes for callers

• Order (POST /v1/cards) takes accountId (an Ark account id the card links to) and type (PHYSICAL / VIRTUAL / PHYSICAL_AND_VIRTUAL). It always orders a brand-new card; BIN, brand, collection method, and expiry come from the account's configured card product — the caller cannot choose them. The response carries cardId, vendorId, accountId, expiry, and cardHolderName (the embossed line 1).
• Card type and brand are restricted: the connector emits only VISA / MASTERCARD brands (the contract's DEBIT is never returned), and physical/virtual/hybrid types. The response does not include a card-capability features array even though the schema allows one (see the implementation notes).
• Activate takes an optional expiry (MM/YY) as proof of possession of a physical card, and returns the refreshed card detail.
• Lock / unlock / activate only succeed when ULTRACS reports the card supports that action; a card in the wrong state is rejected with 409. The full card state machine is in the lifecycle reference.
• Cancel (POST /v1/cards/{cardId}/cancel) takes reason: CANCEL stops the card with no replacement; LOST / STOLEN / DAMAGED order a replacement card. Note the response is the original card's refreshed detail, not the replacement, and the original card is not stopped on a replacement (see the implementation notes).
• Transaction settings are the ten domestic/international controls (online, mobile-wallet, ATM, physical, tap-&-go). PATCH is partial (one or more controls) and only works on an active card (409 otherwise). Enabling a tap-&-go control while the matching physical-purchases control is off is rejected by ULTRACS as 400 CAR000006 (see the implementation notes).
• Change-PIN is not available — the OpenAPI contract reserves an updatePin operation, but the connector exposes no such route (see the implementation notes).

Errors

HTTP	Code	When
400	GEN000000	request body/params fail schema validation
400	CAR000004	invalid card control (unknown feature, missing field — duplicate controls also collapse to this code; the dedicated CAR000005 DUPLICATE_CONTROL_DEFINED constant exists but is unused)
400	CAR000006	tap-&-go enabled while the matching physical-purchases control is disabled (ULTRACS-enforced)
401	CAR001001	order: the linked account isn't owned by the caller
403	CAR003003	the card isn't owned by the caller; list: a returned card/account has no local mapping
404	PAR004001	no party mapping for the caller (ClientAuthManager.getClientKey → PARTY_NOT_FOUND)
404	CAR004001	no card mapping for cardId; order: no card product matches the requested type
404	CAR004003	transaction settings not found for the card
404	CAR004004	the card's linked account has no local mapping
409	CAR009001	lock/unlock/activate/cancel: card is in an invalid state for the action; update settings: card is not ACTIVE
500	CAR100001	list: a card has no matching card product
500	CAR100002	unmappable status/type/brand, missing core-banking number, or a failure during cancel
500	GEN100001	an ULTRACS fault with no mapping (handleUltracsError falls back to DOWNSTREAM_CONNECTOR_ERROR — only the update-settings operation maps faults — see the implementation notes)