UDA connector — lifecycle
The behaviour-over-time of the connector's stateful concepts. For how to call the routes see the endpoints reference; for internals see the architecture reference; for caveats see the implementation notes.
The connector is mostly a thin pass-through to ULTRACS, so most resources have no state of their own.
Two concepts have a genuine journey: a card's status (a state machine) and the party
provisioning sequence. Accounts, payees, scheduled payments, and statements are plain CRUD / read
models (a scheduled payment is always reported ACTIVE), so they have no lifecycle here.
Card status
A card's status is owned by ULTRACS and mapped to the Ark status the connector returns. The
connector never drives transitions directly — it asks ULTRACS to act and reflects the result — and
each write is gated by ULTRACS, which permits it only when the card is in a suitable state; a card
in the wrong state is rejected with 409 CAR009001 (INVALID_CARD_STATE_ERROR via
conflictException).
Ark status | ULTRACS Status | Meaning |
|---|---|---|
NEW | NotIssued | ordered, not yet issued |
PROVISIONED | IssuedInactive | issued, awaiting activation |
ACTIVE | Active | usable |
LOCKED | Restricted | temporarily blocked |
CANCELED | Lost, Stolen, Fraud, Closed | permanently stopped |
The contract also defines a
PROVISIONINGstatus, but no ULTRACS status maps to it, so the connector never returns it (see the implementation notes).
| Operation | Route | Precondition | Result |
|---|---|---|---|
| Order | POST /v1/cards | account owns a matching card product | a new card (virtual/hybrid issue ACTIVE; physical issue NEW/PROVISIONED) |
| Activate | POST /v1/cards/{id}/activate | card awaiting activation | ACTIVE |
| Lock | POST /v1/cards/{id}/lock | card ACTIVE | LOCKED |
| Unlock | POST /v1/cards/{id}/unlock | card LOCKED | ACTIVE |
| Cancel | POST /v1/cards/{id}/cancel (reason: CANCEL) | card active or locked | CANCELED |
Replacement is not a status transition. POST /v1/cards/{id}/cancel with reason LOST /
STOLEN / DAMAGED orders a new card and leaves the original card untouched (it is not stopped),
returning the original card's refreshed detail — see
the implementation notes. Transaction
controls (PATCH /v1/cards/{id}/transaction-settings) are only accepted while the card is ACTIVE
(else 409).
Party provisioning
The connector does not track a party status of its own — the Ark platform owns the party state
machine (PROSPECT → ACTIVE → …); here the connector just keeps an id mapping (Ark party id ↔ the
ULTRACS client identifier), soft-deletable. What the connector owns is the provisioning
sequence that creates the ULTRACS client and records the mapping:
This sequence is not transactional — a failure after the client is created at the core banking
system can leave an orphaned ULTRACS client or a half-finalised record
(see the implementation notes). A party can
also be provisioned by the internal admin path (PUT /admin/mapping/CUSTOMER/{arkId}), which binds an
existing ULTRACS client to an Ark id without creating one (see the admin architecture).