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

# Webhooks

> Receive real-time events for cards, transactions, deposits and cardholders.

Card operations are asynchronous. After the network processes a request, we send the result to your webhook URL as an HTTP `POST` with a JSON body.

## Set up

1. Register your endpoint with [Set webhook URL](/api-reference/api-settings/set-webhook-url).
2. Pass your own `clientTransactionId` on requests. It is included in the matching webhook. If you omit it, the API generates one, returns it in the response and includes it in the webhook.
3. Respond with HTTP `200` and the plain-text body `success` (without quotes).

<Warning>
  If your endpoint does not respond with `success`, we retry the notification up to 5 times.
</Warning>

## Event envelope

Every event has the same top-level fields:

| Field | Type | Description |
| - | - | - |
| `id` | string | Notification ID |
| `type` | string | Event type, see below |
| `data` | object | Event payload |
| `status` | string | Processing status of the event |

## Event types

| Type | Description |
| - | - |
| `CardTransaction` | A card transaction was created or updated |
| `CreateCard` | A card was created |
| `DeleteCard` | A card was closed |
| `FrozenCard` | A card was frozen |
| `UnfrozenCard` | A card was unfrozen |
| `CardStateChange` | A card status changed |
| `LockCard` | A card was locked |
| `Card3dsOtp` | A 3DS one-time code was issued |
| `ThreeDomainSecureForwarding` | A transaction needs authorization at a URL |
| `CardTrade` | A card order failed or was cancelled |
| `CardBinStatus` | A BIN status changed |
| `Overspend` | A card is overspent |
| `Settlement` | An overspend was settled from your balance |
| `AssetsDeposit` | Your wallet received a deposit |
| `BlockchainRefund` | A held deposit was refunded |
| `AssetsWithdrawal` | A wallet withdrawal was created or updated |
| `CardholderUpdate` | A cardholder status changed |

## Card events

### CardTransaction

Sent when a card transaction is created or updated. `data` is a [card transaction object](/guides/card-transaction-object).

```json theme={null}
{
  "id": "3481efe5-0f38-4cf8-b856-0d983dc10924",
  "type": "CardTransaction",
  "data": { },
  "status": "Pending"
}
```

### CreateCard, DeleteCard, FrozenCard, UnfrozenCard, CardStateChange, LockCard

Sent when a card is created, closed, frozen, unfrozen, locked or changes status. `data` is a [card object](/guides/card-object).

```json theme={null}
{
  "id": "3481efe5-0f38-4cf8-b856-0d983dc10924",
  "type": "CreateCard",
  "data": { },
  "status": "Pending"
}
```

### Card3dsOtp

Sent when a purchase needs 3DS verification. Show the `otp` to the cardholder.

```json theme={null}
{
  "id": "3481efe5-0f38-4cf8-b856-0d983dc10924",
  "type": "Card3dsOtp",
  "data": {
    "otp": "547235",
    "detail": "ULTRA MOBILE",
    "amount": 5.0,
    "card_id": "CA2407290908168",
    "card_no": "4931-93xx-xxxx-6332",
    "currency": "CNY",
    "order_id": "6cb23ec2-ecfe-40b9-b88a-7850d79314da"
  },
  "status": "Pending"
}
```

| Field | Description |
| - | - |
| `otp` | One-time verification code |
| `detail` | Merchant |
| `amount` | Transaction amount |
| `card_id` | Card ID |
| `card_no` | Card number, masked |
| `currency` | Transaction currency |
| `order_id` | Order ID |

### ThreeDomainSecureForwarding

Sent when a transaction must be approved at an authorization URL before it expires.

```json theme={null}
{
  "id": "3481efe5-0f38-4cf8-b856-0d983dc10924",
  "type": "ThreeDomainSecureForwarding",
  "data": {
    "url": "https://3ds.example.com/approve/1871870768564506625",
    "detail": "ULTRA MOBILE",
    "amount": 5.0,
    "card_id": "CA2407290908168",
    "card_no": "4931-93xx-xxxx-6332",
    "currency": "CNY",
    "order_id": "6cb23ec2-ecfe-40b9-b88a-7850d79314da",
    "action_id": "1871870768564506625",
    "timestamp": "2024-12-11 17:21:13",
    "expiration_time": "2024-12-11 17:26:13"
  },
  "status": "Pending"
}
```

