Pay with Cashier (Website Browser) - On-Chain
Accept On-Chain cashier on your website by presenting payment method to the shopper.
On-chain payments support partial payments and multiple transfers for the same order. This is enabled for all merchants on Ethereum, TRON, and BSC. Only USDT transfers on the networks allowed by the order count toward payment.
Step 0. Authentication
How to obtain access token Authentication Reference
Step 1. Initialize a Payment Intent
POST /mch-api/v1/pa/payment_intents/create
- Example Request
{
"amount": "20",
"currency": "USDT",
"merchant_order_id": "P9297895081906",
"payment_method": {
"type": "on_chain",
"on_chain": {
"chain": [
"Ethereum",
"TRON",
"BSC"
],
"is_fee_paid_by_user": true
}
},
"description": "Online Payment",
"expire_time": 1800,
"notify_url": "https://put_your_site_here/example_url"
}
- Request
| REQUEST BODY | Details | Type | Required | Example |
|---|---|---|---|---|
| amount | Payment amount. This is the order amount you would like to charge your customer | string(32) | required | |
| currency | Amount currency. Currently USDT is supported. | string(8) | required | USDT |
| merchant_order_id | The order ID created in merchant's order system that corresponds to this PaymentIntent. Maximum length is 32. | string(32) | required | |
| description | The description of the order | string | required | |
| notify_url | The URL that is used to receive the payment result notification from CBTIS | string | optional | |
| payment_method | object | required | ||
| - type | Specific this payment channel (on_chain) | string | required | on_chain |
| - on_chain | object | required | ||
| - - chain | Select the payment network supported by this payment. If left blank, all payment networks will be supported by default. Please note that different payment networks may charge different fees. | array | optional (default All chain) | |
| - - is_fee_paid_by_user | Set this as true if you're using fee paid by user flow. | boolean | optional (default false) | |
| expire_time | Payment expiry duration in seconds, measured from order creation. A positive value is used as supplied; omitted or 0 defaults to 7200 seconds. Negative values are rejected. | integer | optional | 1800 |
- Example Response
{
"code": 0,
"data": {
"amount": "20",
"create_time": "2025-08-18T03:23:46+08:00",
"currency": "USDT",
"merchant_order_id": "P9297895081906",
"next_action": {
"redirect_url": "https://app.aiscpay.com/payment/v1/C96458626019020000",
"type": "redirect"
},
"order_id": "C96458626019020000",
"status": "PENDING"
},
"message": "ok",
"rid": "7fa547cb4c1e428fb996b2c31180dfa7"
}
Redirect the shopper to the on-chain cashier using next_action.redirect_url.
The first valid payment fixes the order's payment network and the full order fee. Subsequent payments must use that same network and the order's payment address; payments on another network do not count. Different sender addresses may pay the same order. The cashier shows the cumulative amount received and the remaining amount, and updates its QR code and wallet payment button to the remaining amount.
Any valid USDT payment greater than zero counts, including amounts below the order's original minimum amount. Each transfer is counted once even if it is scanned again. Existing network confirmation rules apply.
Step 2. Get payment notify
If notify_url is supplied, the system sends a payment webhook for each accepted
transfer. A transfer that leaves the order underpaid produces
partial_payment_success. The transfer that completes payment produces only
payment_success.
How to verify our notify message Webhook Verify Reference
- Example completed-payment webhook
{
"notify_type": "payment_success",
"data": {
"event_id": 1,
"order_id": "C96245645019020000",
"merchant_order_id": "P9297895081903",
"order_amount": "20",
"order_currency": "USDT",
"settle_amount": "20",
"settle_currency": "USDT",
"create_time": "2025-08-18T03:23:46+08:00",
"pay_time": "2025-08-18T03:23:46+08:00"
}
}
Partial-payment webhooks
For an order of 100 USDT where the merchant pays the fee, a first transfer of 30 USDT produces the following webhook:
{
"notify_type": "partial_payment_success",
"data": {
"event_id": 1,
"order_id": "C96245645019020000",
"merchant_order_id": "P9297895081903",
"order_amount": "100",
"order_currency": "USDT",
"partial_payment_amount": "30",
"settle_amount": "0",
"settle_currency": "USDT",
"create_time": "2025-08-18T03:23:46+08:00",
"pay_time": "2025-08-18T03:25:00+08:00"
}
}
A second transfer of 20 USDT produces another partial_payment_success, with
event_id: 2 and partial_payment_amount: "50". A final transfer of 50 USDT
produces payment_success with event_id: 3. If the full order fee is 2 USDT,
the final settle_amount is "98" and order_amount is still "100".
The final callback does not contain partial_payment_amount.
| Field | Meaning |
|---|---|
| event_id | Integer payment sequence within this order, starting at 1. Present in both webhook types. Retries retain the same value. Use order_id and event_id together to deduplicate notifications. |
| order_amount | Original order amount, unchanged by partial payments or overpayments. |
| order_currency | Original order currency, currently USDT. |
| partial_payment_amount | Cumulative actual USDT received on the fixed payment network, before fees. Present only in partial_payment_success, and expressed as a decimal string. It is not the latest transfer's amount. |
| settle_amount | "0" while payment is partial. In a completed-payment callback, the amount credited to the merchant wallet after applying the fee rules. |
| settle_currency | Settlement currency, currently USDT. |
| pay_time | Time this transfer was accepted by the system. In the final callback, the time the order became fully paid. |
Respond with HTTP 200 to acknowledge a webhook. Failed deliveries are retried
using the original payload and signature. Notifications can be duplicated or
arrive out of order; deduplicate by (order_id, event_id) and do not let an older
partial notification overwrite a completed order. Query the order to reconcile
the current payment and settlement status.
Fees, expiry, and settlement
- If
is_fee_paid_by_useris false, the order is fully paid when cumulative receipts reach the order amount. Settlement credits the original order amount minus the full order fee, with a minimum credit of zero. - If
is_fee_paid_by_useris true, cumulative receipts must reach the original order amount plus the full order fee. Settlement credits the original order amount. - Network and service fees are calculated for the full order using the first payment network. Fees are charged once when settlement occurs; individual partial transfers do not incur another order fee.
- Partial orders are not automatically settled. At expiry, their status becomes
EXPIRED; the cumulative amount and payment records are retained. Further transfers do not count toward an expired order. - For an expired order with partial receipts, the merchant can select Settle
Manually on its payment detail page in the merchant portal. Manual settlement
credits
max(cumulative receipts - full order fee, 0)to the merchant's wallet on the fixed payment network, regardless of the original fee bearer. If the result is zero, no wallet credit is created and the order is marked settled. - Manual settlement leaves the payment status as
EXPIREDand changessettlement_statustoSETTLED. It permanently closes the order, creates no payment webhook, and cancels queued callback retries for this order. - Overpayments do not increase the automatic settlement amount. Completed-payment callbacks always use the original order amount. Transfers after automatic or manual settlement do not produce further payment events or wallet credits.
- Wallet credits use six decimal places; any smaller fraction is rounded down.
Step 3. Retrieve a payment
Retrieve a payment by platform order ID or merchant order ID.
POST /mch-api/v1/pa/payment_intents/query
- Example Request
{
"order_id": "P991289984923795789123",
"merchant_order_id": "P9297895081903"
}
- Request
| REQUEST BODY | Details | Type | Required | Example |
|---|---|---|---|---|
| order_id | Platform order id from payment request. | string(32) | conditional (required if merchant_order_id is empty) | |
| merchant_order_id | Merchant order id from your creation of payment. | string(32) | conditional (required if order_id is empty) |
- Example Response
{
"code": 0,
"data": {
"amount": "20",
"create_time": "2025-08-18T03:23:46+08:00",
"currency": "USDT",
"merchant_order_id": "P9297895081906",
"order_id": "C96458626019020000",
"status": "PENDING"
},
"message": "ok",
"rid": "863b73d9d0db4b35a1827c6a4396e988"
}
For an on-chain order, the query response also contains payment progress:
{
"code": 0,
"data": {
"amount": "100",
"currency": "USDT",
"merchant_order_id": "P9297895081903",
"order_id": "C96245645019020000",
"status": "PARTIAL_SUCCESS",
"partial_payment_amount": "50",
"remaining_amount": "50",
"payment_chain": "TRON",
"payment_count": 2,
"settlement_status": "UNSETTLED",
"settle_amount": "0",
"settle_currency": "USDT",
"create_time": "2025-08-18T03:23:46+08:00",
"pay_time": "2025-08-18T03:26:00+08:00",
"expire_time": "2025-08-18T03:53:46+08:00"
},
"message": "ok"
}
| Field | Meaning |
|---|---|
| partial_payment_amount | Cumulative actual receipts, before fees. Unlike webhooks, queries include this field for all on-chain order states. |
| remaining_amount | Amount still required on the fixed payment network, including user-paid fees when applicable. Zero after settlement. Before the first payment, this is the original order amount; the cashier displays each network's fee-inclusive payable amount. |
| payment_chain | Network selected by the first payment. Empty before the first payment. |
| payment_count | Number of accepted, distinct transfers. |
| settlement_status | UNSETTLED or SETTLED. An expired order can be settled manually without becoming SUCCESS. |
| settle_amount | Wallet credit amount. Zero before settlement. |
| expire_time | Order expiry timestamp in RFC 3339 format. The create request's field with the same name is a duration in seconds. |
- Explain of status
| STATUS CODE | Details |
|---|---|
| PENDING | The Payment is pending the final result from the provider. No further action is required. |
| PARTIAL_SUCCESS | One or more payments have been received, but the cumulative amount has not reached the required total. The order is not settled and may receive further payments on its fixed network before expiry. |
| SUCCESS | The Payment has succeeded. The payment transaction is complete. |
| EXPIRED | Payment expired before completion. Any partial receipts and payment records are retained. Check settlement_status to distinguish an unsettled expired order from an order settled manually. |
| FAILED | Payment failed. You can contact our saler to the detail reason. |