Skip to main content

Account lifecycle

How an account moves through its lifecycle, from the platform caller's perspective. For how to call each step see endpoints → accounts.

What the platform owns​

The platform has no account state machine of its own — there is no platform-side close/terminate operation. An account's open/closed state (openStatus: OPEN / CLOSED) is reported by the backing provider and relayed in the GET /v1/accounts and GET /v1/accounts/{accountId} responses; the platform does not manage it.

End-to-end journey​

Signatory management​

openStatus​

The only account state the platform surfaces is the openStatus field on the account:

There is no platform route to close an account; closure happens at the backing bank, outside the platform, and surfaces as openStatus: CLOSED.

Journey summary​

  1. Open (POST /v1/accounts) — the platform checks the product is mapped for your tenant (404 ACC004004 if not) and opens the account.
  2. Manage signatories — add (POST …/signatories) and remove (DELETE …/signatories/{partyId}); each target party must be ACTIVE. The last active signatory cannot be removed (409 ACC009002).
  3. Set alias (PUT …/alias) — fails with 409 ACC009001 if the alias can't be edited.
  4. Transact (GET …/transactions, GET …/transactions/{txId}) — read-only; transactions are PENDING or POSTED with opaque transactionId handles.
  5. Closure — not a platform operation; openStatus: CLOSED is reported when the account is closed at the bank.

Guards and edge cases​

  • Last-signatory guard (concurrent-delete race). The last-signatory check is a read-then-write with no optimistic lock. Two concurrent deletes on a two-signatory account can both pass the check and both succeed, leaving the account with zero active signatories. There is no mitigation today.
  • signatory: false. A party linked with signatory: false is a statement-only recipient: it does not count towards the last-signatory guard and cannot authorise transactions.
  • requiredSignaturesForPayment > number of signatories. Payments queue indefinitely; add more signatories via POST …/signatories.