Quickstart

This page walks you through the shortest path in the sandbox: register a user, issue a first virtual card, fund it, complete a purchase, and query the matching records and statements. The flow has 5 modules and 13 steps, and each step calls one endpoint. In the DeCard-Managed model, sensitive operations such as KYC and viewing card details are completed by the cardholder on a DCS-hosted page; you initiate them through the API and get the results through Webhooks and query endpoints.

Before you start

Before Step 1, make sure these 4 items are ready (see First Steps):

API Key / Secret Key issued.
Egress IP provided to DCS (the API uses an IP allowlist).
Webhook callback URL configured: the results of card issuance, deposits and purchases all arrive by Webhook.
Request signing working: every request carries X-DAPI-API-KEY / X-DAPI-TIMESTAMP / X-DAPI-NONCE / X-DAPI-SIGN; see the Authentication Guide.

The sandbox base URL is https://api.thedecard-sandbox.com (production: https://api.thedecard.com). The examples below omit the authentication headers, and all sample values are masked placeholders. Every response has the shape {code, message, messageDetail, data}, and code = SYS_SUCCESS means success. Each step below lists only the fields you need from data.

📄 Guide

Steps at a glance

Module	Step	Endpoint	What you get
1. Sign-up	1. Send the SMS code	`POST /captcha/v1/send-mobile-code`	A code sent to the cardholder’s phone
	2. Register the user	`POST /account/v1/register`	`externalUserId`
2. Card issuance	3. Get the card-application guidance link	`POST /redirect/v2/guidance-link` (`KYC_GUIDE`)	A one-time hosted-page link
	4. Receive the card-application result	Webhook `CARD_APPLY`	`cardId` (`status = SUCCEED`)
3. Card management	5. Query card detail	`GET /card/v3/detail`	`cardStatus`, masked card number
	6. Show card details	`POST /redirect/v2/guidance-link` (`CARD_INFO`)	A hosted-page link where the cardholder sees the full card number, CVV and expiry
	7. Freeze / unfreeze	`POST /card/v2/block`	Whether the operation succeeded
4. Deposits and simulated purchases	8. Get the deposit address	`GET /crypto/v2/deposit-address`	`address`
	9. Deposit	`POST /simulation/v2/deposit` (sandbox)	`txHash`; Webhook `ORDER_STATUS`
	10. Purchase	`POST /simulation/v2/fund-auth` (sandbox)	`approved`; Webhook `CARD_TRANSACTION`
5. Queries and reconciliation	11. Query deposit records	`GET /card/v1/fiat/transactions`	Deposit records
	12. Query statements	`GET /card/v2/statements`	`statementId`
	13. Query statement detail	`GET /card/v2/statements/detail`	Each transaction in the statement

Step 1: Send the SMS code

Send a registration code to the cardholder’s mobile number.

POST /captcha/v1/send-mobile-code

{
  "mobileCode": "SG",
  "mobile": "91234567",
  "externalUserId": "",
  "behavioral": "REGISTER"
}

Key response: data is an empty string; the code is sent to the cardholder’s phone by SMS. Notes:

Set behavioral to REGISTER; a new user has no externalUserId yet, so leave it empty.
mobileCode is the country code (ISO 2-letter, such as SG); mobile has no dialing prefix.

Step 2: Register the user

Complete registration with the code the cardholder received.

POST /account/v1/register

{
  "mobileCode": "SG",
  "mobile": "91234567",
  "smsCode": "<SMS code>"
}

Key response: data is the externalUserId (for example "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c"). Every later endpoint identifies the user by it, so store it. Notes:

mobileCode, mobile and smsCode must all be provided.
You can also register by email (email + emailCode), but not together with a mobile number; see User Sign-up.

2. Card issuance

Step 3: Get the card-application guidance link

KYC and card application both happen on the DCS-hosted page; the cardholder’s documents and selfie go straight to DCS and never pass through your backend.

POST /redirect/v2/guidance-link

{
  "action": "KYC_GUIDE",
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "successRedirectUrl": "https://your-app.example.com/kyc/success",
  "errorRedirectUrl": "https://your-app.example.com/kyc/failed",
  "language": "en"
}

Key response: data is a one-time hosted-page link; have the cardholder open it in a browser. Notes:

