Simulating transactions: authorization, clearing, refunds, partial, multi-part, 3DS

Simulating transactions

Whether you have just wired up the authorization callback or are running a final regression before go-live, a single sandbox endpoint lets you exercise the whole “card use, authorization, return, reversal” sequence and confirm that your authUrl decision logic and your webhookUrl posting logic are correct, with no real money and no real card network involved at any point. DCS is a licensed card issuer, and the sandbox shares the same authorization forwarding path as production, so whatever you get working in the sandbox migrates cleanly to production. Under the Partner-Managed model, the limit is held by you and the authorization is decided by you. That is why the real value of sandbox simulation is that it drives a genuine authorization forwarding round trip: once DCS receives your simulated transaction, it forwards the authorization request to your configured authUrl exactly as it would for a real card use, waits for your approve-or-decline answer, and then calls your webhookUrl accordingly.

Who does what

DCS: receives the simulation request, creates the transaction, forwards the authorization to authUrl, then calls back webhookUrl based on your decision.

Partner: sends the simulation request, returns the authorization decision at authUrl, then receives the callback at webhookUrl and posts it.

Endpoint: simulate an authorization request

POST /open-api/simulation/v1/fund-auth Simulates one authorization request (purchase, return or purchase reversal), which triggers the complete authorization forwarding and webhook notification chain in the sandbox.

This endpoint is sandbox-only (QA/DEV). A call against production is blocked and returns OPERATION_NOT_SUPPORT.

Authentication and request headers

As with every /open-api/ endpoint, you must send the authentication headers and set Content-Type: application/json. For the full rules, see Authentication.

Header	Required	Description
`Content-Type`	Yes	Fixed value `application/json`
`X-DAPI-API-KEY`	Yes	The `apiKey` DCS issued to you
`X-DAPI-TIMESTAMP`	Yes	Request timestamp (milliseconds, UTC), used for replay protection
`X-DAPI-NONCE`	Yes	Random number in the range `[10000, 99999]`, for replay protection
`X-DAPI-SIGN`	Yes	HMAC-SHA256 signature (lowercase hexadecimal)

Request parameters

Field	Type	Required	Description	Constraints
`cardId`	string	Yes	Card ID. The card must be in a usable state	—
`authType`	string	Yes	Authorization type: `EXPEND` purchase / `REFUND` return / `REVERSAL` purchase reversal	One of the three values
`amount`	number	Yes	Amount as a decimal, positive, in the major unit of the currency	Up to 10 integer digits, up to 2 decimal places
`currency`	string	Yes	Transaction currency, ISO 4217 three-letter code (`USD` / `CNY` / `SGD` / `EUR` / `JPY` and so on)	—

Field source: POST /open-api/simulation/v1/fund-auth (APISimulationAuthRequest). The endpoint currently does not accept parameters such as merchant name (merchantName), merchant category code (MCC) or an explicitly chosen decline reason (declineReason). If you need any of these later, talk to the DCS team.

Request example (purchase)

{
  "cardId": "CARD_20250101XXXX",
  "authType": "EXPEND",
  "amount": 50.00,
  "currency": "USD"
}

Response example

A successful call returns the standard response envelope, with the authorization outcome inside data:

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "approved": true,
    "errorCode": null
  }
}

When the authorization is declined, for instance because your authUrl returned a decline:

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "approved": false,
    "errorCode": "XXXX"
  }
}

Response fields

Field	Type	Description
`data.approved`	boolean	Whether the simulated authorization was ultimately approved
`data.errorCode`	string	The error code when it was not approved (see the error code dictionary for individual values)

About the standard response envelope {code, message, messageDetail, data}: code is the system-level status (such as SYS_SUCCESS), while message and messageDetail carry prompt text.

Note: a successful HTTP call plus code=SYS_SUCCESS does not mean the authorization was approved. For this endpoint, whether the authorization passed is determined by data.approved; an approved=false result comes back inside the very same SYS_SUCCESS envelope. Never judge the business outcome from the envelope alone. For how the error codes are classified, see Error code dictionary.

What the simulation can drive

The DCS sandbox uses authType to distinguish three authorization directions, which together cover the core authorization forwarding loop:

authType	Simulated action	Direction of funds	Typical use
`EXPEND`	Purchase	OUTGOING (consumes limit)	Test your `authUrl` approve or decline decision and webhook posting
`REFUND`	Return	INCOMING (money back)	Test the return callback and the reconciliation direction
`REVERSAL`	Purchase reversal	INCOMING (reverses the original authorization)	Test how you handle a reversal and the release of a hold

Recommended regression order

Create a usable card: complete the card issuance flow in the sandbox first (see Virtual card application) and keep the cardId.
Configure your callback URLs: confirm authUrl and webhookUrl are configured and reachable (see Webhook configuration).
Simulate a purchase: send authType=EXPEND, approve at authUrl, then check that data.approved=true and that webhookUrl received the matching event.
Simulate a decline: return a decline at authUrl, then check data.approved=false and the errorCode.
Simulate a return and a reversal: use REFUND and REVERSAL to verify the callbacks and reconciliation on the INCOMING side.

Simulated transactions create real transaction and authorization records and fire real webhooks, built to the same shape as production, so they are suitable for end-to-end verification as they stand. For the fields on authorization and transaction records and the structure of webhook events, see Events and data structures and Authorization and clearing scenarios.

Scenarios with no dedicated simulation yet

The DCS sandbox currently offers a single simulation entry point, fund-auth, covering purchase, return and reversal. The scenarios below have no dedicated simulation endpoint; test against the callback structures documented for them, or ask the DCS team to help construct a case:

Scenario	Status	Description
Standalone clearing or settlement (settlement/capture) simulation	Not available	There is no standalone clearing simulation endpoint today; for clearing behavior, test against the real callback structures described in Clearing scenarios: partial, over-clearing, multi-part
Incremental authorization (authorization update, such as adding a tip)	Not available	No standalone entry point for incremental authorization
Partial, over- and multi-part clearing	Not available	No standalone entry point; for the semantics see Clearing scenarios
3DS challenge (OTP/challenge) simulation	Not available	No standalone 3DS simulation endpoint; for the 3DS forwarding mechanism see 3DS forwarding
Collateral or deposit funding simulation	Not applicable	Under the Partner-Managed model the limit is held by you and the authorization is decided by you, so the sandbox offers no end-user funding simulation entry point

Today DCS covers the main authorization forwarding loop with a single fund-auth endpoint and its three authType values. If you need to test any of the scenarios above that lack a dedicated simulation entry point, contact the DCS team for help.

Next steps

Once the simulation runs cleanly, check the posting direction of each authType in your own system against Authorization and clearing scenarios, and complete the final regression in Pre-go-live checks.