Events and data structures - DCS Technical Documentation

📄 Guide

Organization onboarding, employee creation, card issuing, card status, 3DS challenges, the three transaction events and the deposit alert add up to 18 outbound events in five groups. Every event shares one envelope — read webhookType, then parse the matching data. Your receiver needs a single endpoint.

Prerequisites: register the callback URL and be ready to recompute X-Signature with your SK. Setup steps and verification code are in Webhook configuration.

Webhook verification and dispatch by event type

The envelope

{
  "webhookId": "7800000000000000900",
  "webhookType": "ORGANIZATION_CREATED",
  "businessId": "7810000000000000123",
  "data": { },
  "notificationTime": "2026-08-25T02:30:00Z"
}

Field	Type	Description
`webhookId`	String	The webhook’s unique ID. The idempotency key — reused across every retry of the same event
`webhookType`	String	Event type code, uppercase with underscores; the full set is below
`businessId`	String	The business ID this delivery is about. Which kind of ID it is depends on `webhookType` — see the mapping below
`data`	Object	Business data; the fields vary by `webhookType`
`notificationTime`	String	Delivery timestamp, ISO-8601 UTC. It is the time of this delivery, so retries of one event carry different values

The envelope matches the common webhook structure used by the platform’s other product lines, so one consumer can handle events from all of them. Every ID field is a string; amounts are strings and trailing zeros are not guaranteed.

Event overview (18)

Group	`webhookType`	`businessId` is	Trigger
Organization	`ORGANIZATION_CREATED`	`organizationApplyId`	KYB passed, organization created
	`ORGANIZATION_REJECTED`	`organizationApplyId`	KYB rejected
	`ORGANIZATION_STATUS_CHANGED`	`organizationId`	Organization restrictions changed (added / removed)
Employee	`CUSTOMER_CREATED`	`customerApplyId`	KYC passed, employee created
	`CUSTOMER_REJECTED`	`customerApplyId`	KYC rejected
	`CUSTOMER_STATUS_CHANGED`	`customerId`	Employee restrictions changed (added / removed)
Card	`CARD_CREATED`	`cardApplyId`	Risk checks passed and the card was created
	`CARD_REJECTED`	`cardApplyId`	Risk declined, or card creation failed
	`CARD_SHIPPED`	`cardId`	The physical card was produced and dispatched (once, when the tracking number is generated)
	`CARD_ACTIVATED`	`cardId`	The physical card was activated
	`CARD_STATUS_CHANGED`	`cardId`	Card status changed (freeze / unfreeze / lock / unlock / lost / close); virtual and physical alike
	`AUTHORISATION_3DS_CHALLENGE`	`challengeId`	A cardholder transaction triggered a 3DS challenge needing your verification or OTP delivery
Transaction	`CARD_TRANSACTION`	`transactionId`	Card authorization / release (approval and decline share one event, distinguished by `data.status`)
	`CARD_TRANSACTION_SETTLEMENT`	`transactionId`	Card settlement
	`CARD_TRANSACTION_DEBT`	`transactionId`	The card entered a debt state
Funds	`BANK_TRANSFER_INFO`	`depositId`	A VA deposit landed (both success and failure, distinguished by `data.status`)
	`BALANCE_CHANGE`	`transactionId`	Balance changed
	`LOW_BALANCE`	`organizationId`	Funding pool balance below the alert threshold

Every event’s data carries organizationId except ORGANIZATION_REJECTED (the entity does not exist yet) and the three transaction events (attribution is derivable from cardId), so you never have to look up ownership.

Organization events

`ORGANIZATION_CREATED`

Field	Type	Description
`organizationId`	String	Organization ID
`organizationType`	String	Organization type; currently only `COMPANY`
`organizationRef`	String	Your own organization identifier (echoed)
`organizationApplyId`	String	Organization application ID
`status`	String	The organization entity’s status, always `ACTIVE`

`ORGANIZATION_REJECTED`

Field	Type	Description
`organizationType`	String	Organization type
`organizationRef`	String	Your own organization identifier
`organizationApplyId`	String	Organization application ID
`status`	String	The application status, always `REJECTED`
`rejectMessage`	String	The KYB rejection reason

This event carries no organizationId — the organization entity is only persisted once KYB passes, so it does not exist at rejection time. Match on organizationRef or organizationApplyId. Also note that status here refers to the application, not the entity as in ORGANIZATION_CREATED.

