Authorization (forwarded decision) - DCS Technical Documentation

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 and Authorization 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).

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.
The IP allowlist for the authorization forwarding notification is in place.
You have issued a card successfully.

The sandbox DCS RSA public key can be copied straight from the Authentication guide; 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 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

{
  "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):

{
  "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).

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.

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.
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 (input cardId / authType / amount / currency, returns approved plus errorCode).
Want to know how the money settles afterwards? See Authorization and settlement.
Want to configure webhooks and their events? See Webhooks: configuration.
For decline reasons and error codes, see Authorization declines and error codes.

​Authorization: the decision comes back to you

​Mental model: the life of one authorization

​Transaction direction (direction)

​Authorization type (authType)

​Authorization transaction type (transactionType)

​Authorization result (responseCode): your reply

​The forwarding notification: who does what on the secure channel

​Prerequisites (partner)

​The round trip

​Request and response structure

​Request header

​Request body

​Business fields inside encryptedData

​cardAcceptorNameLocation

Visa

Mastercard

​Response body

​Minimal authorization request example

​A walkthrough of one authorization

​What authorization touches

​Next steps

Authorization: the decision comes back to you

Mental model: the life of one authorization

Transaction direction (direction)

Authorization type (authType)

Authorization transaction type (transactionType)

Authorization result (responseCode): your reply

The forwarding notification: who does what on the secure channel

Prerequisites (partner)

The round trip

Request and response structure

Request header

Request body

Business fields inside `encryptedData`

`cardAcceptorNameLocation`

Response body

Minimal authorization request example

A walkthrough of one authorization

What authorization touches

Next steps