Real-Time Authorization and Settlement - DCS Technical Documentation

📄 Guide

The authorization leg needs no synchronous action from you — DCS decides every authorization in real time, and your job is to consume three transaction events well: the authorization result (CARD_TRANSACTION), settlement posting (CARD_TRANSACTION_SETTLEMENT) and the debt alert (CARD_TRANSACTION_DEBT). This page follows a transaction through its life cycle: the check chain DCS runs at authorization, what each event means for the money, and which field to trust when you reconcile. Life-cycle concepts are in The transaction life cycle.

Authorization: the check chain on the DCS side

When the cardholder pays, DCS runs a check chain in real time; failing any link declines the authorization:

Entity status — the company, the employee and the card must all be in a transactable state;
Limit rules — the velocity rules the card falls under are evaluated (rule setup in Setting spend limits);
Available balance — the company’s fund-pool balance must fully cover the authorized amount.

Once the chain passes, DCS places a hold on the amount and consumes the matching limit quota. No money has actually left yet — the transaction shows on the statement as an authorization hold, with postStatus = UNPOSTED. Authorization and settlement are typically hours to days apart.

CARD_TRANSACTION: the authorization-result event

Authorization and release results are pushed through a single webhook, CARD_TRANSACTION — approvals and declines share the event, distinguished by status (A approved / D declined). The data fields:

Field	Description
`cardId`	The card ID
`panLast4`	Last four digits of the card
`status`	Authorization result: `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`	Merchant category code
`merchantName`	Merchant name and location
`merchantCountryCode`	Merchant country code
`transactionId`	The transaction identifier, for matching against records and statements

Example (an approved purchase):

{
  "webhookId": "7800000000000000941", "webhookType": "CARD_TRANSACTION",
  "businessId": "5185740066240791001", "notificationTime": "2026-08-25T02:30:00Z",
  "data": { "cardId": "7830000000000009001", "panLast4": "4417",
    "status": "APPROVED", "direction": "DEBIT",
    "originalAmount": "16.45", "originalCurrency": "USD",
    "postAmount": "16.45", "postCurrency": "USD",
    "transactionCategory": "PURCHASE", "mcc": "5812",
    "merchantName": "ONLINE MERCHANT",
    "merchantCountryCode": "US", "transactionId": "TXN20260802000012345" }
}

Settlement: from hold to posting

When the merchant later submits for clearing, DCS debits the actual settled amount and posts the transaction: postStatus moves from UNPOSTED to POSTED, the transaction lands on the cycle’s statement, and the webhook CARD_TRANSACTION_SETTLEMENT is pushed.

The settled amount can differ from the authorized amount — tips, exchange-rate differences, or the merchant capturing less. Reconcile against the actual amount in the settlement event; never assume it equals the hold placed at authorization. Records and statement queries are in Funding and reconciliation.

What reversals, refunds and debt mean for the money

Settlement is not the only way forward. The following three scenarios carry different fund semantics — do not reuse one bookkeeping rule across them:

Scenario	When it happens	Fund semantics
Reversal / void	After authorization, before settlement	DCS releases the hold back along the original path and restores the consumed limit quota, leaving no residual hold
Refund / chargeback	After settlement	A refund posts as an independent credit in the opposite direction and does not unwind historical limit counters; chargebacks are tracked through the dispute process to closure
Debt	Delayed settlement, merchant over-capture, etc.	The available balance can be driven negative; the account enters a debt state and `CARD_TRANSACTION_DEBT` is pushed — the partner must repay on schedule

Receiving CARD_TRANSACTION_DEBT means the company account is already in a debt state. Top up and repay promptly — fund-pool deposits and balance management are in Funding and reconciliation.

Authorization to posting at a glance

Consuming the events well

All three transaction events are HTTP POST callbacks that DCS pushes to you, sharing one envelope structure plus the same signature-verification, retry and idempotency rules:

Deduplicate on webhookId — process each delivery exactly once no matter how often it is retried;
Read the outcome from status, and join a transaction’s authorization to its settlement via transactionId;
Post to your books from the settlement event; treat the authorization event as hold display only.

Webhook receiver setup, the envelope structure and signature rules are in the Quickstart.

Next steps

Shape approval rates with velocity rules: Setting spend limits
Taking part in verification when an online purchase triggers 3DS: Handling 3DS challenges

​📄 Guide

​Authorization: the check chain on the DCS side

​CARD_TRANSACTION: the authorization-result event

​Settlement: from hold to posting

​What reversals, refunds and debt mean for the money

​Authorization to posting at a glance

​Consuming the events well

​Next steps

📄 Guide

Authorization: the check chain on the DCS side

CARD_TRANSACTION: the authorization-result event

Settlement: from hold to posting

What reversals, refunds and debt mean for the money

Authorization to posting at a glance

Consuming the events well

Next steps