`ORGANIZATION_STATUS_CHANGED`

Mirrors updating organization restrictions; pushed once the change is committed.

Field	Type	Description
`organizationId`	String	Organization ID
`organizationType`	String	Organization type
`addRestrictions`	Array<String>	Restrictions added by this change
`removeRestrictions`	Array<String>	Restrictions removed by this change
`remark`	String	Operation remark

Employee events

`CUSTOMER_CREATED`

Field	Type	Description
`customerId`	String	Employee ID
`customerRef`	String	Your own employee identifier (echoed)
`organizationId`	String	The organization the employee belongs to
`customerApplyId`	String	Employee application ID
`status`	String	The employee entity’s status, always `ACTIVE`

`CUSTOMER_REJECTED`

Field	Type	Description
`customerRef`	String	Your own employee identifier
`organizationId`	String	The organization the employee belongs to
`customerApplyId`	String	Employee application ID
`status`	String	The application status, always `REJECTED`
`rejectMessage`	String	The KYC rejection reason

`CUSTOMER_STATUS_CHANGED`

Mirrors updating employee restrictions.

Field	Type	Description
`customerId`	String	Employee ID
`organizationId`	String	The organization the employee belongs to
`addRestrictions`	Array<String>	Restrictions added by this change
`removeRestrictions`	Array<String>	Restrictions removed by this change
`remark`	String	Operation remark

Card events

`CARD_CREATED`

Field	Type	Description
`cardId`	String	Card ID
`organizationId`	String	The organization the card belongs to
`cardApplyId`	String	Card application ID
`cardApplyRef`	String	Your own application identifier (echoed)
`status`	String	Card status, always `ACTIVE`

`CARD_REJECTED`

Field	Type	Description
`organizationId`	String	The organization the card belongs to
`cardApplyId`	String	Card application ID
`cardApplyRef`	String	Your own application identifier (echoed)
`status`	String	The application status, always `REJECTED`
`rejectMessage`	String	Why it failed (risk decline or a card-creation error)

`CARD_SHIPPED`

Pushed when the tracking number is generated, exactly once.

Field	Type	Description
`cardId`	String	Card ID
`organizationId`	String	The organization the card belongs to
`trackingNumber`	String	Tracking number
`trackingCompanyName`	String	Courier
`trackingNumberDate`	String	Waybill date, `yyyy-MM-dd`

`CARD_ACTIVATED`

Field	Type	Description
`cardId`	String	Card ID
`organizationId`	String	The organization the card belongs to

`CARD_STATUS_CHANGED`

Field	Type	Description
`cardId`	String	Card ID
`organizationId`	String	The organization the card belongs to
`fromStatus`	String	Card status before the change (one of 7)
`toStatus`	String	Card status after the change (one of 7)

This event covers neither activation nor expiry: activation is pushed as CARD_ACTIVATED, and expiry currently has no trigger. The 7 card statuses are listed in Managing cards.

`AUTHORISATION_3DS_CHALLENGE`

The business flow and how to reply are covered in 3DS challenges.

Field	Type	Description
`challengeId`	String	Challenge ID, echoed back when you reply. Deduplicate on it
`status`	String	Always `INIT` — the challenge’s final state is not notified through this event
`cardId`	String	The card that triggered the challenge
`organizationId`	String	The organization the card belongs to
`expiryTime`	String	When the challenge expires, ISO-8601 UTC (about 300 seconds by default)
`currency`	String	Transaction currency, ISO-4217; paired with `amount`
`amount`	String	Transaction amount
`merchantId`	String	Merchant identifier
`merchantName`	String	Merchant name
`merchantCountryCode`	String	Merchant country, ISO-3166-1 alpha-2 uppercase
`mcc`	String	Merchant category code, four digits
`challengeFlowType`	String	`OOB` / `OTP_DELEGATE` — tells you whether to parse the encrypted fields below
`challengeMethodType`	String	`DELEGATE_SCA_V1` / `SMS_OTP` / `EMAIL_OTP`

The following four fields are populated only when challengeFlowType=OTP_DELEGATE and the partner is configured with otpSendMode=ENTERPRISE:

Field	Type	Description
`encryptedOtpPasscode`	String	The OTP, encrypted
`encryptedPhoneNumber`	String	The cardholder’s mobile number, encrypted
`encryptedEmail`	String	The cardholder’s email address, encrypted
`iv`	String	AES-GCM initialisation vector (Base64), shared by the three encrypted fields above

