Webhook Events and Payloads

Webhook events are delivered and enclosed in the following webhook event envelope. The following event definition only provides the name of the event as well as its event data schema.

Event Envelope

The webhook event envelope includes the following components:

Field	Description
event	The name of the event that occurred.
id	A unique identifier for the event. This should be used as the idempotency key for processing event deliveries.
data	The data associated with the event.
time	The timestamp of the event in ISO 8601 format at which it was published.

The following is an example of a webhook event that may be received when using the Issuing API.

{
  "event": "account.created",
  "id": "7dd3a60c-b0f3-416f-aacc-b64661a3a909",
  "time": "2023-01-10T00:57:38.585Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "xid": "def456",
    "xmetadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "name": "My Account",
    "accountNumber": "002-123456-7890123",
    "description": "This is my account."
  }
}

Accounts

account.created

This event is triggered when a new account is created. Example payload

{
  "event": "account.created",
  "id": "7dd3a60c-b0f3-416f-aacc-b64661a3a909",
  "time": "2023-01-10T00:57:38.585Z"
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "xid": "def456",
    "xmetadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "name": "My Account",
    "accountNumber": "002-123456-7890123",
    "description": "This is my account."
  }
}

account.balance

This event is triggered when balance has changed on an account, usually as a result of a new transaction or a transaction status change. Example payload:

{
  "event": "account.balance",
  "id": "89d14f5e-a5c5-4d7c-aa5a-b7f9e9b1f9c8",
  "time": "2023-01-10T01:12:34.567Z"
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "balance": 10000.25,
    "available": 825.30,
    "outstanding": 0,
    "asset": "HKD"
  }
}

account.transaction.created

This event is triggered when a transaction occurs on an account. Example payload:

{
  "event": "account.transaction.created",
  "id": "89d14f5e-a5c5-4d7c-aa5a-b7f9e9b1f9c8",
  "time": "2023-01-10T01:12:34.567Z"
  "data": {
    "asset": "HKD",
    "amount": 100.00,
    "balance": 10000.00,
    "intent": "transfer",
    "intentId": "52a40c0e-8b88-4f3f-a553-83f1537cf8d3",
    "intentRefId": "WTUJVUCYUJ",
    "status": "posted",
    "description": "INTERNAL TRANSFER FROM - A657808-001",
    "accountNumber": "002-011-2524311-004",
    "accountLabel": "wallet_digital",
    "xid": "def456",
    "xmetadata": {
      "key1": "value1",
      "key2": "value2"
    },
  }
}

account.transfer.created

This event is triggered when the account initiates a transfer. Example payload:

{
  "event": "account.transfer.created",
  "id": "89d14f5e-a5c5-4d7c-aa5a-b7f9e9b1f9c8",
  "time": "2023-01-10T01:12:34.567Z"
  "data": {
    "id": "699e5d76-1ad7-4817-9eb6-046a6c985f29",
    "asset": "HKD",
    "refId": "WTUJVUCYUJ",
    "amount": 1000,
    "sourceAccountId": "0ebd3c68-af60-4a6e-aaa9-040d8e64aa8e",
    "destinationAccountId": "56f6e9f1-3ca8-47a1-b3cd-f83d54497bb6",
    "description": "INTERNAL TRANSFER FROM - A657808-001",
    "xid": "def456",
    "xmetadata": {
      "key1": "value1",
      "key2": "value2"
    },
  }
}

Card Accounts

cardaccount.created

This event is triggered when a new card account is created. Data is a object of type CardAccount Example

{
  "event": "cardaccount.created",
  "id": "1c9e9e3a-3d51-4571-a5e5-5b5e5a5b5e5f",
  "time": "2023-01-10T02:34:56.789Z"
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "xid": "def456",
    "xmetadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "balance": 10000.25,
    "available": 825.30,
    "outstanding": 0,
    "currency": "HKD",
    "accountType": "asset-link",
    "phoneNumber": "+85212345678",
    "identityType": "individual"
  }
}

cardaccount.balance

This event is triggered when card account balance is changed.

{
  "event": "cardaccount.balance",
  "id": "1c9e9e3a-3d51-4571-a5e5-5b5e5a5b5e5f",
  "time": "2023-01-10T02:34:56.789Z"
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "balance": 10000.25,
    "available": 825.30,
    "outstanding": 0,
    "currency": "HKD"
  }
}

cardaccount.transaction.created

This event is triggered when a new transaction is initiated on the card account. Data is a object of type CardAccountTransaction

