Skip to main content

​
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:
FieldDescription
eventThe name of the event that occurred.
idA unique identifier for the event. This should be used as the idempotency key for processing event deliveries.
dataThe data associated with the event.
timeThe 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). Data is a object of type CardAccountTransaction

​
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. 
{
    "id": "6b4332cd-0738-48fc-acbe-17f4edbcdcd7",
    "event": "cardaccount.client-identity.approved",
    "data": {
        "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d"
    },
    "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 and rejectedReason of the rejected reason..
rejectedReason value has:
  • Invalid ID
  • Cannot Open Doc
  • Image not Clear
  • Incomplete Information
  • Information Mismatch between ID and Input Data
  • Block Nationality
  • Multiple Accounts with Same KYC
{
    "id": "49f85bf3-f616-4a9f-8aaa-564d900ee829",
    "event": "cardaccount.client-identity.rejected",
    "data": {
        "cardAccountId": "05a3881a-568e-45f3-b601-8601064ae3d5",
        "rejectedReason": "Image not Clear",
    },
    "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
  }
}
FieldTypeDescription
urlstringTime-sensitive URL for cardholder to approve/decline
expiresAtstring (ISO 8601)When the approval URL expires
cardAccountIdstring (UUID)Card account ID
cardIdstring (UUID)Card ID used for transaction
merchantstringMerchant name
currencystringTransaction currency (ISO 4217)
amountnumberTransaction 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