Decryption: AES/GCM/NoPadding with a 128-bit authentication tag; the key is your SK (the same one used for request signing), following the same contract as retrieving secure card details.

merchantCountryCode changes from alpha-3 (three letters) to alpha-2 (two uppercase letters) — that is a value conversion, not just a rename, so your parsing needs to change with it.

Transaction events

The three transaction events describe the same facts as statement line items and reuse the statement domain’s vocabulary: panLast4 / transactionTime / transactionCategory / originalAmount+originalCurrency (the original transaction amount) / postAmount+postCurrency (the posted amount) / merchantName / mcc / merchantCountryCode.

Transaction events carry no organizationId: attribution is derivable from cardId — a card’s organization is fixed at issue time and never changes, and you already received it in CARD_CREATED. Transaction events are far higher in volume than lifecycle events, so they carry only what is necessary. To aggregate by organization, use Statements and transactions.

`CARD_TRANSACTION`

Authorization and release share one event; approval versus decline is given by status.

Field	Type	Description
`transactionId`	String	Transaction ID, identical to the statement line’s, so it reconciles directly
`originalTransactionId`	String	The original transaction’s ID. Present only for release / reversal / refund events
`cardId`	String	Card ID
`panLast4`	String	Last four digits of the card number
`status`	String	Authorization result: `APPROVED` / `DECLINED`
`direction`	String	Debit or credit: `DEBIT` / `CREDIT` / `DEDUCT`. Absent entirely when upstream sends no indicator
`originalAmount` / `originalCurrency`	String	The original transaction amount and currency
`postAmount` / `postCurrency`	String	The posted (accounting) amount and currency
`transactionTime`	String	Transaction time in the acquirer’s local time, `yyyy-MM-dd HH:mm:ss`
`transactionCategory`	String	`SALES` / `CASH_ADVANCE` / `PAYMENT` / `INSTALLMENT` / `INQUIRY` / `TRANSFER_OUT`
`merchantName`	String	Merchant name, passed through from upstream and may include an address
`merchantCountryCode`	String	Merchant country, alpha-2 uppercase
`mcc`	String	Merchant category code, four digits

{
  "webhookId": "7800000000000001201",
  "webhookType": "CARD_TRANSACTION",
  "businessId": "5185740066240791001",
  "notificationTime": "2026-08-25T02:30:00Z",
  "data": {
    "transactionId": "5185740066240791001",
    "cardId": "5136759791164443137",
    "panLast4": "4821",
    "status": "APPROVED",
    "direction": "DEBIT",
    "originalAmount": "128.50",
    "originalCurrency": "HKD",
    "postAmount": "16.47",
    "postCurrency": "USD",
    "transactionTime": "2026-08-25 10:30:00",
    "transactionCategory": "SALES",
    "merchantName": "STARBUCKS TSIM SHA TSUI HK",
    "merchantCountryCode": "HK",
    "mcc": "5812"
  }
}

`CARD_TRANSACTION_SETTLEMENT`

Field	Type	Description
`transactionId`	String	Transaction ID, identical to the authorization event’s and the statement line’s
`cardId`	String	Card ID
`panLast4`	String	Last four digits of the card number
`direction`	String	`DEBIT` / `CREDIT`. Memo transactions do not push this event
`originalAmount` / `originalCurrency`	String	The original transaction amount and currency
`postAmount` / `postCurrency`	String	The settled amount and currency
`transactionTime`	String	Transaction time in the acquirer’s local time
`transactionCategory`	String	`RETAIL` / `CASH` / `RETAIL_FEES` / `CASH_FEES` / `PAYMENT` / `DISPUTE_REGISTER` / `DISPUTE_RELEASE` / `RETAIL_INTEREST` / `CASH_ADVANCE_INTEREST` / `CARD_ANNUAL_FEE` / `CARD_PHYSICAL_FEE` / `CARD_REPLACEMENT_FEE`
`merchantName`	String	Merchant name
`merchantCountryCode`	String	Merchant country, alpha-2
`mcc`	String	Merchant category code

transactionCategory has three different value domains: six values on the authorization event (SALES, CASH_ADVANCE, …), twelve on the settlement event (RETAIL, CASH, …) and seven on statement lines (PURCHASE, REFUND, …). Parse them per event type; do not share one enum.

