Payment collection in order mode

​

Order identification fields

• PSP order code (psp_order_code): Set this field to your own internal business order identifier. This field is required, and the value must be unique within your Cobo organization.
• Merchant order code (merchant_order_code): Set this field only if you are a platform or payment service provider (PSP) serving a downstream merchant that has its own separate order reference to track. This field is optional.

• Platform or PSP serving a downstream merchant:

{
  "merchant_id": "M1001",
  "psp_order_code": "PSP-20260729-0042",
  "merchant_order_code": "SHOP88-INV-556213",
  "pricing_currency": "USD",
  "pricing_amount": "100",
  "payable_currency": "ETH_USDT"
}

• Direct merchant serving payers:

{
  "merchant_id": "M1001",
  "psp_order_code": "PSP-20260729-0042",
  "pricing_currency": "USD",
  "pricing_amount": "100",
  "payable_currency": "ETH_USDT"
}

• **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

• 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, you can configure this order-level charge to collect a developer share from this specific order. This is distinct from the merchant-level developer_fee_rate used in Top-up mode; for details on configuring that rate, refer to Merchants. In a normal settlement, where the payer’s deposit exactly matches the payable amount, the developer account receives fee_amount and the merchant account receives the remainder:
  • When fee_amount is 0, the merchant account receives the full collected amount.
  • When payable_amount is 104.08 and fee_amount is 2, an exact 104.08 deposit credits 102.08 to the merchant account and 2 to the developer account.
  For overpayments and underpayments, funds are settled using the same ratio between fee_amount and the payable amount, rather than always subtracting the literal fee_amount value. If a deposit is processed after the order has already reached the EXPIRED, UNDERPAID, or COMPLETED status, the entire deposit is credited to the developer account regardless of fee_amount. For more details on how funds are settled and allocated between accounts, refer to Accounts and fund allocation.

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.

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.

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.