Top-up

This page covers Top-up Mode: each payer has their own deposit address, and every deposit is tracked on its own. Read Events overview first for the envelope, deduplication, and the rules that apply to every event.

Events on this page

Event	What it notifies you of	Type
`payment.topup.updated`	A top-up’s status changed: detected, in compliance screening, action required, completed, or failed.	Standard
`payment.address.updated`	You replaced a payer’s deposit address via the update top-up address API.	Standard

`payment.topup.updated`

The main event for Top-up Mode.

Trigger conditions

One event per change of this deposit’s status.

The diagram shows the main status paths; final statuses are shown in green. An intermediate status (such as PendingScreening) may not appear if the deposit moves on to the next status quickly, and events may arrive out of order; see Event ordering.

Trigger condition	`status`	Creditable	What to do
The funds are detected on a deposit address	`Detected`	❌	Record the incoming deposit.
The deposit enters compliance screening (no second event is sent when it returns here after `ActionRequired` is resolved)	`PendingScreening`	❌	Wait.
Screening needs you to act — supply information, or complete a manual compliance review	`ActionRequired`	❌	Act on `message`.
Screening passed and the transaction has at least one on-chain confirmation	`Completed` (final)	✅	Credit `amount`, using `transaction_id` as the idempotency key.
The deposit was rejected or failed	`Failed` (final)	❌	Read `failed_reason.code` to decide what happens next.

A deposit at or below the dust threshold sends no event. Each token’s threshold is the min_amount returned by Create/Get top-up address or Batch create top-up addresses; tokens without their own setting default to 0.05, and an amount must exceed it.

Event content

Field	Type	Description
`data_type`	`string`	Always `PaymentTopUpUpdate`.
`transaction_id`	`string`	The deposit’s ID in Cobo.
`merchant_id`	`string`	Which merchant this deposit belongs to.
`payer_id`	`string`	The payer ID assigned by Cobo.
`custom_payer_id`	`string`	The payer ID you supplied when registering the deposit address; `null` if you supplied none.
`status`	`string`	The current status; see Trigger conditions for what each means: • `Detected` • `PendingScreening` • `ActionRequired` • `Completed` • `Failed`
`amount`	`object`	The deposit’s amount. It never changes and is kept even when the deposit fails.
`amount.amount`	`string`	The amount. See Amounts for the format.
`amount.token_id`	`string`	The token ID.
`amount.chain_id`	`string`	The chain ID.
`tx_hash`	`string`	The on-chain transaction hash.
`topup_address`	`string`	The deposit address that received the funds.
`source_address`	`string`	The on-chain sender, and the target if you return the funds.
`screening_mode`	`string`	The screening method, used to tell where to handle the deposit when `status` is `ActionRequired`. • `CoboKyt` — Cobo KYT. • `IntegratedVendor` — a third-party provider integrated by Cobo in the Screening App.
`message`	`string`	What to do when `status` is `ActionRequired`; `null` otherwise. • `Additional information is required…` — check the email Cobo sent to your account contact and supply what it asks for. • `A manual compliance review by your team is required…` — complete a manual compliance review in the Screening App.
`failed_reason`	`object`	Set when `status` is `Failed`; `null` otherwise.
`failed_reason.code`	`string`	The failure code. See Failure reasons for the values.
`failed_reason.message`	`string`	The failure reason.
`created_timestamp`	`integer`	When this deposit was created, in Unix timestamp (seconds).
`updated_timestamp`	`integer`	When this deposit last changed status, in Unix timestamp (seconds).

Failure reasons

`code`	What happened	What to do
`transaction.rejected_by_screening_app`	Your own compliance team rejected this deposit in the Screening App.	Review the case there.
`transaction.rejected_by_compliance`	Cobo’s compliance checks rejected this deposit.	Check with Cobo.
`transaction.failed`	Failed for any other reason.	Raise a case and quote `transaction_id`.

Sample events

Each sample shows the data object only. The envelope around it is the same for every event — see Event structure.

A deposit is detected

Mark it as in progress. Do not credit anything yet.

{
  "data_type": "PaymentTopUpUpdate",
  "transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
  "merchant_id": "M1001",
  "payer_id": "P20250619T0310056d7aa",
  "custom_payer_id": "user_abc_10001",
  "status": "Detected",
  "amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": "0xabc123",
  "topup_address": "0xtopup_addr_M1001_user_abc",
  "source_address": "0xsender001",
  "screening_mode": null,
  "message": null,
  "failed_reason": null,
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689000
}

Compliance screening is in progress

Keep waiting. screening_mode tells you which system is reviewing it, not that you need to do something.

