> ## Documentation Index
> Fetch the complete documentation index at: https://developer.utgl.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

# 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

<Warning>
  **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](/issuing/guides/3ds-integration).
</Warning>

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](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account) 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

<Info>
  For complete integration guide including mobile app implementation and `postMessage` handling, see [3D Secure Integration](/issuing/guides/3ds-integration).
</Info>

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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

* [Create Webhook](/reference/createwebhook)

* [List Webhooks](/reference/listwebhooks)

* [Remove Webhook](/reference/removewebhook)

* [Table of Contents](#)

* * [Webhook Events and Payloads](#webhook-events-and-payloads)

    * [Event Envelope](#event-envelope)
    * [Accounts](#accounts)
    * [Card Accounts](#card-accounts)
    * [Cards](#cards)
    * [Payouts](#payouts)
    * [Others](#others)