cardaccount.transaction.updated

This event is triggered when a transaction on the card account is updated (e.g. the transaction status changes from pending to posted, or the transaction dispute status changes). Data is a object of type CardAccountTransaction For card disputes, data.disputeStatus is one of requested, pending, success, failed, reported, or null when the transaction is not disputed.

cardaccount.transaction.declined

This event is triggered when a transaction has been declined on the card account data is a object of type CardAccountTransaction

cardaccount.transaction.verification-code-delivered

Deprecated: This webhook is replaced by the new 3D Secure (3DS) challenge flow which provides a more secure and streamlined verification experience. Please migrate to the new 3D Secure Integration.

This event is triggered when a security code is delivered to the client in relation to a payment authorization on the card account. The security code may be required to complete the transaction and should be delivered to the client as soon as possible to complete the transavtion. data is an object of type CardTransactionVerificationCode Example:

{
  "id": "1c9e9e3a-3d51-4571-a5e5-5b5e5a5b5e5f",
  "time": "2023-01-10T02:34:56.789Z"
  "event": "cardaccount.transaction.verification-code-delivered",
  "data": {
    "code": "1234",
    "expiresAt": "2022-11-10T07:52:09.415Z",
    "cardAccountId": "936da01f-9abd-4d9d-80c7-02af85c822a8",
    "cardId": "6f3a3b3f-a7c3-44b1-a7f9-f5d5f5a6aa5c",
    "createdAt": "2022-11-10T07:47:09.415Z"
  }
}

cardaccount.googlepay.verification-code-delivered

This event is triggered when a security code is delivered to the client in relation to a payment authorization on the card account. The security code may be required to complete the googlepay and should be delivered to the client as soon as possible to complete the transavtion. data is an object of type CardTransactionVerificationCode Example:

{
  "id": "1c9e9e3a-3d51-4571-a5e5-5b5e5a5b5e5f",
  "time": "2023-01-10T02:34:56.789Z"
  "event": "cardaccount.googlepay.verification-code-delivered",
  "data": {
    "code": "1234",
    "expiresAt": "2022-11-10T07:52:09.415Z",
    "cardAccountId": "936da01f-9abd-4d9d-80c7-02af85c822a8",
    "cardId": "6f3a3b3f-a7c3-44b1-a7f9-f5d5f5a6aa5c",
    "createdAt": "2022-11-10T07:47:09.415Z"
  }
}

cardaccount.transaction.suspicious-activity-detected

This event is triggered when a card transaction has triggered one or more rules in our fraud risk engine data is an object of type CardAccountSuspiciousActivity

{
  "id": "1c9e9e3a-3d51-4571-a5e5-5b5e5a5b5e5f",
  "time": "2023-01-10T02:34:56.789Z"
  "event": "cardaccount.transaction.suspicious-activity-detected",
  "data": {
    "id": "1eaf7193-d8af-4256-963f-70b2641db7f0",
    "cardId": "438f4574-8d75-4938-8667-e626d181da19",
    "cardAccountId": "8e243571-69af-45b5-8109-1523f7b8a79f",
    "ruleName": "Alert MCC (Trx › HKD70k)",
    "ruleDescription": "High Risk MCC Code. Amount HKD 70,000",
    "transaction": CardAccountTransaction,
    "relatedTransactions": CardAccountTransaction[],
    "actions": ["lock_card"]
  }
}

cardaccount.client-identity.approved

This event is triggered when a client’s identity verification for a card account has been approved. data is an object containing the cardAccountId of the approved account and the xid you assigned to that same card account.

xid is your own reference for the card account, letting you reconcile the outcome without a follow-up lookup. It is null when the card account has no xid.

{
    "id": "6b4332cd-0738-48fc-acbe-17f4edbcdcd7",
    "event": "cardaccount.client-identity.approved",
    "data": {
        "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d",
        "xid": "cobrander-card-account-123"
    },
    "time": "2025-01-16T08:02:14.413Z"
}

cardaccount.client-identity.rejected

This event is triggered when a client’s identity verification for a card account has been rejected. data is an object containing the cardAccountId of the rejected account, the xid you assigned to that same card account, the rejectedReason, and any rejectionAdditionalInfo.

xid is your own reference for the card account, letting you reconcile the outcome without a follow-up lookup. It is null when the card account has no xid. rejectionAdditionalInfo carries extra detail about the rejection, such as which document to resubmit. It is null when no additional information was provided.