| Field | Description |
| - | - |
| `url` | Authorization URL |
| `detail` | Merchant |
| `amount` | Transaction amount |
| `card_id` | Card ID |
| `card_no` | Card number, masked |
| `currency` | Transaction currency |
| `order_id` | Card order ID |
| `action_id` | Action ID |
| `timestamp` | Transaction time |
| `expiration_time` | Time the authorization expires |

### CardTrade

<Note>Sent only when a card order fails or is cancelled.</Note>

```json theme={null}
{
  "id": "c9bc0224-cf86-4dd1-a02b-ef0bbf7bf3e7",
  "type": "CardTrade",
  "data": {
    "holder": {
      "email": "jane@example.com",
      "phone": "2025550143",
      "lastName": "DOE",
      "firstName": "JANE",
      "phoneCode": "+1",
      "cardAddress": {
        "city": "Allentown",
        "state": "Pennsylvania",
        "country": "US",
        "postalCode": "20748",
        "addressLine1": "Allentown Way",
        "addressLine2": null
      }
    },
    "trade_id": "1s23ad13sa1d3s132999",
    "message": "Card creation failed. Please contact your account manager.",
    "trade_date": "2024-12-21 12:35:15"
  },
  "status": "Fail"
}
```

| Field | Description |
| - | - |
| `holder` | Cardholder details sent when creating the card |
| `trade_id` | The `clientTransactionId` sent when creating the card |
| `message` | Error message |
| `trade_date` | Transaction time |

### CardBinStatus

Sent when a BIN is enabled, disabled or put under maintenance.

```json theme={null}
{
  "id": "ef59a369-92ac-4eda-9c47-9a2700c641b4",
  "type": "CardBinStatus",
  "data": {
    "id": 51,
    "bin": "559292",
    "time": "2025-01-22 14:11:19",
    "status": false,
    "maintain": true
  },
  "status": "Pending"
}
```

| Field | Description |
| - | - |
| `id` | BIN ID |
| `bin` | BIN |
| `status` | `true` enabled, `false` disabled |
| `maintain` | `true` under maintenance, `false` normal |
| `time` | Updated at |

### Overspend

Sent once a day while a card is overspent.

```json theme={null}
{
  "id": "1f02c0ae-2b0e-604a-a76e-0242ac110002",
  "type": "Overspend",
  "data": {
    "card_id": "CA2407230104481",
    "card_no": "493193******5563",
    "amount": "-26.48",
    "type": "Overspend",
    "status": "Closed"
  },
  "status": "Pending"
}
```

### Settlement

Sent when an overspend is settled by deducting your account balance. The payload has the same fields as `Overspend`, with `type` set to `Settlement`.

| Field | Description |
| - | - |
| `card_id` | Card ID |
| `card_no` | Card number, masked |
| `amount` | Amount |
| `type` | `Overspend` or `Settlement` |
| `status` | Status |

## Wallet events

### AssetsDeposit

Sent when your wallet receives a transfer.

<Warning>Deposits with status `OnHold` are held and not credited. Use [Refund held deposit](/api-reference/account/refund-held-deposit) with the `transfer_id` to return them.</Warning>

```json theme={null}
{
  "id": "1f05d373-9545-6a14-bccf-0242ac110002",
  "type": "AssetsDeposit",
  "data": {
    "transfer_id": "78ef8cb6-bdd1-4f79-b1a1-62489a8d4e9466341",
    "to": "TWhvXq9BNM32vrKxDw49a5iDMFH68HgeNu",
    "from": "TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr",
    "amount": "41",
    "fee": "0",
    "currency": "USDT",
    "chain": "TRX",
    "status": "Closed",
    "risk_level": "low",
    "details": null,
    "hash": "5bf89335ff08acbd1bbb9d9426e98b604ae0bfcbf341d574c1c94b39be4d800e41",
    "updated_at": "2025-07-10 10:40:19"
  },
  "status": "Pending"
}
```

