Skip to content

Transactions and Holds APIs

A card payment happens in two stages:

  1. Authorization — at the moment of payment, the merchant asks whether the card may pay the amount. LightCMS decides in real time and, if it approves, the amount is held on the account (reserved) so it cannot be spent twice.
  2. Clearing — typically a day or more later, the merchant's bank submits the transaction for settlement. The final amount is posted to the account and the hold is released.

LightCMS authorizes card transactions itself, based on its copy of the account balance (see Card account APIs). The external system — typically the Core banking system (CBS) — keeps the account, so it has to learn about every hold to keep the account balance correct. The Transactions and Holds APIs cover this exchange, and let the external system follow every card transaction.

Call Direction API contract Purpose
POST /v3/holdEventRequest LightCMS → External system (CBS) Required LightCMS asks the CBS to create, modify or cancel a hold
POST /v3/holdEventResponse External system (CBS) → LightCMS Provided CBS confirms a hold operation, or reports a change of a hold on its own
POST /v3/transactionEvent LightCMS → External system Required LightCMS notifies the external system about a card transaction

Holds

How a hold is created, changed and cancelled

The authorization decision is made by LightCMS alone — the CBS is not asked during the payment, so the payment is never delayed by the CBS. Once the payment is approved, LightCMS asks the CBS to reflect it on the account:

  • CREATE — a new approved authorization; the CBS reserves the amount on the account.
  • MODIFY — the amount of an existing authorization changed, e.g. an incremental authorization at a hotel or a partial reversal; the CBS changes the reserved amount.
  • CANCEL — the hold is no longer needed, e.g. the merchant reversed the payment. LightCMS also cancels a hold automatically when it expires without being cleared; the expiry is set at authorization.

Each operation is a request to the CBS (POST /v3/holdEventRequest), and the CBS confirms each of them by calling POST /v3/holdEventResponse. The request is asynchronous — the CBS acknowledges receipt immediately and confirms the processed operation later.

Identifying a hold

A hold carries identifiers of both sides:

  • LightCMS sends its own hold ID and the card processor's transaction ID with every request.
  • On CREATE the CBS assigns its own hold ID and returns it in the confirmation. LightCMS then uses it in every MODIFY and CANCEL of the same hold, so the CBS can always find the hold by its own ID.

Order of hold operations

LightCMS guarantees the order the CBS receives the operations in:

  • The operations of one account are delivered one at a time, in the order they happened.
  • A MODIFY or CANCEL is sent only after the CBS has confirmed the CREATE of that hold — the CBS never receives a change of a hold it does not know yet.

Confirmations keep the balance right

Every confirmation carries the current balance of the account after the operation was applied. LightCMS uses it to update its copy of the balance for further authorizations:

  • Until the CBS confirms a hold, LightCMS subtracts the held amount from the available balance itself, so approved but not yet confirmed payments are never spent twice.
  • Once the CBS confirms the hold, the balance reported by the CBS already includes it, and LightCMS relies on the CBS balance.

Prompt confirmations therefore matter: the sooner the CBS confirms, the sooner LightCMS works with the CBS's own view of the account.

Changes of a hold made by the CBS

The CBS can also change a hold on its own and report it with POST /v3/holdEventResponse — with no preceding request from LightCMS:

  • CLEARING — the transaction linked to the hold has been posted to the account; the hold is consumed by the posting.
  • EXTCANCEL — the CBS cancelled the hold on its own decision.
  • EXTMODIFY — the CBS changed the hold. LightCMS treats it as a cancellation of its own hold and relies on the balance reported by the CBS from then on.

As with confirmations, these reports carry the current account balance.

Transaction notifications

LightCMS notifies the external system about every card transaction via POST /v3/transactionEvent — typically to feed transaction history in internet or mobile banking, push notifications to the cardholder, monitoring or accounting.

  • A notification is sent every time the transaction changes — when it is authorized or declined, when its amount changes, when it is reversed, posted, disputed, and also when LightCMS adds more information to it later (e.g. merchant details or the exchange rate). Each notification carries the complete current state of the transaction, so the latest one always replaces the previous ones.
  • The authorization and the clearing of one payment are one transaction with one LightCMS transaction ID — the external system follows the transaction through its stages under the same ID.
  • Declined authorizations are notified as well, so the cardholder can be told why a payment failed.
  • Transactions are enriched with merchant data — a clean merchant name, logo, category and location — that make the transaction easy to recognize for the cardholder. Tokenized transactions also identify the token used (see Card token APIs).

The notification is fire-and-forget — the external system only acknowledges receipt; no result callback is expected.