`CARD_TRANSACTION_DEBT`

Pushed when the card enters a debt state.

Field	Type	Description
`transactionId`	String	Transaction ID
`cardId`	String	The card the debt belongs to
`debtAmount` / `debtCurrency`	String	The debt amount and currency (transaction basis)
`postAmount` / `postCurrency`	String	The posted amount and currency (settlement basis)
`transactionTime`	String	Transaction time in the acquirer’s local time
`merchantName`	String	Merchant name

This payload holds two amounts with different meanings (the debt and the posting), so each carries a qualifier instead of a bare amount.

Fund events

`LOW_BALANCE`

Raised when the funding pool falls below the threshold. Threshold setup is covered in Company maintenance.

Field	Type	Description
`organizationId`	String	The organization that triggered the alert
`currency`	String	Funding pool currency: `USD` / `HKD`
`availableAmount`	String	Current available balance, paired with `currency`
`thresholdAmount`	String	The threshold that triggered the alert

{
  "webhookId": "7800000000000001001",
  "webhookType": "LOW_BALANCE",
  "businessId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "notificationTime": "2026-08-25T02:30:00Z",
  "data": {
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "currency": "USD",
    "availableAmount": "850.25",
    "thresholdAmount": "1000"
  }
}

`BANK_TRANSFER_INFO`

A VA deposit landed. Both success and failure are pushed, distinguished by status.

Field	Type	Description
`depositId`	String	The platform’s deposit record ID, matching the deposit-records query
`organizationId`	String	The organization that owns the receiving pool
`amount` / `currency`	String	Deposit amount and currency: `USD` / `HKD`
`payeeAccountNumber`	String	The receiving virtual account number
`referenceCode`	String	The bank’s reference number
`payerName`	String	Payer name
`payerAccountNumber`	String	Payer account number
`payerBankCode`	String	Payer bank code
`status`	String	Posting status: `SUCCESS` / `FAILED`
`errorCode` / `errorMessage`	String	Returned only on `FAILED`, always as a pair

`BALANCE_CHANGE`

This event’s contract is not finalised and its fields may change at any time. The current implementation forwards the ledger change log as-is, including internal fields that do not follow the conventions in this documentation. Confirm with the platform before integrating; this page does not define its data structure.

Three things remain open: which balance dimensions it covers (organization pool balance / free balance / a dedicated-balance card’s own balance), how the subject and balance type are identified, and whether every ledger movement is pushed.

Next steps

Registering the callback URL, verification and the retry contract: Webhook configuration
Receiving and replying to 3DS challenges: 3DS challenges
Reconciling through query endpoints: Statements and transactions

​📄 Guide

​The envelope

​Event overview (18)

​Organization events

​ORGANIZATION_CREATED

​ORGANIZATION_REJECTED

​ORGANIZATION_STATUS_CHANGED

​Employee events

​CUSTOMER_CREATED

​CUSTOMER_REJECTED

​CUSTOMER_STATUS_CHANGED

​Card events

​CARD_CREATED

​CARD_REJECTED

​CARD_SHIPPED

​CARD_ACTIVATED

​CARD_STATUS_CHANGED

​AUTHORISATION_3DS_CHALLENGE

​Transaction events

​CARD_TRANSACTION

​CARD_TRANSACTION_SETTLEMENT

​CARD_TRANSACTION_DEBT

​Fund events

​LOW_BALANCE

​BANK_TRANSFER_INFO

​BALANCE_CHANGE

​Next steps

📄 Guide

The envelope

Event overview (18)

Organization events

`ORGANIZATION_CREATED`

`ORGANIZATION_REJECTED`

`ORGANIZATION_STATUS_CHANGED`

Employee events

`CUSTOMER_CREATED`

`CUSTOMER_REJECTED`

`CUSTOMER_STATUS_CHANGED`

Card events

`CARD_CREATED`

`CARD_REJECTED`

`CARD_SHIPPED`

`CARD_ACTIVATED`

`CARD_STATUS_CHANGED`

`AUTHORISATION_3DS_CHALLENGE`

Transaction events

`CARD_TRANSACTION`

`CARD_TRANSACTION_SETTLEMENT`

`CARD_TRANSACTION_DEBT`

Fund events

`LOW_BALANCE`

`BANK_TRANSFER_INFO`

`BALANCE_CHANGE`

Next steps