Transactions · Overview - DCS Technical Documentation

📄 Guide

Unlike issuing or transfers, the transaction leg needs no synchronous action from you — authorization completes on the DCS side in real time, and your job is to consume the events well: record authorization results, take your configured part in 3DS challenges, and update your books when settlement and debt events arrive. The life-cycle concepts are in The transaction life cycle.

Real-time authorization

When the cardholder pays, DCS checks the entity’s status, the velocity rules and the available balance in real time, and pushes the webhook CARD_TRANSACTION (status=APPROVED / DECLINED). Key payload fields:

Field	Description
`cardId` / `panLast4`	The card ID and last four digits
`status`	`APPROVED` / `DECLINED`
`direction`	Fund direction (`DEBIT` for purchases)
`originalAmount` / `originalCurrency`	Original amount and currency
`postAmount` / `postCurrency`	Settlement amount and currency
`transactionCategory`	The nature of the transaction (e.g. `PURCHASE`)
`mcc` / `merchantName` / `merchantCountryCode`	Merchant details
`transactionId`	The transaction identifier, for matching against records and statements

Handling 3DS challenges

When an online purchase triggers 3DS, DCS pushes the webhook AUTHORISATION_3DS_CHALLENGE; handle it per the mode configured at onboarding (the mode is set per card BIN range on the issuing side; the division of work is detailed in Handling 3DS challenges):

Mode	Challenge delivery	What you do
Issuer OTP	DCS sends the code to the cardholder directly (email / SMS)	Nothing — you are not involved
OTP_DELEGATE	The webhook carries the encrypted code and the cardholder’s phone / email (AES-GCM ciphertexts sharing one `iv`)	Decrypt and deliver the code through your own channel; no result callback
OOB	The webhook carries the basic transaction details	Notify the cardholder’s app → they verify in-app → call authenticate with the result

Key challenge fields: challengeId, status, cardId / organizationId, expiryTime, the amount and currency, merchant details (merchantName / merchantCountryCode / mcc) and challengeFlowType (the mode); OTP_DELEGATE additionally carries encryptedOtpPasscode / phoneNumber / email (ciphertexts) and iv. The OOB callback: POST /open-api-corp/card3ds/v1/authenticate — send challengeId (from the challenge event) + action (APPROVE / REJECT) + optional operateTime. Repeating the same result is idempotent; calling it against an OTP_DELEGATE challenge returns CARD_3DS_CHALLENGE_NOT_FOUND.

Challenges are valid for about 300 seconds and time out as rejected; the result-confirmation endpoint applies to OOB mode only.

Settlement and debt

Settlement: card settlement pushes CARD_TRANSACTION_SETTLEMENT; the transaction moves from an authorization hold (UNPOSTED) to posted (POSTED) and lands on the cycle’s statement — records and statement queries are in Funding and reconciliation.
Debt: delayed settlement or merchant over-capture can drive the available balance negative; the account enters a debt state and CARD_TRANSACTION_DEBT is pushed — remind the customer to repay on schedule (repayment state in the statement’s paymentStatus).

Next steps

Shape approval rates with velocity rules: Setting spend limits
Post-settlement records and statements: Funding and reconciliation
In this group: Real-time authorization and settlement · Handling 3DS challenges

​📄 Guide

​Real-time authorization

​Handling 3DS challenges

​Settlement and debt

​Next steps

📄 Guide

Real-time authorization

Handling 3DS challenges

Settlement and debt

Next steps