> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/payments/llms.txt
> Use this file to discover all available pages before exploring further.
# Events and status
**Disclaimer: This article contains AI translations and should only be used as reference.** Contact Cobo's support team through [help@cobo.com](mailto:help@cobo.com) if you have any questions.
This document describes all Webhook events and status transition processes involved in receiving payments (Pay-in), refunds, and payouts/transfers.
## Webhook Events
### **1. Pay-in Related**
| Scenario | Event Name | Trigger Condition | Event Content |
| :----------------- | :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Order Mode | `payment.order.status.updated` | Triggered when a payment order status changes. Key nodes include:
- `Pending`: Triggered only when an order is successfully created via a payment link.
- `Completed`: Full payment received within the order validity period.
- `Expired`: No completed deposit transactions within the validity period, or the order was canceled.
- `Underpaid`: Completed deposit transactions exist, but the total amount received is less than the expected amount. | This payload includes:
- `order_id` (required): The order ID.
- `merchant_id` (optional): The merchant ID.
- `merchant_order_code` (optional): A unique reference code assigned by the merchant.
- `psp_order_code` (required): A unique reference code assigned by the developer to identify this order.
- `pricing_currency` (optional): The pricing currency of the order.
- `pricing_amount` (optional): The base amount of the order, excluding the developer fee.
- `fee_amount` (required): The developer fee for the order.
- `payable_currency` (optional): The ID of the cryptocurrency used for payment.
- `chain_id` (required): The ID of the blockchain network.
- `payable_amount` (required): The cryptocurrency amount to be paid for this order.
- `exchange_rate` (required): The exchange rate between `payable_currency` and `pricing_currency`.
- `amount_tolerance` (optional): The allowed amount deviation.
- `receive_address` (required): The recipient wallet address for the payment transaction.
- `status` (required): The current order status. One of: `Pending`, `Processing`, `Completed`, `Expired`, `Underpaid`.
- `received_token_amount` (required): The total cryptocurrency amount received for this order.
- `expired_at` (optional): The expiration time, in Unix timestamp (seconds).
- `created_timestamp` (optional): The creation time, in Unix timestamp (seconds).
- `updated_timestamp` (optional): The last update time, in Unix timestamp (seconds).
- `transactions` (optional): An array of payment transactions associated with this order.
For full details, see [Get pay-in order information](/payments/en/api-references/payment/get-pay-in-order-information). |
| Order Mode | `payment.transaction.late` | A deposit transaction that passed compliance scanning is received after the payment order has reached a final state (`Underpaid`, `Expired`, or `Completed`). | This payload includes all fields from the [Transaction payload fields](#transaction-payload-fields) section, plus the following Payment-specific fields:
- `acquiring_type` (required): The collection type. Value: `Order` (Order Mode only).
- `order_id` (optional): The pay-in order ID.
- `psp_order_code` (optional): A unique reference code assigned by the developer to identify this order. |
| Top-up Mode | `payment.transaction.created` | A new deposit transaction is detected on a deposit address. | This payload includes all fields from the [Transaction payload fields](#transaction-payload-fields) section, plus the following Payment-specific fields:
- `acquiring_type` (required): The collection type. Value: `TopUp` (Top-up Mode only).
- `payer_id` (optional): A unique identifier assigned by Cobo to track and identify individual payers.
- `custom_payer_id` (optional): A unique identifier assigned by the developer to track and identify individual payers. |
| Top-up Mode | `payment.address.updated` | Triggered when the payer's top-up address is replaced. | This payload includes:
- `custom_payer_id`: Payer identifier in your system.
- `payer_id`: Payer identifier assigned by Cobo.
- `chain`: The chain of the address.
- `previous_address`: Address before replacement.
- `updated_address`: Address after replacement. |
| Order Mode | `payment.transaction.completed` | For every transaction received within the order's validity period, once the funds pass compliance screening, they are credited and recorded in the **Actual Receipt** amount. | This payload includes all fields from the [Transaction payload fields](#transaction-payload-fields) section, plus the following Payment-specific fields:
- `acquiring_type` (required): The collection type. Value: `Order`.
- `order_id` (optional): The pay-in order ID.
- `psp_order_code` (optional): A unique reference code assigned by the developer to identify this order. |
| Top-up Mode | `payment.transaction.completed` | Once a collection transaction passes compliance screening, the funds are credited and recorded in the **Actual Receipt** amount. | This payload includes all fields from the [Transaction payload fields](#transaction-payload-fields) section, plus the following Payment-specific fields:
- `acquiring_type` (required): The collection type. Value: `TopUp`.
- `payer_id` (optional): A unique identifier assigned by Cobo to track and identify individual payers.
- `custom_payer_id` (optional): A unique identifier assigned by the developer to track and identify individual payers. |
| Unexpected Deposit | `payment.transaction.external.created` | An unexpected deposit transaction is detected (e.g., transactions not within current orders/deposit plans, or deposits in unsupported tokens). | This payload includes all fields from the [Transaction payload fields](#transaction-payload-fields) section. |
| Unexpected Deposit | `payment.transaction.external.completed` | The unexpected deposit transaction passed compliance scanning and has been successfully credited to the developer balance. | This payload includes all fields from the [Transaction payload fields](#transaction-payload-fields) section. |
| Pay-in Check | `payment.transaction.failed` | The collection transaction failed the compliance screening. | This payload includes all fields from the [Transaction payload fields](#transaction-payload-fields) section, plus the following Payment-specific fields:
- `acquiring_type` (required): The collection type. `Order` for Order Mode, `TopUp` for Top-up Mode.
- `order_id` (optional): The pay-in order ID.
- `psp_order_code` (optional): A unique reference code assigned by the developer to identify this order.
- `payer_id` (optional): A unique identifier assigned by Cobo to track and identify individual payers.
- `custom_payer_id` (optional): A unique identifier assigned by the developer to track and identify individual payers. |
### Transaction payload fields
The following table lists the base fields included in all `payment.transaction.*` event payloads. Not all fields may be populated in every scenario.
| Field | Type | Required | Description |
| :--------------------- | :-------------- | :------- | :-------------------------------------------------------------------------------------------------------- |
| `transaction_id` | string (UUID) | Yes | The transaction ID. |
| `cobo_id` | string | No | The Cobo ID used to track a transaction. |
| `request_id` | string | No | The request ID used to track the transaction request. |
| `wallet_id` | string | Yes | For deposit transactions, the wallet ID of the destination. For other types, the wallet ID of the source. |
| `type` | string | No | The transaction type. |
| `status` | string | Yes | The transaction status. |
| `sub_status` | string | No | The transaction sub-status. |
| `failed_reason` | string | No | The reason why the transaction failed (applicable to approval and signature failures only). |
| `chain_id` | string | No | The chain ID. |
| `token_id` | string | No | The token ID. |
| `asset_id` | string | No | The asset ID (Exchange Wallets only). |
| `transaction_hash` | string | No | The transaction hash. |
| `source` | object | Yes | The transaction source. |
| `destination` | object | Yes | The transaction destination. |
| `result` | object | No | The transaction result. |
| `fee` | object | No | The transaction fee. |
| `initiator` | string | No | The transaction initiator. |
| `initiator_type` | string | Yes | The initiator type. |
| `confirmed_num` | integer | No | The number of confirmations received. |
| `confirming_threshold` | integer | No | The minimum number of confirmations required. |
| `block_info` | object | No | The block information. |
| `raw_tx_info` | object | No | The raw transaction information. |
| `replacement` | object | No | Replacement transaction information. |
| `category` | array | No | Custom transaction categories. |
| `description` | string | No | The transaction description. |
| `is_loop` | boolean | No | Whether the transaction was executed as a Cobo Loop transfer. |
| `cobo_category` | array | No | Transaction categories defined by Cobo. |
| `extra` | array | No | Structured, business-specific extra information for the transaction. |
| `fueling_info` | object | No | Fueling information. |
| `created_timestamp` | integer (int64) | Yes | The creation time, in Unix timestamp format (milliseconds). |
| `updated_timestamp` | integer (int64) | Yes | The last update time, in Unix timestamp format (milliseconds). |
Each transaction event also includes Payment-specific fields listed in the **Event Content** column of the table above.
### **2. Pay-out Related**
| Scenario | Event Name | Trigger Condition | Event Content |
| :--------------------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Refund | `payment.refund.status.updated` | Triggered when a refund order status changes. Key nodes include:
- `Pending`: Triggered only when a refund order is successfully created via a refund link.
- `Completed`: All refund transactions are completed.
- `PartiallyCompleted`: Some refund transactions completed, while others failed.
- `Failed`: All refund transactions failed. | This payload includes:
- `refund_id` (required): The refund order ID.
- `request_id` (optional): The request ID you provided when creating the refund.
- `order_id` (optional): The ID of the pay-in order corresponding to this refund.
- `merchant_id` (optional): The merchant ID.
- `token_id` (required): The ID of the cryptocurrency used for the refund.
- `chain_id` (required): The ID of the blockchain network.
- `amount` (required): The cryptocurrency amount to be returned for this refund.
- `to_address` (required): The recipient wallet address.
- `status` (required): The current refund status. One of: `AddressPending`, `AddressSubmitted`, `Pending`, `Processing`, `Completed`, `PartiallyCompleted`, `Failed`, `PendingConfirmation`.
- `refund_type` (optional): The source of funds. One of: `Merchant`, `Psp`.
- `created_timestamp` (required): The creation time, in Unix timestamp (seconds).
- `updated_timestamp` (required): The last update time, in Unix timestamp (seconds).
- `initiator` (optional): The initiator of the refund request.
- `transactions` (optional): An array of payment transactions associated with this refund.
- `charge_merchant_fee` (optional): Whether to charge the developer fee to the merchant.
- `merchant_fee_amount` (optional): The developer fee amount to charge the merchant.
- `merchant_fee_token_id` (optional): The ID of the cryptocurrency used for the developer fee.
- `commission_fee` (optional): Commission fee details.
For full details, see [Get refund order information](/payments/en/api-references/payment/get-refund-order-information). |
| Single-Destination Payout/Transfer | `payment.payout.status.updated` | Triggered when a payout/transfer request status changes:
- `Completed`: All payouts/transfers completed.
- `PartiallyCompleted`: Some completed, some failed.
- `Failed`: All failed. | This payload includes:
- `payout_id` (required): The payout ID.
- `request_id` (required): The request ID you provided when creating the payout.
- `payout_channel` (required): The payout channel. One of: `Crypto`, `OffRamp`.
- `source_account` (optional): The source account from which the payout is made.
- `payout_items` (optional): An array of payout items.
- `recipient_info` (optional): The recipient information.
- `initiator` (optional): The initiator of the payout request.
- `actual_payout_amount` (optional): The actual amount delivered to the recipient.
- `commission_fees` (optional): An array of commission fees for this payout.
- `remark` (optional): A note or comment about the payout.
- `status` (required): The current payout status. One of: `Pending`, `Preparing`, `Transferring`, `Completed`, `PartiallyCompleted`, `Failed`, `RejectedByBank`.
- `created_timestamp` (required): The creation time, in Unix timestamp (seconds).
- `updated_timestamp` (required): The last update time, in Unix timestamp (seconds).
- `transactions` (optional): An array of payment transactions associated with this payout.
For full details, see [Get payout information](/payments/en/api-references/payment/get-payout-information). |
| Bulk Send (Crypto) | `payment.bulk_send.status.updated` | Triggered when a bulk send request status changes:
- `Completed`: All sends completed.
- `PartiallyCompleted`: Some completed, some failed.
- `Failed`: All failed. | This payload includes:
- `bulk_send_id` (required): The bulk send ID.
- `request_id` (optional): The request ID you provided when creating the bulk send.
- `source_account` (required): The source account from which the bulk send is made.
- `description` (optional): The description for the entire bulk send batch.
- `execution_mode` (required): The execution mode.
- `status` (required): The current bulk send status.
- `created_timestamp` (required): The creation time, in Unix timestamp (seconds).
- `updated_timestamp` (required): The last update time, in Unix timestamp (seconds).
For full details, see [Get bulk send information](/payments/en/api-references/payment/get-bulk-send-information). |
| Account Balance | `payment.account.balance.updated` | Triggered when the available balance of a Payments account changes for a specific token. | This payload includes:
- `source_account` (required): The source account of the balance change. For a merchant account, this is the merchant ID; for the developer account, this is `developer`.
- `source_id` (required): The source ID of the balance change.
- `source_type` (required): The source type of the balance change (for example, `OrderIn`, `Payout`, `RefundOut`, `BulkSend`).
- `token_id` (required): The token ID.
- `amount` (required) / `amount_raw` (required): The balance change amount, truncated to two decimal places and in the token's decimal precision respectively.
- `balance_before` / `balance_before_raw` (required): The account balance before the change.
- `balance_after` / `balance_after_raw` (required): The account balance after the change.
- `flow_direction` (required): The direction of the balance change. One of: `in`, `out`.
- `update_time` (required): The time when the balance was updated, in Unix timestamp (seconds). |
### **3. Settlement Network Related**
| Scenario | Event Name | Trigger Condition | Event Content |
| :----------------- | :------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settlement Network | `payment.transaction.settlement_network.created` | Triggered when a Settlement Network transaction is created. | This payload includes the base fields from the [Transaction payload fields](#transaction-payload-fields) section. See the [Settlement Network](/payments/en/guides/settlement-network) guide. |
| Settlement Network | `payment.transaction.settlement_network.completed` | Triggered when a Settlement Network transaction is completed. On completion, the settled funds are reflected in your Payment account balance with the `SettlementNetwork` `source_type`. | This payload includes the base fields from the [Transaction payload fields](#transaction-payload-fields) section. See the [Settlement Network](/payments/en/guides/settlement-network) guide. |
## Webhook event examples
The following examples are illustrative and constructed from the field definitions in the Payment spec. Optional fields may be absent in actual webhook deliveries.
### payment.order.status.updated
```json theme={null}
{
"event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.order.status.updated",
"data": {
"data_type": "PaymentOrder",
"order_id": "O20250304-M1001-1001",
"merchant_id": "1001",
"psp_order_code": "P20240201001",
"pricing_currency": "USD",
"pricing_amount": "100.00",
"fee_amount": "2.00",
"payable_currency": "ETH_USDT",
"chain_id": "ETH",
"payable_amount": "103.03",
"exchange_rate": "0.99",
"receive_address": "0x1234567890abcdef1234567890abcdef12345678",
"status": "Completed",
"received_token_amount": "103.0305",
"created_timestamp": 1744689600,
"updated_timestamp": 1744689600
},
"status": "Success"
}
```
### payment.transaction.created
```json theme={null}
{
"event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b2f",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.transaction.created",
"data": {
"data_type": "PaymentTransaction",
"transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
"wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "Submitted",
"chain_id": "ETH",
"token_id": "ETH_USDT",
"transaction_hash": "239861be9a4afe080c359b7fe4a1d035945ec46256b1a0f44d1267c71de8ec28",
"source": { "source_type": "DepositFromAddress" },
"destination": { "destination_type": "DepositToAddress" },
"initiator_type": "API",
"created_timestamp": 1701396866000,
"updated_timestamp": 1701396866000,
"acquiring_type": "TopUp",
"payer_id": "P20250619T0310056d7aa",
"custom_payer_id": "user_abc_10001"
},
"status": "Success"
}
```
### payment.payout.status.updated
```json theme={null}
{
"event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b3f",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.payout.status.updated",
"data": {
"data_type": "PaymentPayout",
"payout_id": "123e457-e89b-12d3-a456-426614174004",
"request_id": "123e457-e89b-12d3-a456-426614174004",
"payout_channel": "Crypto",
"source_account": "M1001",
"status": "Completed",
"created_timestamp": 1744689600,
"updated_timestamp": 1744689600
},
"status": "Success"
}
```
### payment.account.balance.updated
```json theme={null}
{
"event_id": "9a3f1c2b-7d8e-4f0a-9b2c-5d6e7f8a9b0c",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.account.balance.updated",
"data": {
"data_type": "PaymentAccountBalanceUpdate",
"source_account": "M1001",
"source_id": "O202503041234567890",
"source_type": "OrderIn",
"token_id": "Tron_USDT",
"amount": "20.00",
"amount_raw": "20",
"balance_before": "100.00",
"balance_before_raw": "100",
"balance_after": "120.00",
"balance_after_raw": "120",
"flow_direction": "in",
"update_time": 1701396866
},
"status": "Success"
}
```
***
## Tips
To ensure absolute data accuracy and avoid concurrency conflicts, the Webhook payload does not include real-time balance changes or detailed fee deductions. If your use case requires this information, please refer to the following:
* **To update balances promptly based on Webhook notifications:** Upon receiving a Webhook, immediately call the [List merchant balances](/payments/en/api-references/payment/list-merchant-balances) or [Get developer balances](/payments/en/api-references/payment/get-developer-balance) endpoint to obtain the accurate balance for internal accounting.
* **To obtain fee details associated with a transaction for reconciliation:** Use the corresponding transaction query endpoints or [Generate reports](/payments/en/api-references/payment/generate-reports) to retrieve fee reports for data verification.
* **To monitor Fee Station balance changes and prevent business disruption:** Periodically call [List Fee Station token balance](https://www.cobo.com/developers/v2/api-references/feestation/list-fee-station-token-balances) and set up internal alerting based on your consumption rate to avoid service interruptions due to insufficient fees.