Events overview

Cobo Payments notifies your system through webhook events. This page lists every event Cobo Payments provides, grouped by payment business. Click an event name to see its trigger conditions, fields, and samples.

All events

Events come in two kinds:

Standard events report the outcome of each payment business. Subscribe to the ones for the businesses you use.
Advanced events provide detail about the underlying on-chain transactions, such as confirmations, on-chain transaction fees, and block information. The business outcome is already reported by a standard event, so you do not need to subscribe to these unless you need that detail.

Business	Event	Type	What it notifies you of
Top-up	`payment.topup.updated`	Standard	A top-up’s status changed: detected, in compliance screening, action required, completed, or failed.
	`payment.address.updated`	Standard	A payer’s deposit address was replaced. Cobo also replaces addresses on its own.
	`payment.transaction.created`	Advanced	A top-up address received a new deposit, with on-chain transaction detail.
	`payment.transaction.completed`	Advanced	A top-up deposit cleared compliance screening, with on-chain transaction detail.
	`payment.transaction.failed`	Advanced	A top-up deposit failed or was rejected (for example, did not clear compliance screening), with on-chain transaction detail.
Orders	`payment.order.updated`	Standard	A pay-in order’s status changed: pending, processing, paid in full, underpaid, or expired. Also sent when a deposit needs your action, fails, or arrives after the order ended.
	`payment.order.status.updated`	Advanced	A pay-in order’s status changed, with on-chain transaction detail.
	`payment.transaction.late`	Advanced	A screened deposit arrived after the order reached a final state.
	`payment.transaction.completed`	Advanced	A deposit to the order cleared compliance screening, with on-chain transaction detail.
	`payment.transaction.failed`	Advanced	A deposit to the order failed or was rejected (for example, did not clear compliance screening), with on-chain transaction detail.
Unexpected deposits	`payment.transaction.external.created`	Standard	An unexpected deposit is detected (transactions not within current orders/deposit plans, or deposits in unsupported tokens).
Unexpected deposits	`payment.transaction.external.completed`	Standard	The unexpected deposit cleared compliance screening.
Refunds	`payment.refund.updated`	Standard	A refund order’s status changed: pending, completed, or failed.
Refunds	`payment.refund.status.updated`	Advanced	A refund order’s status changed, with on-chain transaction detail.
Payouts	`payment.payout.updated`	Standard	A payout’s status changed: accepted, preparing funds, transferring, completed, partially completed, failed, or returned by the receiving bank.
Payouts	`payment.payout.status.updated`	Advanced	A payout’s status changed, with on-chain transaction detail.
Fiat withdrawals	`payment.bank_withdrawal.status.updated`	Standard	A fiat withdrawal from one of your virtual accounts to a bank account changed status.
Bulk send	`payment.bulk_send.updated`	Standard	A bulk send batch’s status changed: created, validating, transferring, completed, partially completed, or failed, with amount and item-count summaries.
	`payment.bulk_send.item.updated`	Standard	A bulk send item’s status changed: pending, processing, completed, failed, or not executed.
	`payment.bulk_send.status.updated`	Advanced	A bulk send batch’s status changed.
	`payment.bulk_send.item.status.updated`	Advanced	A bulk send item reached a final status: `Completed`, `Failed`, or `NotExecuted`.
Balances	`payment.account.balance.updated`	Standard	One account’s available balance moved for one token, with the balance before and after and what caused it.

Event structure

Every webhook message shares the same envelope. event_id uniquely identifies an event and stays the same when the event is redelivered, so use it to deduplicate. The envelope’s created_timestamp is when this event was created, in milliseconds; it does not change on retries and cannot be used to order events (see Event ordering). The created_timestamp and updated_timestamp inside data are the object’s own creation and last-update times, in seconds. The envelope’s status (Success, Retrying, Failed) and the next_retry_timestamp and retries_left fields that appear during retries describe delivery of this message, not your business, and can be ignored when processing.

{
  "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b2f",
  "url": "https://example.com/webhook",
  "created_timestamp": 1701396866000,
  "type": "payment.topup.updated",
  "data": {
    "data_type": "PaymentTopUpUpdate",
    ...
    "created_timestamp": 1701396800,
    "updated_timestamp": 1701396865
  },
  "status": "Success"
}

`type`	`data.data_type`	ID field
`payment.topup.updated`	`PaymentTopUpUpdate`	`transaction_id`
`payment.order.updated`	`PaymentOrderUpdate`	`order_id`
`payment.refund.updated`	`PaymentRefundUpdate`	`refund_id`
`payment.payout.updated`	`PaymentPayoutUpdate`	`payout_id`
`payment.bulk_send.updated`	`PaymentBulkSendUpdate`	`bulk_send_id`
`payment.bulk_send.item.updated`	`PaymentBulkSendItemUpdate`	`bulk_send_item_id`

Rules that apply to every event

Event ordering

Cobo does not guarantee that events are delivered in the order they occur. For example, a payout moves through Pending, Preparing, Transferring, and Completed, but if one of those events fails to deliver and is retried, you may receive Completed before Transferring. Make sure your handling does not depend on the order in which events arrive. To confirm an object’s latest state, call the matching query endpoint, such as Get pay-in order information, Get refund order information, Get payout information, or Get bulk send information.

Empty values

Every field in the field tables is always present in the payload: null when it does not apply, [] for an empty array. Fields marked Optional or “Present only when…” are the exception.

Failure reasons

Events that can report a failure carry a failed_reason object.

"failed_reason": { "code": "transaction.rejected_by_policy", "message": "..." }

code is a controlled enumeration. Use it to decide how to handle the failure. message is written for human operators and its wording can change, so you can display it, but do not match on it. Each business page lists the codes that can appear on that object, grouped by the response they need: Top-up, Order, Refund, Payouts and withdrawals, Bulk send.

Amounts

Unless stated otherwise, amounts carry at most two decimal places (extra digits truncated, not rounded), with trailing zeros stripped (100.00 is sent as 100).

Shape	Example	Where it is used
Asset amount	`{ "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" }`	Most amount fields.
Asset or fiat amount	`{ "amount_type": "Crypto", "amount": "300", "token_id": "TRON_USDT", "chain_id": "TRON" }` `{ "amount_type": "Fiat", "amount": "497.5", "currency": "USD" }`	Fields that can be either crypto or fiat, such as the entries of `actual_payout_amounts`. Use `amount_type` to tell which.
Commission fee	`{ "fee_amount": "2.5" }`	Commission charged by Cobo, denominated in USD. It is taken from Fee Station, whose balance is in USD.

A field whose name is plural, such as requested_amounts, is an array and can span several tokens. A singular field is a single object covering one asset. Never add amounts across assets. Arrays group by token_id, so the same token symbol on two chains is two entries.

Set up your endpoint

To set up a webhook endpoint and subscribe to events, see Handle webhook events.

Overview

Initial Setup

Pay-In

Funds Management

Reference

All events

Event structure

Rules that apply to every event

Event ordering

Empty values

Failure reasons

Amounts

Set up your endpoint

​All events

​Event structure

​Rules that apply to every event

​Event ordering

​Empty values

​Failure reasons

​Amounts

​Set up your endpoint

All events

Event structure

Rules that apply to every event

Event ordering

Empty values

Failure reasons

Amounts

Set up your endpoint