Webhooks

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

Register your endpoint with Set webhook URL.
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.
Respond with HTTP 200 and the plain-text body success (without quotes).

If your endpoint does not respond with success, we retry the notification up to 5 times.

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

Sent only when a card order fails or is cancelled.

{
  "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.

{
  "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.

{
  "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.

Deposits with status OnHold are held and not credited. Use Refund held deposit with the transfer_id to return them.

{
  "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.

{
  "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.

{
  "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.

{
  "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

Get started

Cards

Remittance

Webhooks

Set up

Event envelope

Event types

Card events

CardTransaction

CreateCard, DeleteCard, FrozenCard, UnfrozenCard, CardStateChange, LockCard

Card3dsOtp

ThreeDomainSecureForwarding

CardTrade

CardBinStatus

Overspend

Settlement

Wallet events

AssetsDeposit

BlockchainRefund

AssetsWithdrawal

Cardholder events

CardholderUpdate

​Set up

​Event envelope

​Event types

​Card events

​CardTransaction

​CreateCard, DeleteCard, FrozenCard, UnfrozenCard, CardStateChange, LockCard

​Card3dsOtp

​ThreeDomainSecureForwarding

​CardTrade

​CardBinStatus

​Overspend

​Settlement

​Wallet events

​AssetsDeposit

​BlockchainRefund

​AssetsWithdrawal

​Cardholder events

​CardholderUpdate

Set up

Event envelope

Event types

Card events

CardTransaction

CreateCard, DeleteCard, FrozenCard, UnfrozenCard, CardStateChange, LockCard

Card3dsOtp

ThreeDomainSecureForwarding

CardTrade

CardBinStatus

Overspend

Settlement

Wallet events

AssetsDeposit

BlockchainRefund

AssetsWithdrawal

Cardholder events

CardholderUpdate