Skip to main content
PUT

Authorizations

BIZ-API-KEY
string
header
required

The API key. For more details, refer to API key.

In the API playground, enter your API secret, and your API key will be accordingly calculated.

Path Parameters

order_id
string
required

The pay-in order ID.

Body

application/json

The request body to update a pay-in order.

expired
boolean
required

Whether to manually expire the order. If set to true, the order status will be updated to Expired.

Example:

true

Response

The request was successful.

order_id
string
required

The unique identifier of the payment order. Cobo assigns this ID when the payment order is created — when that happens depends on which pay-in method you use.

For the direct method, Create pay-in order creates the order synchronously and returns order_id in the response immediately.

For the payment link method, Create order link returns only the hosted link details and does not create an order, so order_id does not exist yet at that point. order_id becomes available only after the payer opens the hosted payment page, selects the payment token and blockchain network, and submits the order — Cobo creates the order and assigns order_id at that moment, not when the link itself was generated.

Example:

"5001"

psp_order_code
string
required

The order identifier for your own internal business order, exactly as you supplied it in psp_order_code when creating the order. This value is unique within your Cobo organization.

Example:

"psp-order-20240601-00789"

fee_amount
string
required

The order-level developer charge credited to your developer balance when the order settles. A value of 0 means that no developer fee was charged and the merchant was credited with the full collected amount.

When the collected payment exactly matches the payable amount, the merchant balance is credited with the payable amount minus fee_amount, and your developer balance is credited with fee_amount. For example, for a payable amount of 104.08 and a fee_amount of 2, the merchant receives 102.08 and you receive 2.

For related fee settings and settlement details, see Merchant management and Accounts and fund allocation.

Example:

"2"

chain_id
string
required

The ID of the blockchain network where the payment transaction should be made.

Example:

"ETH"

payable_amount
string
required

The cryptocurrency amount to be paid for this order.

Example:

"103.03"

exchange_rate
string
required

The exchange rate between payable_currency and pricing_currency, calculated as (pricing_amount + fee_amount) / payable_amount.

This field is only returned when payable_amount was not provided in the order creation request.

Example:

"0.99"

receive_address
string
required

The recipient wallet address to be used for the payment transaction.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

status
enum<string>
required

The current status of the pay-in order:

  • Pending: The order has been created and is awaiting payment. No incoming transaction has been detected.
  • Processing: An incoming transaction has been detected at the recipient address.
  • Completed: The payment has been fully received and is now complete.
  • Expired: The order has reached its expiration time without receiving any payment, or the order has been cancelled by the Update pay-in order operation.
  • Underpaid: The order has reached its expiration time. A payment was received but the amount is less than the order's required amount.
Available options:
Pending,
Processing,
Completed,
Expired,
Underpaid
Example:

"Pending"

received_token_amount
string
required

The total cryptocurrency amount received for this order. Updates until the expiration time. Precision matches the token standard (e.g., 6 decimals for USDT).

Example:

"103.0305"

merchant_id
string

The merchant ID.

Example:

"1001"

merchant_order_code
string

The downstream merchant's order reference, exactly as you supplied it in merchant_order_code when creating the order, if you provided one. Present only when a merchant_order_code was included at order creation.

Example:

"merchant-inv-55231"

pricing_currency
string

The pricing currency of the order.

Example:

"USD"

pricing_amount
string

The base amount of the order, excluding the developer fee (specified in fee_amount).

Example:

"100.00"

payable_currency
string

The ID of the cryptocurrency used for payment.

Example:

"ETH_USDT"

amount_tolerance
string

The allowed amount deviation, with precision up to 1 decimal place.

For example, if payable_amount is 100.00 and amount_tolerance is 0.50:

  • Payer pays 99.55 → Success (difference of 0.45 ≤ 0.5)
  • Payer pays 99.40 → Underpaid (difference of 0.60 > 0.5)
Example:

"0.5"

expired_at
integer

The expiration time of the pay-in order, represented as a UNIX timestamp in seconds.

Example:

1711324800

created_timestamp
integer

The created time of the order, represented as a UNIX timestamp in seconds.

Example:

1744689600

updated_timestamp
integer

The updated time of the order, represented as a UNIX timestamp in seconds.

Example:

1744689600

transactions
object[]

An array of transactions associated with this pay-in order. Each transaction represents a separate blockchain operation related to the settlement process.

currency
string

This field has been deprecated. Please use pricing_currency instead.

order_amount
string

This field has been deprecated. Please use pricing_amount instead.

token_id
string

This field has been deprecated. Please use payable_currency instead.

settlement_status
enum<string>

The current status of a settlement.

  • Pending: The settlement has been created and is awaiting processing.
  • Processing: The settlement is being processed.
  • Completed: The funds have been successfully deposited into the bank account or the withdrawal crypto address.
  • PartiallyCompleted: Some settlement transactions have been completed successfully, while others have failed.
  • Failed: The settlement could not be completed due to an error.
Available options:
Pending,
Processing,
Completed,
PartiallyCompleted,
Failed
Example:

"Pending"