rejectedReason carries the same value returned by Get Client Identity Information for the same card account, so the two always agree. Values are detailed strings in the form Category or Category (specific detail) — for example Invalid ID (expired doc), Unclear ID Image, or Info Mismatch b/w ID and Input Data (gender). See that endpoint’s rejectedReason field for the full list. New reasons are added over time. Match on the category prefix (e.g. Invalid ID () rather than the full string, and treat an unrecognized value as a generic rejection instead of failing.

{
    "id": "49f85bf3-f616-4a9f-8aaa-564d900ee829",
    "event": "cardaccount.client-identity.rejected",
    "data": {
        "cardAccountId": "05a3881a-568e-45f3-b601-8601064ae3d5",
        "xid": "cobrander-card-account-456",
        "rejectedReason": "Invalid ID (expired doc)",
        "rejectionAdditionalInfo": "Please upload valid hotel booking information."
    },
    "time": "2025-01-16T08:19:22.350Z"
}

3D Secure (3DS) Events

For complete integration guide including mobile app implementation and postMessage handling, see 3D Secure Integration.

These events manage the lifecycle of online transaction verification (3DS). When a cardholder performs an online transaction requiring verification, the system generates an approval link delivered via webhook.

cardaccount.transaction.challenge.initiated

This event is triggered when a 3DS challenge is initiated. It contains a unique, time-sensitive URL for the cardholder to approve or decline the transaction. data contains the approval URL and transaction details. Payload:

{
  "event": "cardaccount.transaction.challenge.initiated",
  "id": "evt_1a2b3c4d5e6f7g8h9i0j",
  "time": "2025-09-12T11:50:00.000Z",
  "data": {
    "url": "https://approve.utgl.io/tx/eyJhbg...GciOiJIUzI1NiJ9",
    "expiresAt": "2025-09-12T11:55:00.000Z",
    "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d",
    "cardId": "438f4574-8d75-4938-8667-e626d181da19",
    "merchant": "Example Online Store",
    "currency": "USD",
    "amount": 125.50
  }
}

Field	Type	Description
`url`	string	Time-sensitive URL for cardholder to approve/decline
`expiresAt`	string (ISO 8601)	When the approval URL expires
`cardAccountId`	string (UUID)	Card account ID
`cardId`	string (UUID)	Card ID used for transaction
`merchant`	string	Merchant name
`currency`	string	Transaction currency (ISO 4217)
`amount`	number	Transaction amount

cardaccount.transaction.challenge.succeeded

This event is triggered when the cardholder successfully approves the transaction. Payload:

{
  "event": "cardaccount.transaction.challenge.succeeded",
  "id": "evt_2b3c4d5e6f7g8h9i0j1k",
  "time": "2025-09-12T11:51:00.000Z",
  "data": {
    "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d",
    "cardId": "438f4574-8d75-4938-8667-e626d181da19"
  }
}

cardaccount.transaction.challenge.declined

This event is triggered when the cardholder actively declines the transaction. Payload:

{
  "event": "cardaccount.transaction.challenge.declined",
  "id": "evt_3c4d5e6f7g8h9i0j1k2l",
  "time": "2025-09-12T11:51:05.000Z",
  "data": {
    "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d",
    "cardId": "438f4574-8d75-4938-8667-e626d181da19"
  }
}

cardaccount.transaction.challenge.failed

This event is triggered when the challenge expires or fails due to a system error. Payload:

{
  "event": "cardaccount.transaction.challenge.failed",
  "id": "evt_4d5e6f7g8h9i0j1k2l3m",
  "time": "2025-09-12T11:55:01.000Z",
  "data": {
    "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d",
    "cardId": "438f4574-8d75-4938-8667-e626d181da19",
    "reason": {
      "code": "expired",
      "message": "The approval challenge expired before a decision was made."
    }
  }
}

Cards

card.issued

This event is triggered when a new card is issued. data is an object of type Card

card.activated

This event is triggered when a card is activated and becomes ready for use. data is an object of type Card

card.suspended

This event is triggered when a card is suspended and can no longer be used for transactions. data is an object of type Card

card.unsuspended

This event is triggered when a suspended card is unsuspended and can once again be used for transactions. data is an object of type Card

card.locked

This event is triggered when a card is locked and can no longer be used for transactions. data is an object of type Card

card.unlocked

This event is triggered when a locked card is unlocked and can once again be used for transactions. data is an object of type Card

card.cancelled

This event is triggered when a card is cancelled and can no longer be used for transactions. data is an object of type Card

card.spending-controls.modified

This event is triggered when the spending controls for a card are modified (e.g. the daily spending limit is changed). data is an object of type Card

Payouts

The Payouts section includes several events that are emitted by the API in response to specific actions related to payouts:

payout.created

This event is emitted when a new payout is created. data is an object of type Payout

payout.accepted

This event is emitted when a payout is accepted and is being processed. data is an object of type Payout

payout.succeeded

This event is emitted when a payout has been successfully completed. data is an object of type Payout

payout.cancelled

This event is emitted when a payout is cancelled. data is an object of type Payout

Others

depositaddress.assigned

This event is triggered when the user deposit address is created and updated. data is an object of type DepositAddress Example

{
  "id": "0c9e9e3a-3d51-4571-a5e5-5b5e5a5b5e5f",
  "time": "2024-09-26T17:16:38.232+00:00"
  "event": "depositaddress.assigned",
  "data": {
    "id": "933d295f-676a-4897-abf1-977537844132",
    "asset": "USDC",
    "address": "0x68d188066AbD13717369ebE4A06Aa1d7a3E843Cd",
    "chain": "ETH",
    "accountId": "383cdfdc-a2e6-42be-bf77-9a8f95968547",
    "addressTag": null,
    "created": "2024-09-26T17:16:38.232+00:00"
  }
}

digitaldeposit.completed

This event is triggered when a digital deposit is confirmed. data is an object of type DigitalDeposit Example

{
  "id": "0c9e9e3a-3d51-4571-a5e5-5b5e5a5b5e5f",
  "time": "2023-01-10T02:34:56.789Z"
  "event": "digitaldeposit.completed",
  "data": {
    "id": "71e0ff8a-7f37-4e10-8198-be99c815d123",
    "refId": "DDFJFN68U3",
    "amount": 10,
    "asset": "USDT",
    "transactionHash": "0x486c55cfac0a226eafc8cdec21a52806885bbe76c7065d8bb68084cb218a35ac",
    "chain": "BSC",
    "accountId": "904b8a05-00cb-401e-9e7f-1bf442ac7a34",
    "sourceAddress": "0xB90171AC3FfB8FC3197BB18B20e2B21f156cE039",
    "destinationAddress": "0x8f39FC5e07E1a3504C8912319600111b940e274b"
  }
}

webhook.ping

This event is triggered when the webhook is created and resumed.

What’s Next

​Webhook Events and Payloads

​Event Envelope

​Accounts

​account.created

​account.balance

​account.transaction.created

​account.transfer.created

​Card Accounts

​cardaccount.created

​cardaccount.balance

​cardaccount.transaction.created

​cardaccount.transaction.updated

​cardaccount.transaction.declined

​cardaccount.transaction.verification-code-delivered

​cardaccount.googlepay.verification-code-delivered

​cardaccount.transaction.suspicious-activity-detected

​cardaccount.client-identity.approved

​cardaccount.client-identity.rejected

​3D Secure (3DS) Events

​cardaccount.transaction.challenge.initiated

​cardaccount.transaction.challenge.succeeded

​cardaccount.transaction.challenge.declined

​cardaccount.transaction.challenge.failed

​Cards

​card.issued

​card.activated

​card.suspended

​card.unsuspended

​card.locked

​card.unlocked

​card.cancelled

​card.spending-controls.modified

​Payouts

​payout.created

​payout.accepted

​payout.succeeded

​payout.cancelled

​Others

​depositaddress.assigned

​digitaldeposit.completed

​webhook.ping

Webhook Events and Payloads

Event Envelope

Accounts

account.created

account.balance

account.transaction.created

account.transfer.created

Card Accounts

cardaccount.created

cardaccount.balance

cardaccount.transaction.created

cardaccount.transaction.updated

cardaccount.transaction.declined

cardaccount.transaction.verification-code-delivered

cardaccount.googlepay.verification-code-delivered

cardaccount.transaction.suspicious-activity-detected

cardaccount.client-identity.approved

cardaccount.client-identity.rejected

3D Secure (3DS) Events

cardaccount.transaction.challenge.initiated

cardaccount.transaction.challenge.succeeded

cardaccount.transaction.challenge.declined

cardaccount.transaction.challenge.failed

Cards

card.issued

card.activated

card.suspended

card.unsuspended

card.locked

card.unlocked

card.cancelled

card.spending-controls.modified

Payouts

payout.created

payout.accepted

payout.succeeded

payout.cancelled

Others

depositaddress.assigned

digitaldeposit.completed

webhook.ping