| Field | Description |
| - | - |
| `transfer_id` | Transfer ID, needed to refund a held deposit |
| `to` | Receiving address |
| `from` | Sending address |
| `amount` | Amount |
| `fee` | Fee |
| `currency` | Currency |
| `chain` | Blockchain network |
| `status` | `Pending` processing, `Closed` completed, `OnHold` held |
| `risk_level` | Risk level |
| `hash` | Transaction hash |
| `updated_at` | Updated at |

### BlockchainRefund

Sent when a held deposit has been refunded.

```json theme={null}
{
  "id": "1f05d3a8-6b02-6178-899f-0242ac110002",
  "type": "BlockchainRefund",
  "data": {
    "transfer_id": "78ef8cb6-bdd1-4f79-b1a1-62489a8d4e9466330",
    "address": "TEKUmbfUeMmicz7V11rY3nx6ijmsmZk9MJ",
    "amount": "30.000",
    "fee": "8.00",
    "currency": "USDT",
    "chain": "ETH",
    "status": "Refunded",
    "hash": "78ec433e84ba9ced2e46adfbe0ca7b362bba3b5ade155f5d170bab61",
    "refund_no": "40302ed1-9298-4f5c-8f0b-80927b5a523b",
    "updated_at": "2025-07-10 11:03:58"
  },
  "status": "Pending"
}
```

| Field | Description |
| - | - |
| `transfer_id` | Transfer ID |
| `address` | Refund address |
| `amount` | Amount |
| `fee` | Fee |
| `currency` | Currency |
| `chain` | Blockchain network |
| `status` | `ChannelRefunding` refund in progress, `Refunded` completed |
| `hash` | Transaction hash |
| `refund_no` | Refund number |
| `updated_at` | Updated at |

### AssetsWithdrawal

Sent when you request a withdrawal and whenever its status changes.

```json theme={null}
{
  "id": "1f07dad3-416d-6c20-9e95-0242ac110002",
  "type": "AssetsWithdrawal",
  "data": {
    "id": 33,
    "address": "TRMapUjRsFDxJzpRSigRWPgbyo8pVPCBUt",
    "amount": "5.333",
    "fee": 1.53,
    "txid": "",
    "status": "audit",
    "remark": "123",
    "reason": "",
    "create_time": "2025-08-20 18:05:30",
    "update_time": "2025-08-20 18:05:30"
  },
  "status": "Pending"
}
```

| Field | Description |
| - | - |
| `id` | Withdrawal ID |
| `address` | Receiving address |
| `amount` | Amount |
| `fee` | Fee |
| `txid` | Transaction hash |
| `status` | `rejected`, `audit` awaiting review, `waiting` queued, `pending` processing, `completed` |
| `remark` | Your withdrawal note |
| `reason` | Review note |
| `create_time` | Created at |
| `update_time` | Updated at |

## Cardholder events

### CardholderUpdate

Sent when a cardholder's status changes.

```json theme={null}
{
  "id": "1f076a9d-21ea-62c8-ac10-0242ac110002",
  "type": "CardholderUpdate",
  "data": {
    "cardholder_id": "20260413191941004295710863",
    "bin_ids": [602],
    "max_cardholder_count": 5,
    "business_mode": "B2C",
    "status": "Active",
    "first_name": "DAYTON",
    "last_name": "BERNHARD",
    "phone_country_code": null,
    "phone_number": null,
    "remark": ""
  },
  "status": "Pending"
}
```

| Field | Description |
| - | - |
| `cardholder_id` | Cardholder ID |
| `bin_ids` | BIN IDs the cardholder can use |
| `max_cardholder_count` | Cards the cardholder can hold, `-1` for unlimited |
| `business_mode` | `B2B` or `B2C` |
| `status` | `Active` activated, `Pending` processing, `Inactive` rejected |
| `first_name` | First name |
| `last_name` | Last name |
| `phone_country_code` | Phone country code |
| `phone_number` | Phone number |
| `remark` | Remark |