The link is valid for 5 minutes. Generate it and redirect immediately while the cardholder is online; do not send it asynchronously, for example by email.
If the user’s KYC is already PASS or PENDING, the call returns OPERATION_UNSUPPORTED and cannot be repeated.

For language, theme and the other parameters, see H5 KYC / Card Onboarding Guidance Page.

Step 4: Receive the card-application result

Once the cardholder submits on the hosted page, DCS pushes the result to you as the Webhook CARD_APPLY. Key response (inside data):

Field	Description
`status`	`PENDING` in progress / `SUCCEED` card issued / `FAILED` application failed
`cardId`	Card ID, present on `SUCCEED`; every later step uses it
`applyId`	Application ID, needed for extra documents
`needExtraInfo`	`true` means the cardholder must upload extra documents
`errorCode`	Failure reason, present on `FAILED`

Notes:

Return a 2xx within 2 seconds of receiving the Webhook; store it first and process it asynchronously, or it will be treated as a timeout and redelivered.
When status = PENDING and needExtraInfo = true, the cardholder must upload extra documents; see below.

If extra documents are needed: get an extra-document link with the same applyId and hand it to the cardholder; once they finish, DCS pushes CARD_APPLY again.

POST /redirect/v2/guidance-link

{
  "action": "KYC_EXTRA_DOC",
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "applyId": "A100001",
  "successRedirectUrl": "https://your-app.example.com/kyc/success",
  "errorRedirectUrl": "https://your-app.example.com/kyc/failed"
}

3. Card management

Step 5: Query card detail

GET /card/v3/detail?externalUserId=4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c&cardId=1234567890123456789

Key response: cardStatus (NORMAL / FROZEN / BLOCKED / CANCELLED), cardNo (masked card number), physicalCardStatus (physical card status). Notes:

cardId is optional; without it, all of the user’s cards are returned.
BLOCKED is an issuer-side block the cardholder cannot lift themselves; the reason is in statusReason. See Managing Cards.

Step 6: Show card details

The full card number, CVV and expiry are never returned to your backend through the API; the cardholder views them directly on the DCS-hosted page.

POST /redirect/v2/guidance-link

{
  "action": "CARD_INFO",
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "cardId": "1234567890123456789",
  "successRedirectUrl": "https://your-app.example.com/card/back",
  "errorRedirectUrl": "https://your-app.example.com/card/error"
}

Key response: data is a one-time hosted-page link for the cardholder to open. Notes: cardId is required.

Step 7: Freeze / unfreeze

POST /card/v2/block

{
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "cardId": "1234567890123456789",
  "block": true
}

Key response: data is a boolean; true means the operation succeeded. Notes: block = true freezes and false unfreezes. Unfreezing also needs smsCode or emailCode; send the code first with the Step 1 endpoint using behavioral = CARD_UNFROZEN. Physical card and PIN (optional): these also use POST /redirect/v2/guidance-link, with the same request body as Step 6 and only action changed.

`action`	What the cardholder does on the hosted page	How the result reaches you
`CREATE_PHYSICAL_CARD`	Enters the mailing details and applies for a physical card	For card products that ship, `CARD_PHYSICAL_SHIPPING` is pushed on every shipping status change
`ACTIVE_PHYSICAL_CARD`	Activates the card after receiving it	No push; check `physicalCardStatus` with Step 5
`UPDATE_PIN`	Sets the PIN	No push; the PIN never passes through your system

See Issuing Cards and Managing a Card’s PIN.

4. Deposits and simulated purchases

Step 8: Get the deposit address

GET /crypto/v2/deposit-address?externalUserId=4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c&network=TRON&coin=USDT

Key response: address (the deposit address) and status (PENDING being allocated / SUCCESS allocated / FAILED allocation failed). Notes:

On first request the address may still be allocating (PENDING); poll until SUCCESS before using it.
The sandbox supports only TRON + USDT and Ethereum + USDC; for the chains and tokens supported in production, see Crypto Deposit.

Step 9: Deposit

In the sandbox, a simulator endpoint fakes an on-chain arrival; in production the cardholder transfers on-chain to the address from Step 8.

POST /simulation/v2/deposit

