Skip to main content
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.
Order mode is suitable for scenarios that require specifying a specific payment amount and time limit. In this mode, Cobo creates payment orders with the following characteristics:
  • Fixed amount: The amount payable is specified when the order is created
  • Validity period: Payers need to complete payment within the specified time
  • Exception handling: Supports handling various exception situations, including:
    • Canceling orders that have not been paid
    • Initiating refunds for paid orders
    • Handling payment exceptions such as overpayment, underpayment, and late payment

​
Create order

You can create an order in two ways:
  • Call Create pay-in order to directly create a payment order. After a successful call, you will receive information such as the payable amount and payment address.
  • Call Create order link to generate a payment link. This link will direct users to a payment page provided by Cobo, where they can create an order and complete payment without you needing to develop the front-end interaction. You can also embed this payment page into your website or application using an iFrame.

​
Prerequisites

You have completed all the steps mentioned in Preparation.

​
Implementation steps

The following diagram shows the complete interaction process between payers, merchants, and Cobo during the order payment process:
When creating an order, you must choose one of the following two amount parameter combinations based on your business model:
  • **Option 1: **The original order is priced in fiat currency, and you collect payment in cryptocurrency
    • Required: pricing_currency, pricing_amount, payable_currency
    • Not required: payable_amount
  • **Option 2: **The original order is priced in cryptocurrency, and you collect the payment directly in the same cryptocurrency
    • Required: payable_currency, payable_amount
    • Not required: pricing_currency, pricing_amount
Requests that include parameters from both options, or that do not conform to either combination, will be rejected.You may refer to the following definitions of order amount–related fields:
  • Pricing Currency (pricing_currency):
    The fiat currency used to price the goods. For supported fiat currencies, please refer to Supported Currencies and Blockchains.
    This field is optional and is not required if your goods are priced in cryptocurrency.
  • Pricing Amount (pricing_amount):
    The fiat price of the goods, denominated in the currency specified by pricing_currency.
    This field is optional and is not required if your goods are priced in cryptocurrency.
  • Payable Currency (payable_currency):
    The cryptocurrency the payer needs to pay. For supported cryptocurrencies, please refer to Supported Currencies and Blockchains.
  • Payable Amount (payable_amount):
    The amount of cryptocurrency the payer needs to pay, denominated in the currency specified by payable_currency.
    This field is optional:
    • If payable_amount is specified, the system will use this value directly as the amount the payer needs to pay.
    • If payable_amount is not specified, the system will calculate the payable amount using the real-time exchange rate:
      Payable Amount = (Order Amount + Developer Fee) / Exchange Rate.
      The exchange rate is based on the rate returned by the Get exchange rate operation at the time the order is created.
  • Developer Fee (fee_amount):
    If you are a platform serving multiple downstream merchants and need to distribute revenue between yourself and those merchants, you can configure this fee to achieve revenue sharing.
    This fee is denominated in the cryptocurrency specified by payable_currency.
    The actual developer fee received is calculated as:
    Actual Developer Fee = (Configured Developer Fee / Payable Amount) × Actual Collected Amount. For more details, please refer to Accounts and Fund Allocation.
If you are a merchant (serving users directly), you typically do not need to set the developer fee.
The table below shows how the payable amount is determined in four different configuration scenarios:
Scenario 1Scenario 2
Scenario Description- Pricing amount in fiat currency
- Developer fee not set
- System calculates payable amount		- Pricing amount in cryptocurrency
- Developer fee set
- Custom payable amount
pricing_currency"USD"Not set
pricing_amount"100"Not set
payable_currency"ETH_USDT""ETH_USDT"
payable_amountNot set"104.08"
fee_amount"0" or not set"2"
Real-time exchange rate0.99N/A (custom payable amount used)
Calculation Process(100 + 0) / 0.99Directly uses specified payable_amount
Final payable amount"101.01""104.08"
Developer Fee Calculation02/104.08*104.08
Final Developer Fee"0""0"

​
Query order status

You can subscribe to the following webhook events to receive real-time update notifications of order status. Refer to Webhook reference to understand the trigger time and returned data structure of each event.
  • payment.status.updated
  • payment.transaction.late
  • payment.transaction.completed
