Simulating Transactions · Overview - DCS Technical Documentation

Exercise the whole flow in the sandbox before you go live

Without moving real money or touching real cardholders, you can assemble a complete KYC → deposit → authorized spend flow in the sandbox and validate your integration logic ahead of time (the KYC flow, balance movements, Webhook and WebSocket delivery handling). As a licensed issuer with its own BINs, DCS provides a set of sandbox simulation endpoints so that your integration is solid well before it reaches the card networks.

The simulation endpoints are for sandbox and non-production environments only. All four simulation/* endpoints belong to the “open API simulator” group; never call them in production.

What you can simulate

The DeCard-Managed model offers four simulation endpoints across three capabilities. Requests and responses for each are covered below in “Endpoint reference”.

Capability	Endpoint	What it simulates	Real capability it maps to
KYC simulation token	`POST /simulation/v1/generate-kyc-token`	Issues a KYC simulation token for a given user so you can walk the KYC flow in the sandbox	KYC / H5 guidance page
Deposit simulation (FOMO)	`POST /simulation/v1/deposit`	Simulates an on-chain crypto deposit arriving (FOMO channel), triggering the user balance and deposit flow	Crypto deposits
Authorization simulation (spend / refund / reversal)	`POST /simulation/v2/fund-auth` (uses `cardId`)	Simulates a card authorization request, as a spend, a refund or a spend reversal	Authorizing Transactions

Sandbox simulation endpoints and their effects

The DeCard-Managed model has no concept of on-chain collateral or payment routing (transfers), so there are no matching collateral-funding / transfer-transactions simulations. Authorization is decided in a single pass inside the system, so there are also no standalone settlement / authorization-updates / authorization-reversals / 3ds-challenges simulation endpoints. For how to test those scenarios, see “What is out of scope” below.

Prerequisites

Item	Description	Who provides it
Sandbox API credentials	`ApiKey` + `SecretKey`, used for authentication (`X-DAPI-API-KEY` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE` / `X-DAPI-SIGN`)	DCS
A registered user	Complete user registration in the sandbox first and keep the `externalUserId`	Partner
A usable card	Walk KYC with the simulation token, then apply for a card and keep the `cardId`	Partner
Webhook / WebSocket subscription	Configure callbacks and real-time delivery so you can observe the events the simulations produce	Partner

Your Enterprise account is active. If you do not have credentials yet, see First Steps and the authentication guide.
Every request must carry the signature headers described in the authentication guide. The curl examples on this page omit some header details and focus on the business fields and the sandbox host.
Every externalUserId, cardId, last-4 value, deposit address, token and YOUR_API_KEY in the examples is a placeholder or masked value. Never put real end-user PII or real keys into requests or logs.

Sandbox host

Environment	Base URL
Sandbox	`https://api.thedecard-sandbox.com`
Production	`https://api.thedecard.com`

The simulation endpoints exist in the sandbox only.

Getting started

Get sandbox access. Request sandbox ApiKey / SecretKey from DCS. The simulation endpoints are available in the sandbox only.
Create a test user and a test card. Use POST /simulation/v1/generate-kyc-token to mint a KYC simulation token for the user, walk KYC, then apply for a card and keep the cardId. See Signing Up a Customer and Managing Cards · Issuing Cards.
Set up Webhook and WebSocket. Simulations fire the same events as real transactions, so having your receivers ready makes them easy to observe. See Webhook + WebSocket.
Run the simulations. Start with POST /simulation/v1/deposit to simulate an incoming deposit, then POST /simulation/v2/fund-auth to simulate a spend, and watch the balance and transaction records change.

Endpoint reference

All endpoints share the site-wide response envelope { code, message, messageDetail, data } — with no success boolean; the success code literal is code = SYS_SUCCESS. Use code == SYS_SUCCESS to decide whether the request was accepted, and the fields inside data to read the business outcome. messageDetail is an object intended for display to the end user, with seven optional sub-fields: message / title / type / icon / action / linkTitle / linkUrl; usually each sub-field is an empty string.

1 · Generate a KYC simulation token

Mints a KYC simulation token for a given user so you can walk the KYC flow in the sandbox.

POST /simulation/v1/generate-kyc-token

{
  "externalUserId": "usr_xxxxxxxx"
}

Field	Type	Required	Description
`externalUserId`	string	Yes	External user ID

Successful response:

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": {},
  "data": {
    "token": "<KYC simulation token>"
  }
}

Field	Description
`data.token`	KYC simulation token, used to walk the KYC flow in the sandbox

2 · Simulate a deposit (FOMO channel)

Simulates an on-chain crypto deposit arriving (FOMO channel), the sandbox equivalent of faking a payment into a deposit address, which triggers the user balance and deposit flow. This simulates an on-chain arrival, not a fiat top-up.

POST /simulation/v1/deposit

{
  "chain": "Polygon",
  "currency": "USDC",
  "amount": 100.0,
  "address": "<on-chain deposit address>"
}

Field	Type	Required	Description
`chain`	string	Yes	Chain name, one of `Ethereum` / `SOL` / `BASE` / `Polygon` / `TRON`
`currency`	string	Yes	Currency, either `USDC` or `USDT`
`amount`	number	Yes	Deposit amount (decimal)
`address`	string	Yes	Deposit address. The format depends on `chain`: EVM chains (Ethereum/Polygon/BASE) start with `0x`; Solana (`SOL`) is base58; TRON starts with `T`. Use the user’s actual deposit address on that chain

The chain and token matrix supported by this endpoint is exactly the one in the table above: 5 chains (Ethereum / SOL / BASE / Polygon / TRON) × 2 stablecoins (USDC / USDT). This matrix describes sandbox simulation and may differ from production coverage. Real deposit addresses and the chain and currency configuration belong to the deposits and withdrawals area (crypto deposits) and are not covered here.

Successful response (no business payload, data is null):

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": {},
  "data": null
}

3 · Simulate an authorization (spend / refund / reversal)

Simulates a card authorization request. The DeCard-Managed model covers spend, refund and spend reversal with a single fund-auth endpoint plus the authType enum. The card is identified precisely by cardId (not by the last 4 digits of the card number, which can be ambiguous when one user holds several cards). Request:

POST /simulation/v2/fund-auth

{
  "externalUserId": "usr_xxxxxxxx",
  "cardId": "card_xxxxxxxx",
  "authType": "EXPEND",
  "amount": 12.50,
  "currency": "USD"
}

Field	Type	Required	Description
`externalUserId`	string	Yes	External user ID
`cardId`	string	Yes	Card ID
`authType`	string	Yes	Authorization type (see the enum table below)
`amount`	number	Yes	Amount (decimal), in major currency units
`currency`	string	Yes	Transaction currency, a standard code such as `USD` / `RMB` / `SGD` / `EUR` / `JPY`

authType enum:

Value	Meaning
`EXPEND`	Spend
`REFUND`	Refund
`REVERSAL`	Spend reversal

The DeCard-Managed model covers spend, refund and reversal through this one fund-auth endpoint plus authType. There are no separate settlement, authorization reversal or authorization update endpoints; concepts such as settle / reverse-hold / partial-reversal / tip-update do not exist in the DeCard-Managed model.

Successful response:

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": {},
  "data": {
    "approved": false,
    "errorCode": "<error code when declined>"
  }
}

Field	Type	Description
`data.approved`	boolean	Whether the authorization was approved
`data.errorCode`	string	Error code (returned when the authorization is declined)

code == SYS_SUCCESS only means the simulation request was accepted correctly; it does not mean the authorization was approved. Read data.approved for the authorization outcome.

Common patterns

Run the minimal deposit → spend → check balance loop

# 1. Simulate an on-chain deposit arriving (USDC on Polygon)
curl -X POST https://api.thedecard-sandbox.com/simulation/v1/deposit \
  -H "Content-Type: application/json" \
  -H "X-DAPI-API-KEY: YOUR_API_KEY" \
  -H "X-DAPI-TIMESTAMP: MILLIS_TIMESTAMP" \
  -H "X-DAPI-SIGN: YOUR_SIGNATURE" \
  -H "X-DAPI-NONCE: 12345" \
  -d '{
    "chain": "Polygon",
    "currency": "USDC",
    "amount": 100.0,
    "address": "<on-chain deposit address>"
  }'

# 2. Simulate a spend authorization
curl -X POST https://api.thedecard-sandbox.com/simulation/v2/fund-auth \
  -H "Content-Type: application/json" \
  -H "X-DAPI-API-KEY: YOUR_API_KEY" \
  -H "X-DAPI-TIMESTAMP: 1760943263227" \
  -H "X-DAPI-NONCE: 12346" \
  -H "X-DAPI-SIGN: YOUR_SIGNATURE" \
  -d '{
    "externalUserId": "usr_xxxxxxxx",
    "cardId": "card_xxxxxxxx",
    "authType": "EXPEND",
    "amount": 12.50,
    "currency": "USD"
  }'

# 3. Query the user balance and confirm available/frozen balances moved as expected
#    See the "User Balance" page: the user-asset endpoints

Test refunds and reversals

Change authType in step 2 to REFUND (refund) or REVERSAL (spend reversal), repeat the call, and watch balances and transaction records move in the opposite direction. That confirms your system transitions state correctly in these scenarios.

What is out of scope

Authorization is decided in a single pass inside the system, so there are no separate settlement, authorization update or authorization reversal simulation endpoints; spend, refund and reversal are all expressed through authType on fund-auth.
On-chain collateral and payment routing are not involved, so no simulation endpoints exist for them.
3DS authentication is completed on the issuing side, so there is no standalone 3DS simulation endpoint. To test 3DS handling, see 3DS Forwarding.

Next steps

To understand how authorization is decided and how it holds balance inside the system, see Authorizing Transactions.
To see how user balances (availableBalance / frozenBalance) move after a simulated deposit or spend, see User Balance.
For real on-chain deposit addresses and the chain and currency configuration, see Crypto Deposit.
For how the KYC token is used in the real flow, see Authentication and Integration Resources.

​Exercise the whole flow in the sandbox before you go live

​What you can simulate

​Prerequisites

​Sandbox host

​Getting started

​Endpoint reference

​1 · Generate a KYC simulation token

​2 · Simulate a deposit (FOMO channel)

​3 · Simulate an authorization (spend / refund / reversal)

​Common patterns

​Run the minimal deposit → spend → check balance loop

​Test refunds and reversals

​What is out of scope

​Next steps

Exercise the whole flow in the sandbox before you go live

What you can simulate

Prerequisites

Sandbox host

Getting started

Endpoint reference

1 · Generate a KYC simulation token

2 · Simulate a deposit (FOMO channel)

3 · Simulate an authorization (spend / refund / reversal)

Common patterns

Run the minimal deposit → spend → check balance loop

Test refunds and reversals

What is out of scope

Next steps