Skip to main content

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 BODYDetailsTypeRequiredExample
amountPayment amount. This is the order amount you would like to charge your customerstring(32)required
currencyAmount currency. Currently USDT is supported.string(8)requiredUSDT
merchant_order_idThe order ID created in merchant's order system that corresponds to this PaymentIntent. Maximum length is 32.string(32)required
descriptionThe description of the orderstringrequired
notify_urlThe URL that is used to receive the payment result notification from CBTISstringoptional
payment_methodobjectrequired
- typeSpecific this payment channel (on_chain)stringrequiredon_chain
- on_chainobjectrequired
- - chainSelect 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.arrayoptional (default All chain)
- - is_fee_paid_by_userSet this as true if you're using fee paid by user flow.booleanoptional (default false)
expire_timePayment 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.integeroptional1800
  • 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.

FieldMeaning
event_idInteger 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_amountOriginal order amount, unchanged by partial payments or overpayments.
order_currencyOriginal order currency, currently USDT.
partial_payment_amountCumulative 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_currencySettlement currency, currently USDT.
pay_timeTime 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_user is 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_user is 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 EXPIRED and changes settlement_status to SETTLED. 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 BODYDetailsTypeRequiredExample
order_idPlatform order id from payment request.string(32)conditional (required if merchant_order_id is empty)
merchant_order_idMerchant 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"
}
FieldMeaning
partial_payment_amountCumulative actual receipts, before fees. Unlike webhooks, queries include this field for all on-chain order states.
remaining_amountAmount 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_chainNetwork selected by the first payment. Empty before the first payment.
payment_countNumber of accepted, distinct transfers.
settlement_statusUNSETTLED or SETTLED. An expired order can be settled manually without becoming SUCCESS.
settle_amountWallet credit amount. Zero before settlement.
expire_timeOrder expiry timestamp in RFC 3339 format. The create request's field with the same name is a duration in seconds.
  • Explain of status
STATUS CODEDetails
PENDINGThe Payment is pending the final result from the provider. No further action is required.
PARTIAL_SUCCESSOne 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.
SUCCESSThe Payment has succeeded. The payment transaction is complete.
EXPIREDPayment 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.
FAILEDPayment failed. You can contact our saler to the detail reason.