You can also actively query order status through Payments App or Payments API.
  1. Log in to Cobo Portal development environment or production environment.
  2. In the left navigation bar, click Apps, then click the Payments card to launch the App.
  3. In the App’s left navigation bar, click Pay-In > Orders. You can view detailed information of all orders on this page, such as order ID, merchant information, payment amount, order status, etc.
  4. After the payer completes payment and the transaction passes compliance screening, the order status will change to Completed.
View order list

​
Exception situations

In order mode, you may need to handle the following exception situations.

​
Cancel payment order

When a payment order is in the Pending status, that is, no deposit transaction has been detected yet, you can call Update pay-in order to cancel the order. After cancellation, the order status will change to Expired.

​
Overpayment, underpayment, and late payment

The following three exception situations may occur during the payment process:
Exception situationDescriptionImpact
OverpaymentWithin the order validity period, the payer’s actual payment amount exceeds the payable amountThe final order status is Completed.
UnderpaymentWithin the order validity period, the payer’s actual payment amount is less than the amount payableThe order status is Underpaid (final state).
Late paymentThe payer makes the first or subsequent payment after the order expiresDoes not change the order status. Each late payment will trigger one payment.transaction.late webhook event.
Accounts and fund allocation details how Cobo handles funds in the case of overpayment, underpayment, and late payment.

​
Handle refund requests

You can initiate a refund order through Payments App or Payments API to refund funds to the payer. The following diagram shows the interaction process between payers, merchants, and Cobo during the refund process.

​
Create refund order

  1. Log in to Cobo Portal development environment or production environment.
  2. In the left navigation bar, click Apps, then click the Payments card to launch the App.
  3. In the App’s left navigation bar, click Pay-In > Orders.
  4. Select the target order, then click the View Details button on the right.
  5. On the order details page, click the Refund button.
  6. In the pop-up form:
    • Select the source of the refund amount. You can choose Merchant balance or Developer balance.
    • Enter the refund amount. This amount must not exceed the corresponding merchant balance or developer balance.
    • (Optional) Enter the developer fee amount. This fee will be deducted from the refund amount and credited to the developer balance. For a detailed description of developer fees, refer to Accounts and fund allocation.
    • Enter the receiving address. You can click Use original payment address, and the system will automatically fill in the original payment address for this order. If you want to refund to another address, you can also manually enter the target address.
  7. Click Preview to confirm that all information is correct, then click Submit to create the refund order.

​
Query refund order status

You can subscribe to the payment.refund.status.updated event to receive real-time updates on refund order status. Refer to Webhook reference to understand the detailed trigger conditions and returned data structure of each event. You can also actively query refund order status through Payments App or Payments API.
  1. Log in to Cobo Portal development environment or production environment.
  2. In the left navigation bar, click Apps, then click the Payments card to launch the App.
  3. In the App’s left navigation bar, click Pay-In > Orders.
  4. Click the Refunds tab. In the refund order list, find the target order, then click the View Details button on the right.
  5. View the order status on the refund order details page.

​
Compliance screening failure

When a transaction receives the payment.transaction.failed event , this indicates that the transaction has failed to pass compliance screening by Cobo KYT or Screening App. In this case, you need to follow these steps to handle it:
  • If the transaction subsequently passes manual review:
    • If the order has not expired: The funds will be counted towards the order’s actual received amount, and the order status will be updated accordingly based on the actual received amount
    • If the order has expired: The system will trigger the payment.transaction.late event, and all funds will be credited to the developer balance
  • If the transaction ultimately fails manual review:
    • The funds will be frozen and will not be counted towards the order’s actual received amount
    • The order status will remain unchanged
    • The payer needs to redeposit sufficient funds and pass compliance screening within the order validity period for the order to change to Completed status
For isolated or frozen funds:
  • Cobo KYT: Please contact the Cobo support team through [email protected] for handling
  • Screening App: You can evaluate and handle it yourself within the application

​
Minimum Deposit Threshold

  • To optimize your account costs and prevent situations where the collection fee exceeds the transaction value, a minimum deposit threshold is applied. Transactions with a value below 0.05 USDT (or equivalent) will not be processed for automatic credit.
    Note: If you need to manually recover accumulated funds below this threshold, please contact Cobo Support for assistance in extracting them from the consolidation addresses.