> ## 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.

# Orders

These events cover Order Mode, where each payment order has its own address, expiry, and expected amount. Read [Events overview](https://cobo.com/payments/payments/en/guides/events/overview.md) 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.order.updated`](#payment-order-updated) | 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. | **Standard** |

## `payment.order.updated`

The main event for Order Mode.

### Trigger conditions

**One event per change of the order's `status`.** An event is also sent without a status change when a deposit needs your attention (for example, it needs action, it failed, or it is a late payment); `notice_type` gives the reason. The table below lists every trigger.

The order's `status` changes as follows; final statuses are shown in green:

![Order status flow](https://mintcdn.com/mcpnow/VoBPAZOrg_70X0ZK/payments/en/images/payments/events/orders-status.svg?fit=max\&auto=format\&n=VoBPAZOrg_70X0ZK\&q=85\&s=e99b37779a7d6d0da2ee87492e1c2430)

Each deposit to the order (an entry in `transactions`) has its own `status`, which changes as follows:

![Order deposit status flow](https://mintcdn.com/mcpnow/VoBPAZOrg_70X0ZK/payments/en/images/payments/events/order-deposit-status.svg?fit=max\&auto=format\&n=VoBPAZOrg_70X0ZK\&q=85\&s=e51b3d45ed55d9828efeed442f85e1dc)

An intermediate status may not appear if it moves on to the next status quickly, and events may arrive out of order; see [Event ordering](https://cobo.com/payments/payments/en/guides/events/overview.md#event-ordering).

| Trigger condition | `status` | `notice_type` | What to do |
| - | - | - | - |
| The order is created | `Pending` | `null` | Record the order and show the payer what to pay. |
| The **first** deposit for this order is detected | `Processing` | `null` | Update progress. Do not release goods. |
| A deposit enters `ActionRequired` | `Processing` | `PaymentUpdated` | Act on that entry's `message`. Those funds do not count towards the order until you do. |
| A deposit fails | `Processing` | `PaymentFailed` | Read that entry's `failed_reason.code`. Those funds neither count towards the order nor get credited; follow your own rules for asking the payer to pay again. |
| Cumulative receipts reach the expected amount (less the tolerance, if one is set) | `Completed` (final) | `null` | The order is complete; release goods. |
| The validity period ends with completed deposits that did not reach the threshold | `Underpaid` (final) | `null` | Handle as underpaid. Do not treat as fully paid. |
| The validity period ends with no completed deposit | `Expired` (final) | `null` | Close the payment window. Create a new order to keep collecting. |
| The order is already final and another deposit arrives **and clears screening** | final | `LatePaymentReceived` | The funds go to your developer account (to the merchant account on a Starter package). Decide whether to refund them based on your own business rules. |
| The order is already final and the late deposit **fails** (for example, fails screening) | final | `PaymentFailed` | The funds will not be credited. Decide how to handle them based on the entry's `failed_reason.code` and your own business rules. |

**Nothing fires** when the second and later deposits are detected, when a deposit enters screening, when a deposit clears screening, or when a late deposit has arrived but not finished screening.

### Event content

| Field | Type | Description |
| - | - | - |
| `data_type` | `string` | Always `PaymentOrderUpdate`. |
| `order_id` | `string` | The order ID. |
| `psp_order_code` | `string` | The order identifier for your own internal business order, exactly as you supplied it in `psp_order_code` when creating the order. |
| `merchant_id` | `string` | The merchant ID. |
| `merchant_order_code` | `string` | The downstream merchant's order reference, exactly as you supplied it in `merchant_order_code` when creating the order; `null` if you did not provide one. |
| `receive_address` | `string` | The address the payer sends funds to. |
| `expired_at` | `integer` | The order's expiration time, in Unix timestamp (seconds). |
| `status` | `string` | The order's current status; see [Trigger conditions](#trigger-conditions) for what each means: • `Pending` • `Processing` • `Completed` • `Underpaid` • `Expired` |
| `notice_type` | `string` | The deposit change this event reports: • `PaymentUpdated` — a deposit entered `ActionRequired`. • `PaymentFailed` — a deposit failed. • `LatePaymentReceived` — a late payment arrived and has cleared compliance screening. |
| `requested_amount` | `object` | The total the order expects, which is the order's `payable_amount`. |
| `requested_amount.amount` | `string` | The amount. See [Amounts](https://cobo.com/payments/payments/en/guides/events/overview.md#amounts) for the format. |
| `requested_amount.token_id` | `string` | The token ID. |
| `requested_amount.chain_id` | `string` | The chain ID. |
| `credited_amount` | `object` | The total received and counted towards the order. It excludes deposits not yet completed (detected or in compliance screening), rejected deposits, and late payments (entries with `is_late` `true`). |
| `credited_amount.amount` | `string` | The amount. See [Amounts](https://cobo.com/payments/payments/en/guides/events/overview.md#amounts) for the format. |
| `credited_amount.token_id` | `string` | The token ID. |
| `credited_amount.chain_id` | `string` | The chain ID. |
| `outstanding_amount` | `object` | How much more the payer still owes = `requested_amount` − `credited_amount`. Its floor is `0`: it is `0` on overpayment and does not show how much was overpaid. • ⚠️ It can still be greater than `0` when `status` is `Completed` (the order completed within `amount_tolerance`). Cobo then treats the order as paid in full; whether to collect the difference from the payer is your decision. |
| `outstanding_amount.amount` | `string` | The amount. See [Amounts](https://cobo.com/payments/payments/en/guides/events/overview.md#amounts) for the format. |
| `outstanding_amount.token_id` | `string` | The token ID. |
| `outstanding_amount.chain_id` | `string` | The chain ID. |
| `transactions` | `array` | Every deposit to the order so far. ⚠️ Excludes deposits whose amount does not exceed the dust threshold. |
| `transactions.transaction_id` | `string` | The deposit's ID in Cobo. |
| `transactions.tx_hash` | `string` | The deposit's on-chain transaction hash. |
| `transactions.amount` | `object` | The deposit's amount. |
| `transactions.amount.amount` | `string` | The amount. See [Amounts](https://cobo.com/payments/payments/en/guides/events/overview.md#amounts) for the format. |
| `transactions.amount.token_id` | `string` | The token ID. |
| `transactions.amount.chain_id` | `string` | The chain ID. |
| `transactions.source_address` | `string` | The payer's on-chain address; `null` when it cannot be identified. |
| `transactions.status` | `string` | The deposit's status, with the same values as a [top-up](https://cobo.com/payments/payments/en/guides/events/top-up.md#trigger-conditions): • `Detected` • `PendingScreening` • `ActionRequired` • `Completed` • `Failed` |
| `transactions.is_late` | `boolean` | `true` means the deposit completed after the order reached a final status, so it does not count towards `credited_amount`. |
| `transactions.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. |
| `transactions.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. |
| `transactions.failed_reason` | `object` | Set when the deposit's `status` is `Failed`; `null` otherwise. |
| `transactions.failed_reason.code` | `string` | The failure code. See [Failure reasons](#failure-reasons) for the values. |
| `transactions.failed_reason.message` | `string` | The failure reason. |
| `created_timestamp` | `integer` | When the order was created, in Unix timestamp (seconds). |
| `updated_timestamp` | `integer` | When the order last changed status, in Unix timestamp (seconds). • ⚠️ A change to a deposit's status (such as a deposit failing) does not change the order's status, so it does not update this timestamp. |

### Failure reasons

| `code` | What happened | What to do |
| - | - | - |
| `transaction.rejected_by_screening_app` | Your own compliance team rejected this deposit in the [Screening App](https://manuals.cobo.com/en/apps/screening/introduction). | Review the case there. |
| `transaction.rejected_by_compliance` | Cobo's compliance checks rejected this deposit. | Raise it with Cobo. |
| `transaction.failed` | Failed for any other reason. | Raise a case and quote the entry's `transaction_id`. |

### Sample events

Each sample shows the `data` object only. The envelope around it is the same for every event — see [Event structure](https://cobo.com/payments/payments/en/guides/events/overview.md#event-structure).

#### The order is created

```json theme={null}
{
  "data_type": "PaymentOrderUpdate",
  "order_id": "order_001",
  "psp_order_code": "psp_order_001",
  "merchant_id": "M1001",
  "merchant_order_code": "shop_20260921_0001",
  "status": "Pending",
  "notice_type": null,
  "receive_address": "0xorder_addr_001",
  "expired_at": 1744692600,
  "requested_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "credited_amount": { "amount": "0", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "outstanding_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "transactions": [],
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689000
}
```

#### The first deposit is detected

Update progress. Do not release goods: the deposit is still in screening, so `credited_amount` is still `0`.

```json theme={null}
{
  "data_type": "PaymentOrderUpdate",
  "order_id": "order_001",
  "psp_order_code": "psp_order_001",
  "merchant_id": "M1001",
  "merchant_order_code": "shop_20260921_0001",
  "status": "Processing",
  "notice_type": null,
  "receive_address": "0xorder_addr_001",
  "expired_at": 1744692600,
  "requested_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "credited_amount": { "amount": "0", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "outstanding_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "transactions": [
    {
      "transaction_id": "d1f2e3c4-1111-4a2b-9c3d-000000000001",
      "tx_hash": "0xdep001",
      "amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer001",
      "status": "PendingScreening",
      "screening_mode": "IntegratedVendor",
      "message": null,
      "is_late": false,
      "failed_reason": null
    }
  ],
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689100
}
```

#### A deposit needs you to act

`notice_type` is `PaymentUpdated` and the order `status` has not changed. Act on that entry's `message`; those funds stay held until you do. Other deposits keep accumulating normally.

```json theme={null}
{
  "data_type": "PaymentOrderUpdate",
  "order_id": "order_001",
  "psp_order_code": "psp_order_001",
  "merchant_id": "M1001",
  "merchant_order_code": "shop_20260921_0001",
  "status": "Processing",
  "notice_type": "PaymentUpdated",
  "receive_address": "0xorder_addr_001",
  "expired_at": 1744692600,
  "requested_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "credited_amount": { "amount": "0", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "outstanding_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "transactions": [
    {
      "transaction_id": "d1f2e3c4-1111-4a2b-9c3d-000000000001",
      "tx_hash": "0xdep001",
      "amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer001",
      "status": "ActionRequired",
      "screening_mode": "IntegratedVendor",
      "message": "A manual compliance review by your team is required before these funds can be made available. Please complete it in the Screening App.",
      "is_late": false,
      "failed_reason": null
    }
  ],
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689100
}
```

#### A deposit failed

`notice_type` is `PaymentFailed` and the order `status` has not changed. Those funds do not count towards `credited_amount`; use the entry's `failed_reason.code` to decide what to tell the payer.

```json theme={null}
{
  "data_type": "PaymentOrderUpdate",
  "order_id": "order_001",
  "psp_order_code": "psp_order_001",
  "merchant_id": "M1001",
  "merchant_order_code": "shop_20260921_0001",
  "status": "Processing",
  "notice_type": "PaymentFailed",
  "receive_address": "0xorder_addr_001",
  "expired_at": 1744692600,
  "requested_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "credited_amount": { "amount": "0", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "outstanding_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "transactions": [
    {
      "transaction_id": "d1f2e3c4-1111-4a2b-9c3d-000000000001",
      "tx_hash": "0xdep001",
      "amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer001",
      "status": "Failed",
      "screening_mode": null,
      "message": null,
      "is_late": false,
      "failed_reason": {
        "code": "transaction.rejected_by_screening_app",
        "message": "This transaction was rejected by your compliance team in the Screening App. Please review the case in the Screening App and resubmit only after it has been cleared."
      }
    }
  ],
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744689100
}
```

#### The order is paid in full

The order is complete; release the goods.

```json theme={null}
{
  "data_type": "PaymentOrderUpdate",
  "order_id": "order_001",
  "psp_order_code": "psp_order_001",
  "merchant_id": "M1001",
  "merchant_order_code": "shop_20260921_0001",
  "status": "Completed",
  "notice_type": null,
  "receive_address": "0xorder_addr_001",
  "expired_at": 1744692600,
  "requested_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "credited_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "outstanding_amount": { "amount": "0", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "transactions": [
    {
      "transaction_id": "d1f2e3c4-1111-4a2b-9c3d-000000000001",
      "tx_hash": "0xdep001",
      "amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer001",
      "status": "Completed",
      "screening_mode": null,
      "message": null,
      "is_late": false,
      "failed_reason": null
    },
    {
      "transaction_id": "d1f2e3c4-1111-4a2b-9c3d-000000000002",
      "tx_hash": "0xdep002",
      "amount": { "amount": "42", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer001",
      "status": "Completed",
      "screening_mode": null,
      "message": null,
      "is_late": false,
      "failed_reason": null
    }
  ],
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744690100
}
```

#### The order expired underpaid

Handle it as underpaid. `outstanding_amount` is the shortfall, and the second deposit was rejected so it never counted.

```json theme={null}
{
  "data_type": "PaymentOrderUpdate",
  "order_id": "order_002",
  "psp_order_code": "psp_order_002",
  "merchant_id": "M1001",
  "merchant_order_code": "shop_20260921_0002",
  "status": "Underpaid",
  "notice_type": null,
  "receive_address": "0xorder_addr_002",
  "expired_at": 1744692600,
  "requested_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "credited_amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "outstanding_amount": { "amount": "42", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "transactions": [
    {
      "transaction_id": "d1f2e3c4-2222-4a2b-9c3d-000000000001",
      "tx_hash": "0xdep101",
      "amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer002",
      "status": "Completed",
      "screening_mode": null,
      "message": null,
      "is_late": false,
      "failed_reason": null
    },
    {
      "transaction_id": "d1f2e3c4-2222-4a2b-9c3d-000000000002",
      "tx_hash": "0xdep102",
      "amount": { "amount": "42", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer002",
      "status": "Failed",
      "screening_mode": null,
      "message": null,
      "is_late": false,
      "failed_reason": {
        "code": "transaction.rejected_by_screening_app",
        "message": "This transaction was rejected by your compliance team in the Screening App. Please review the case in the Screening App and resubmit only after it has been cleared."
      }
    }
  ],
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744692600
}
```

#### Money arrives after the order ended

`notice_type` is `LatePaymentReceived` and `status` keeps its final value. The funds go to your developer account (to the merchant account on a Starter package); decide whether to refund them based on your own business rules. **`credited_amount` does not change** — the late entry is `Completed` but does not count towards the order.

```json theme={null}
{
  "data_type": "PaymentOrderUpdate",
  "order_id": "order_002",
  "psp_order_code": "psp_order_002",
  "merchant_id": "M1001",
  "merchant_order_code": "shop_20260921_0002",
  "status": "Underpaid",
  "notice_type": "LatePaymentReceived",
  "receive_address": "0xorder_addr_002",
  "expired_at": 1744692600,
  "requested_amount": { "amount": "102", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "credited_amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "outstanding_amount": { "amount": "42", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "transactions": [
    {
      "transaction_id": "d1f2e3c4-2222-4a2b-9c3d-000000000001",
      "tx_hash": "0xdep101",
      "amount": { "amount": "60", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer002",
      "status": "Completed",
      "screening_mode": null,
      "message": null,
      "is_late": false,
      "failed_reason": null
    },
    {
      "transaction_id": "d1f2e3c4-2222-4a2b-9c3d-000000000003",
      "tx_hash": "0xdep103",
      "amount": { "amount": "42", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "source_address": "0xpayer002",
      "status": "Completed",
      "screening_mode": null,
      "message": null,
      "is_late": true,
      "failed_reason": null
    }
  ],
  "created_timestamp": 1744689000,
  "updated_timestamp": 1744692600
}
```

## Advanced events

For the on-chain transaction detail behind each deposit to the order, subscribe to the advanced events `payment.order.status.updated`, `payment.transaction.completed`, `payment.transaction.failed`, and `payment.transaction.late`. See [Advanced events](https://cobo.com/payments/payments/en/guides/events/advanced.md).