Card account APIs

A card account is the bank account a card pays from. Every card is linked to at least one account, and one account can have several cards (e.g. a main card and supplementary cards of other holders). An account can have several currency components; the account is then identified by its account number together with the currency.

The account is mastered by the external system — typically the Core banking system (CBS). The CBS keeps the account, its balance and its status; LightCMS keeps a copy of the information it needs to authorize card transactions and to manage the cards linked to the account. The account APIs are about keeping this copy up to date.

Call	Direction	API contract	Purpose
POST /v3/accountUpdate	External system (CBS) → LightCMS	Provided	CBS reports a change of account balance or status
GET /v3/account/{accountNumber}	LightCMS → External system (CBS)	Required	LightCMS reads the current account state from the CBS
POST /v3/accountUpdateResult	LightCMS → External system	Required	LightCMS asks the external system to resend an update it could not process
GET /v3/accounts/{accountexternalid}/cards	External system → LightCMS	Provided	External system lists the cards linked to an account

How an account gets into LightCMS

There is no separate API to create an account. An account becomes known to LightCMS when the first card linked to it is created (see Card creation) — the card creation request carries the account and its owner. Right after that, LightCMS reads the current state of the account from the CBS (GET /v3/account/{accountNumber}), so the card starts with the actual balance and status of the account.

An account that is not linked to any card is of no interest to LightCMS — updates of such accounts are ignored.

Keeping the account up to date

Whenever the balance or the status of an account changes in the CBS, the CBS should report it via POST /v3/accountUpdate. The update always carries the complete current state of the account — balances and status — not just the change.

• Balances — LightCMS uses the available balance to decide whether a card transaction can be approved. The more promptly the CBS reports balance changes (e.g. incoming payments, direct debits, transfers), the more accurate the authorization decisions are. Card transactions themselves reduce the balance through authorization holds — see Transactions and Holds APIs.
• Status — ACTIVE, BLOCKED or REVOKED. The status controls whether the cards linked to the account can be used (see below). The status should be sent in every update.
• Order of updates — each update carries a timestamp, an ever-increasing value set by the CBS. LightCMS keeps only the newest state, so an update that arrives late (with an older timestamp than the one already processed) does not overwrite newer information. The CBS can therefore safely resend updates.
• Failed processing — a 2xx response means LightCMS has accepted the update. If LightCMS later fails to process it, it calls POST /v3/accountUpdateResult with status: NOT_PROCESSED and the x-idempotency-key of the update — the CBS should then resend the update.

Account status and cards

The account status is reflected on all cards linked to the account:

• Account blocked or revoked — LightCMS blocks every card linked to the account with the reason "blocked by account", so the cards stop authorizing transactions. A card linked also to another account that is still ACTIVE is left alone. The external system is notified about each blocked card (see Card blocking).
• Account active again — LightCMS lifts the "blocked by account" block from the cards. Other blocks on the card (e.g. a card reported as lost by the holder) stay in place — the card becomes usable again only when it has no other active block.

A revoked account blocks its cards in the same way as a blocked account; the cards are not revoked automatically. To terminate the cards of a closed account permanently, revoke them via Card revocation.

Finding the cards of an account

GET /v3/accounts/{accountexternalid}/cards lists all cards linked to an account, whatever their status — e.g. to show a call center operator all cards drawing on an account, or to check which cards are affected before the account is blocked or closed.