Disclaimer: This article contains AI translations and should only be used as reference. Contact Cobo’s support team through [email protected] if you have any questions.
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. |
| 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 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 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 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 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 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 section. |
| Pay-in Check | payment.transaction.failed | The collection transaction failed the compliance screening. | This payload includes all fields from the 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. |
For an order that receives multiple partial transfers before completion,
payment.transaction.completed fires once per successful receipt as funds are credited, while payment.order.status.updated reflects the order’s cumulative, terminal outcome (Completed or Underpaid). See Partial payments for details.payment.transaction.late reports a receipt that arrived after the order already reached a terminal status. It does not reopen or otherwise change the order’s final status. See Late payment for the full lifecycle.Transaction payload fields
The following table lists the base fields included in allpayment.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). |
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.- 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, 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. |
| 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.- RejectedByBank: The recipient bank rejected the Off-Ramp payout. | 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. |
| 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. |
| 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 section. See the 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 section. See the 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
{
"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
{
"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
{
"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
{
"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 or Get developer balances 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 to retrieve fee reports for data verification.
- To monitor Fee Station balance changes and prevent business disruption: Periodically call List Fee Station token balance and set up internal alerting based on your consumption rate to avoid service interruptions due to insufficient fees.