Events and data structures

​

📄 Guide

Prerequisites: before you can receive events you need to register your webhookUrl, get your IPs whitelisted, and be ready to verify X-Signature with your secretKey. For the configuration steps and the HMAC-SHA256 verification code, see Webhook configuration.

​

Mental model: one envelope, many events

Idempotent deduplication: the same event may be delivered several times because of network retries. Use the webhookId in the envelope as your idempotency key and acknowledge and skip any webhookId you have already processed, so you never double-post an entry or issue a card twice.

​

Common envelope structure

Time zones: notificationTime, along with createTime/modifyTime inside each data, carries a +08:00 offset (Singapore time), consistent with the UTC+8 convention used across the business time fields. Parse them using the offset the string carries.

​

webhookType event enum

AUTHORISATION_RESULT is the receipt for an authorization, which is a different thing from the authorization forwarding request that asks you to decide synchronously while the cardholder is paying. The latter is delivered in real time over authUrl (RSA two-way signing) and requires you to return approve or decline within a strict deadline. For how to handle those requests, see Authorization forwarding.

​

The data structure of each event

​

Card Order

For the full card order state machine, the meaning of each errorCode and what to resubmit, see Card issuing and Card order error codes.

​

Card

Webhooks never carry sensitive data such as the full card number or the CVV. For the card state machine (FROZEN can be lifted by you, BLOCKED only by DCS) and for statusReason, see Card management.

​

Authorization Result

Pushed for approvals and declines alike: DCS pushes this event whether the authorization was approved or declined (approveFlag=A/D). A decline you return on authUrl (01/11/21) is pushed as approveFlag=D; a failed DCS pre-check (a frozen or canceled card, for example, where the request was never forwarded to authUrl) is also pushed as approveFlag=D. You can therefore build a complete authorization ledger from this webhook alone, with the next day’s authorization report as the reconciliation backstop. For how authType, direction and originalAuthId combine in returns, incremental authorizations, multi-part settlements and similar scenarios, see Authorization and settlement and Capture scenarios.

​

Authorization 3DS Challenge

• OOB (out of band): the cardholder is sent to you to complete the verification. On receiving this webhook you guide the cardholder through authentication in your own app or another channel, then report the result back to DCS via API.
• OTP_DELEGATE: you send the verification code to the cardholder by SMS or email. DCS pushes the code to you in this webhook, and you decrypt it before sending it on to the cardholder.

Decrypting the sensitive fields (OTP_DELEGATE only): DCS encrypts otpPasscode, phoneNumber and email with AES-GCM using your secretKey, and the webhook carries the matching iv. Decrypt them with secretKey plus iv before you send the verification code to the cardholder. For a reference AES/GCM implementation (12-byte IV, 128-bit authentication tag), see Card management: reset PIN. For the full 3DS forwarding sequence, see 3DS forwarding.

​

KYC Ticket

The statuses a ticket can take differ per kycApplyMode: H5-RENEWAL and H5-MIGRATION only ever use INIT / PASSED / REJECTED and never NEED_VERIFY or PENDING. For each mode’s status line, see Updating KYC information and KYC information migration. For the KYC state machine, the rejection codes and what to resubmit, see Query KYC and KYC rejection codes.

​

KYC

For how to guide the user through a renewal after receiving kycRenewalRequired=true, see Updating KYC information; you can also call Query a user’s KYC information at any time to confirm.

​

A complete webhook example

{
  "businessId": "co_1234567890",
  "data": {
    "cardId": "card_xxx",
    "cardOrderId": "co_1234567890",
    "cardOrderRef": "your-ref-001",
    "createTime": "2026-01-01T11:58:00+08:00",
    "customerId": "cus_xxx",
    "modifyTime": "2026-01-01T12:00:00+08:00",
    "needExtraInfo": false,
    "profileId": "prof_xxx",
    "status": "COMPLETED",
    "type": "VIRTUAL"
  },
  "notificationTime": "2026-01-01T12:00:00+08:00",
  "webhookId": "wh_7f3a1c9e",
  "webhookSubType": "UPDATE",
  "webhookType": "CARD_ORDER"
}

The sample follows the actual lexicographic field order and is only pretty-printed for readability; the real payload is compact (see Notes below).

1. Verify X-Signature first and discard the request if verification fails;
2. Deduplicate on webhookId;
3. Dispatch to the right handler by webhookType;
4. Return HTTP 200 (any 2xx response counts as received); otherwise DCS redelivers according to its retry policy.

Apart from the real-time AUTHORISATION channel, a general webhook is retried at most 3 times; retries are driven by a scheduled job and the backoff interval follows that job’s configuration. The real-time AUTHORISATION channel is never retried and a timeout is treated directly as responseCode=21. The outbound DCS Content-Type is always application/json.

​

Notes

​

Payload format and field order

​

Field extensions

1. Existing fields stay stable: the fields already defined in this document never change their name, type or meaning, and are never removed;
2. Extension happens only by adding fields: partners can read the new fields as needed; if you do not need them yet, simply ignore them — existing parsing is unaffected;
3. Ignore unknown fields when parsing: do not parse webhook payloads in a strict mode that rejects unknown fields, so that new fields never break an existing integration.

​

New fields and signature verification

​

Next steps

• Signature verification not set up yet? Start with Webhook configuration and get a receiver that can verify X-Signature.
• Need to approve or decline in real time while the cardholder is paying? Read Authorization forwarding.