> ## 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.
# Authorization (forwarded decision)
> Where the direction / authType and related enumerations live.
## Authorization: the decision comes back to you
Whether you want to own cardholder limits outright or apply your own risk rules transaction by transaction, authorization forwarding lets you decide, at the moment of every card payment, whether to approve or decline. DCS is a licensed issuer with its own BIN: we forward each real-time network authorization request to you securely and place or release the fund hold on your behalf. **The limits belong to the partner, and so does the authorization decision.**
An authorization happens the instant a cardholder pays. It is a real-time decision and **moves no money**. Funds actually leave the account later, at settlement (see [Transaction records](./transaction) and [Authorization and settlement](./auth-and-settlement)).
***
## Mental model: the life of one authorization
| Role | Who does it | Responsibility |
| --------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| Forward the authorization request | **DCS** | Check card status, then encrypt, sign and push the request to your `authUrl` |
| Make the authorization decision | **Partner** | Verify the signature, decrypt, and approve or decline based on the enterprise security deposit balance and your risk rules |
| Hold or release funds | **DCS** | Act on your decision and answer the card network |
> Under Partner-Managed, the decision always stays with the partner. The forwarding channel adds **two-way RSA encryption and signing**, so no business field ever travels in clear text.
***
## Transaction direction (direction)
| Value | Name | Fund action | Typical scenario |
| ---------- | -------- | -------------------------------- | -------------------------- |
| `OUTGOING` | Outgoing | Hold the corresponding amount | Cardholder makes a payment |
| `INCOMING` | Incoming | Release the corresponding amount | Reversal, refund |
> `INCOMING` authorizations — refunds with an original authorization, reversals — are forwarded through `authUrl` as well. DCS recommends that the partner simply return `00` (approve) for these `INCOMING` authorizations; the partner may still decline in abnormal cases, such as when an `INCOMING` release exceeds the amount currently held.
***
## Authorization type (authType)
`authType` tells you how an authorization record came into being, so you can separate a live authorization from a system back-fill or release.
| Value | Name | Goes through `authUrl` | Description |
| --------------------- | ----------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NORMAL` | Normal authorization | Yes | Standard record created from a real-time channel authorization callback; covers purchases, incremental authorizations, reversals, refunds, cash withdrawals, balance enquiries and every other live scenario |
| `FORCE_AUTH` | Forced authorization | No | Record back-filled by the system: settlement arrives with no matching authorization (an offline transaction, for example), or the settled amount differs from the amount held and the difference must be trued up |
| `EXPIRED_RELEASE` | Expiry release | No | The authorization expired before settlement, and the channel instructed the release of the held funds through a settlement file |
| `STATUS_DIFF_RELEASE` | Status mismatch release | No | Reconciliation correction raised when the channel declined the authorization on timeout while DCS had already approved it |
Only `NORMAL` authorizations are forwarded through `authUrl` for the partner's real-time decision; `FORCE_AUTH` / `EXPIRED_RELEASE` / `STATUS_DIFF_RELEASE` are system-side authorizations that never go through `authUrl` and are only pushed as receipts through the `AUTHORISATION_RESULT` webhook.
The field appears both in the **authorization webhook request** and in the **daily authorization report** (see [Authorization report](../reports/authorization-report)).
the `authType` of an authorization forwarding notification and the sandbox field `APISimulationAuthRequest.authType` (`EXPEND` / `REFUND` / `REVERSAL`) are two independent enumerations, one for real authorization callbacks and one for sandbox triggers. Do not mix them.
***
## Authorization transaction type (transactionType)
`transactionType` describes the nature of the cardholder's transaction, which helps both your authorization decision and your reconciliation breakdown.
| Value | Name | Description |
| ----- | ------------------- | --------------------------------------------- |
| `R` | Card purchase | All card purchase transactions |
| `C` | ATM cash withdrawal | ATM withdrawals and other cash advances |
| `Q` | Enquiry | Enquiry transactions, no movement of funds |
| `P` | Return / refund | All transfers or refunds credited to the card |
***
## Authorization result (responseCode): your reply
Once the partner has decided, it returns the outcome to DCS in `responseCode`:
| `responseCode` | Meaning |
| -------------- | -------------------------------- |
| `"00"` | Approve |
| `"01"` | Decline, insufficient funds |
| `"11"` | Decline, transaction not allowed |
| `"21"` | Decline, no response |
> How it is stored: the authorization forwarding notification is answered with `responseCode`, and the persisted mapping is fixed at `00 → approveFlag=A`, with `01` / `11` / `21` and any other non-`00` value mapping to `approveFlag=D`. `approveFlag` appears in the authorization result webhook and the daily authorization report. In production the synchronous response window is **2.5 seconds**; the partner must reply within it. A timeout is treated as `responseCode=21` / `DAPI_AUTH_ENTERPRISE_TIMEOUT_REJECT`, and a real-time authorization is never retried.
***
## The forwarding notification: who does what on the secure channel
An authorization request is not an ordinary webhook. It travels over a channel protected by **two-way RSA encryption and signing**, with every business field wrapped inside `encryptedData` rather than sent in clear text.
### Prerequisites (partner)
* Your enterprise has been created and both `authUrl` and `externalPublicKey` (your RSA public key) are configured. See [First steps](../../getting-started/first-steps).
* The **IP allowlist** for the authorization forwarding notification is in place.
* You have [issued a card](../cards/card-issuing) successfully.
> The sandbox DCS RSA public key can be copied straight from the [Authentication guide](../../integration-resources/authentication); for the production key, contact the DCS team.
### The round trip
| Step | Who does it | Action |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1. Send the notification | **DCS** | Take the business fields (`authId`, `direction`, `currency`, `amount` and so on), encrypt them with the **partner RSA public key** and Base64-encode the result into `data.encryptedData`; sign with the **DCS RSA private key** and Base64-encode the result into the `X-Auth-Signature` header; POST to your `authUrl` |
| 2. Verify | **Partner** | Verify `X-Auth-Signature` with the **DCS RSA public key**, and decline outright if verification fails |
| 3. Decrypt | **Partner** | Decrypt `data.encryptedData` with your **partner RSA private key** to recover the business fields |
| 4. Decide | **Partner** | Produce a `responseCode` from the enterprise security deposit balance and your risk rules |
| 5. Reply | **Partner** | Encrypt `{authId, responseCode}` with the **DCS RSA public key** into `encryptData`, sign it with your **partner RSA private key** into `signature`, and return both to DCS |
| 6. Execute | **DCS** | Verify and decrypt your reply, then hold funds, release funds or stop the transaction according to `responseCode` |
Signature algorithm: **RSA-SHA256 (`SHA256withRSA`)**, 2048-bit keys, with chunked encryption and decryption (245-byte encryption blocks, 256-byte decryption blocks). Full Java sample code is on the [Authentication guide](../../integration-resources/authentication) page.
> Notification URL template: `https://{domain}/xxx/v1/auth-notification` (the POST that DCS sends to your `authUrl`).
***
## Request and response structure
### Request header
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------ |
| `X-Auth-Signature` | string | Signature: the Base64-encoded result of signing with the DCS private key |
### Request body
| Field | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `webhookId` | string | Unique webhook identifier; use it to deduplicate and avoid processing the same event twice |
| `webhookType` | string | Fixed value `AUTHORISATION` |
| `webhookSubType` | string | Subtype, for example `CREATE` or `UPDATE` |
| `businessId` | string | Identifier of the webhook subject, for example the `authId` |
| `data.authId` | string | Unique number of the authorization event |
| `data.encryptedData` | string | All authorization business fields, encrypted (RSA + Base64); see below |
| `notificationTime` | string | Notification time, `yyyy-MM-dd'T'HH:mm:ss+08:00` (UTC+8) |
**Time zone**: authorization notifications and the reconciliation files both carry UTC+8 (`+08:00`) timestamps; the one exception is the velocity-limit query endpoint, whose date fields are UTC. Store the offset explicitly so that comparisons across endpoints do not drift.
### Business fields inside `encryptedData`
| Field | Type | Description |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `authId` | string | Unique authorization identifier, the key to later transactions and reconciliation |
| `direction` | string | Transaction direction, `OUTGOING` or `INCOMING` |
| `authType` | string | Authorization type; see the enumeration above |
| `outsId` | string | Outstanding (bill) ID, created with the first authorization, links authorization to settlement |
| `originalAuthId` | string | Original authorization being referenced; incremental and reversal scenarios reuse the same Outstanding |
| `customerId` | string | Cardholder user ID |
| `cardId` | string | ID of the card being authorized |
| `currency` | string | Settlement currency, ISO 3-character code |
| `amount` | bigdecimal | Settlement amount |
| `acquirerCurrency` | string | Currency requested by the user (may differ from the settlement currency) |
| `acquirerAmount` | bigdecimal | Amount requested by the user |
| `cardAcceptorIdentification` | string | Merchant number identifying the merchant in the transaction |
| `cardAcceptorNameLocation` | string | Merchant name and address (layout below) |
| `merchantType` | string | Merchant category code (MCC), 4 digits |
| `transactionType` | string | Transaction type `R` / `C` / `Q` / `P`; see the enumeration above |
#### `cardAcceptorNameLocation`
A fixed 40-character text; each segment is left-justified and right-padded with spaces.
##### Visa
| Position | Length | Description |
| -------- | ------ | ---------------------------------------------------- |
| 1–25 | 25 | Merchant name, recognisable to the cardholder |
| 26–38 | 13 | Merchant city |
| 39–40 | 2 | Merchant country, ISO 3166-1 alpha-2 two-letter code |
##### Mastercard
| Position | Length | Description |
| -------- | ------ | ------------------------------------------------------ |
| 1–22 | 22 | Merchant name, recognisable to the cardholder |
| 23 | 1 | Space separator |
| 24–36 | 13 | Merchant city |
| 37 | 1 | Space separator |
| 38–40 | 3 | Merchant country, ISO 3166-1 alpha-3 three-letter code |
### Response body
| Field | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `signature` | string | Signature over the response: the Base64-encoded result of signing with the partner private key |
| `encryptData` | string | Encrypted response data (`authId` + `responseCode`), Base64-encoded |
Structure inside `encryptData`:
| Field | Type | Description |
| -------------- | ------ | ------------------------------- |
| `authId` | string | Authorization ID |
| `responseCode` | string | Authorization result; see above |
the encrypted field on the request side is `data.encryptedData` (nested inside `data`), while on the response side it is `encryptData` (top level, spelled differently). The names do not match, so read each one from its own structure and never treat them as interchangeable.
***
## Minimal authorization request example
```json theme={null}
{
"webhookId": "wh_20260616_0001",
"webhookType": "AUTHORISATION",
"webhookSubType": "CREATE",
"businessId": "auth_8f3c...",
"data": {
"authId": "auth_8f3c...",
"encryptedData": "Base64(RSA(partner public key, business fields JSON))"
},
"notificationTime": "2026-06-16T14:23:05+08:00"
}
```
Response (partner to DCS):
```json theme={null}
{
"encryptData": "Base64(RSA(DCS public key, {\"authId\":\"auth_8f3c...\",\"responseCode\":\"00\"}))",
"signature": "Base64(SHA256withRSA(partner private key, encryptData))"
}
```
> This forwarding notification is a **dedicated secure channel** from DCS to your `authUrl`. It does not use the common response envelope `{code, message, messageDetail, data}` of the `/open-api/` endpoints, which applies only to the calls you initiate (see [Authentication and request conventions](../../integration-resources/authentication)).
***
## A walkthrough of one authorization
Let's tie the fields and the flow together with one realistic purchase: your cardholder carries a USD card and spends 3,000 JPY at a supermarket in Tokyo.
| Moment | What happens | What you receive / return |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| T+0ms | The cardholder taps; the card network routes the request to DCS, which checks the card state (active, not frozen) | — |
| T+\~100ms | DCS encrypts, signs and POSTs to your `authUrl` | Request: `direction=OUTGOING`, `authType=NORMAL`, `transactionType=R`, `acquirerCurrency=JPY`, `acquirerAmount=3000`, `currency=USD`, `amount=20.45`, `merchantType=5411`, `outsId=outs_71ab...` |
| Within T+2.5s | You verify the signature, decrypt, check the user's limit and your risk rules, and decide | Response: `{authId, responseCode: "00"}` (encrypted and signed) |
| T+\~2.5s | DCS freezes 20.45 USD, records 20.45 on Outstanding `outs_71ab...`, answers the network; the purchase succeeds at the till | — |
| Shortly after | DCS pushes the result receipt | `AUTHORISATION_RESULT` webhook: `approveFlag=A`, same `authId` / `outsId` |
| Next day | The authorization lands in the daily authorization report for reconciliation | Report row: `authId`, `approveFlag=A`, amount and merchant fields |
Three details worth noting:
* **The two amount pairs are not duplicates**: `acquirerAmount`/`acquirerCurrency` (3,000 JPY) is what the cardholder spent at the merchant; `amount`/`currency` (20.45 USD) is the settlement view converted at the network rate — freezing, settlement and reconciliation all follow the settlement view.
* **You only decide; you never move funds**: after you return `00`, DCS performs the freeze on the network side. If you return `01` (insufficient funds) or `11` (transaction not allowed), the flow ends at row three: the purchase fails at the till and no funds move.
* **The decision window is 2.5 seconds**: a timeout is treated as `21` (no response) and real-time authorizations are never retried, so keep your whole chain — verify, decrypt, check limits — inside the window.
At this point the money's life cycle is only half done — how the frozen 20.45 USD is actually debited on settlement day, and what happens when the settled amount differs from the frozen amount, is covered in [Authorization and settlement: every scenario](./auth-and-settlement).
***
## What authorization touches
* **Enterprise**: the partner makes the decision, and the hold or release is booked against the **enterprise security deposit** or against the cardholder limits the partner maintains.
* **Card**: every authorization request carries a `cardId`, and the card's activated, frozen or canceled state determines whether the authorization can succeed. Freezing a card triggers the release of its holds.
* **Outstanding**: the bridge between authorization and settlement. The authorization stage accumulates the held amount, and settlement draws it back down to zero. See [Authorization and settlement](./auth-and-settlement).
* **Transaction**: authorization comes first; a single transaction record can reference several `authId` values, and only approved authorizations ever produce a movement of funds.
***
## Next steps
* Want to run an authorization end to end in the sandbox without a card network? Use `POST /open-api/simulation/v1/fund-auth` from [Sandbox: simulating transactions](../sandbox/simulating-transactions) (input `cardId` / `authType` / `amount` / `currency`, returns `approved` plus `errorCode`).
* Want to know how the money settles afterwards? See [Authorization and settlement](./auth-and-settlement).
* Want to configure webhooks and their events? See [Webhooks: configuration](../webhooks/configuration).
* For decline reasons and error codes, see [Authorization declines and error codes](./decline-codes).