{
  "chain": "TRON",
  "currency": "USDT",
  "amount": 100.0,
  "address": "<address from Step 8>"
}

Key response: data.txHash (the hash of the simulated arrival). Once credited, the Webhook ORDER_STATUS is pushed (transStatus = SUCCESS). Notes: to show the cardholder their balance, use GET /user-asset/v1/balance; see User Balance.

Step 10: Purchase

In the sandbox, a simulator endpoint starts a card authorization; in production it is triggered by the cardholder spending with the card.

POST /simulation/v2/fund-auth

{
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "cardId": "1234567890123456789",
  "authType": "EXPEND",
  "amount": 10.0,
  "currency": "USD"
}

Key response: data.approved (whether it was approved). Every purchase pushes the Webhook CARD_TRANSACTION: response = A means approved and D declined, with the decline reason in rejectReason. Notes: authType can also be REFUND (return) or REVERSAL (reversal); see Simulating Transactions.

5. Queries and reconciliation

Step 11: Query deposit records

GET /card/v1/fiat/transactions?externalUserId=4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c&page=1&rows=20

Key response: for each record, debitCreditIndcator (C credit / D debit), transactionAmount, and transferDetails (on-chain deposit details, including txHash).

Step 12: Query statements

GET /card/v2/statements?externalUserId=4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c&cardId=1234567890123456789&page=1&rows=20

Key response: for each statement, statementId (needed in Step 13) and statementDateStart / statementDateEnd (the billing period).

Step 13: Query statement detail

GET /card/v2/statements/detail?externalUserId=4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c&cardId=1234567890123456789&statementId=<statementId>&page=1&rows=20

Key response: for each transaction in the statement, transactionType (R purchase / C cash / P repayment / Q memo), debitCreditIndcator (debit or credit), and postIndicator (1 posted / 0 not posted). For the full fields and pagination rules, see Managing Transactions · Overview. Your first card is now issued, funded and has completed a purchase, and you can query the matching deposit records and statements.

Next steps

Full KYC flow and state machine → Compliance
All guidance-page actions and parameters → H5 KYC / Card Onboarding Guidance Page
The full card lifecycle (physical cards, replacement, PIN) → Managing Cards
Crypto deposits → Crypto Deposit
Every simulated transaction type in the sandbox → Simulating Transactions
Signing and authentication → Authentication Guide
Data structures of every push event → Webhook & WebSocket

Getting Started

Basic Concepts

How to Use

Integration Resources

Customer Success

Before you start

📄 Guide

Steps at a glance

Step 1: Send the SMS code

Step 2: Register the user

2. Card issuance

Step 3: Get the card-application guidance link

Step 4: Receive the card-application result

3. Card management

Step 5: Query card detail

Step 6: Show card details

Step 7: Freeze / unfreeze

4. Deposits and simulated purchases

Step 8: Get the deposit address

Step 9: Deposit

Step 10: Purchase

5. Queries and reconciliation

Step 11: Query deposit records

Step 12: Query statements

Step 13: Query statement detail

Next steps

​Before you start

​📄 Guide

​Steps at a glance

​1. Sign-up

​Step 1: Send the SMS code

​Step 2: Register the user

​2. Card issuance

​Step 3: Get the card-application guidance link

​Step 4: Receive the card-application result

​3. Card management

​Step 5: Query card detail

​Step 6: Show card details

​Step 7: Freeze / unfreeze

​4. Deposits and simulated purchases

​Step 8: Get the deposit address

​Step 9: Deposit

​Step 10: Purchase

​5. Queries and reconciliation

​Step 11: Query deposit records

​Step 12: Query statements

​Step 13: Query statement detail

​Next steps

Before you start

📄 Guide

Steps at a glance

1. Sign-up

Step 1: Send the SMS code

Step 2: Register the user

2. Card issuance

Step 3: Get the card-application guidance link

Step 4: Receive the card-application result

3. Card management

Step 5: Query card detail

Step 6: Show card details

Step 7: Freeze / unfreeze

4. Deposits and simulated purchases

Step 8: Get the deposit address

Step 9: Deposit

Step 10: Purchase

5. Queries and reconciliation

Step 11: Query deposit records

Step 12: Query statements

Step 13: Query statement detail

Next steps