> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions · Overview

> Real-time authorization completes on the DCS side with results pushed as CARD_TRANSACTION; 3DS challenges follow one of three modes, with the authenticate endpoint returning OOB results; settlement and debt arrive as events.

## 📄 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](../basic-concepts/transaction-lifecycle).

## 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](./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`.

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

## 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](./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](./spend-limits)
* Post-settlement records and statements: [Funding and reconciliation](./funding-and-reconciliation)
* In this group: [Real-time authorization and settlement](./realtime-authorization) · [Handling 3DS challenges](./3ds-challenges)