{
  "data_type": "PaymentTopUpUpdate",
  "transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
  "merchant_id": "M1001",
  "payer_id": "P20250619T0310056d7aa",
  "custom_payer_id": "user_abc_10001",
  "status": "PendingScreening",
  "amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": "0xabc123",
  "topup_address": "0xtopup_addr_M1001_user_abc",
  "source_address": "0xsender001",
  "screening_mode": "IntegratedVendor",
  "message": null,
  "failed_reason": null,
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689060
}

Screening needs you to act

Route the deposit into your manual handling process and use message to decide which action is needed.

{
  "data_type": "PaymentTopUpUpdate",
  "transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
  "merchant_id": "M1001",
  "payer_id": "P20250619T0310056d7aa",
  "custom_payer_id": "user_abc_10001",
  "status": "ActionRequired",
  "amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": "0xabc123",
  "topup_address": "0xtopup_addr_M1001_user_abc",
  "source_address": "0xsender001",
  "screening_mode": "CoboKyt",
  "message": "Additional information is required before these funds can be made available. Please check the email sent to your account contact.",
  "failed_reason": null,
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689100
}

The funds are available

This is the only status you may credit on. Use transaction_id as the idempotency key.

{
  "data_type": "PaymentTopUpUpdate",
  "transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
  "merchant_id": "M1001",
  "payer_id": "P20250619T0310056d7aa",
  "custom_payer_id": "user_abc_10001",
  "status": "Completed",
  "amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": "0xabc123",
  "topup_address": "0xtopup_addr_M1001_user_abc",
  "source_address": "0xsender001",
  "screening_mode": null,
  "message": null,
  "failed_reason": null,
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689300
}

The deposit failed

Stop any automatic crediting and read failed_reason.code. Here Cobo’s compliance checks rejected it, so do not resend — resolve it with Cobo first.

{
  "data_type": "PaymentTopUpUpdate",
  "transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
  "merchant_id": "M1001",
  "payer_id": "P20250619T0310056d7aa",
  "custom_payer_id": "user_abc_10001",
  "status": "Failed",
  "amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": "0xabc123",
  "topup_address": "0xtopup_addr_M1001_user_abc",
  "source_address": "0xsender001",
  "screening_mode": null,
  "message": null,
  "failed_reason": {
    "code": "transaction.rejected_by_compliance",
    "message": "This transaction was rejected by Cobo's compliance checks. Please do not resubmit it; contact Cobo support to resolve the issue first."
  },
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689400
}

`payment.address.updated`

Fires after you replace a payer’s deposit address via Update top-up address. When you receive it, update that payer’s deposit address in your system to updated_address.

Address event content

Field	Type	Description
`data_type`	`string`	Always `PaymentAddressUpdate`.
`merchant_id`	`string`	Which merchant the payer belongs to.
`payer_id`	`string`	The payer whose address changed, as assigned by Cobo.
`custom_payer_id`	`string`	The same payer’s ID in your own system, `null` if you supplied none.
`chain`	`string`	The chain the address is on. Only the address on this chain changed.
`previous_address`	`string`	The address before the replacement.
`updated_address`	`string`	The address to show the payer from now on.

{
  "data_type": "PaymentAddressUpdate",
  "merchant_id": "M1001",
  "payer_id": "P20250619T0310056d7aa",
  "custom_payer_id": "user_abc_10001",
  "chain": "ETH",
  "previous_address": "0xtopup_addr_M1001_user_abc",
  "updated_address": "0xtopup_addr_M1001_user_abc_new"
}

Advanced events

For confirmation counts, on-chain transaction fee breakdowns, and other on-chain transaction detail, subscribe to the advanced events payment.transaction.created, payment.transaction.completed, and payment.transaction.failed. See Advanced events.

Overview

Initial Setup

Pay-In

Funds Management

Reference

Events on this page

`payment.topup.updated`

Trigger conditions

Event content

Failure reasons

Sample events

A deposit is detected

Compliance screening is in progress

Screening needs you to act

The funds are available

The deposit failed

`payment.address.updated`

Address event content

Advanced events

​Events on this page

​payment.topup.updated

​Trigger conditions

​Event content

​Failure reasons

​Sample events

​A deposit is detected

​Compliance screening is in progress

​Screening needs you to act

​The funds are available

​The deposit failed

​payment.address.updated

​Address event content

​Advanced events

Events on this page

`payment.topup.updated`

Trigger conditions

Event content

Failure reasons

Sample events

A deposit is detected

Compliance screening is in progress

Screening needs you to act

The funds are available

The deposit failed

`payment.address.updated`

Address event content

Advanced events