Payments
Payment Orders
Check payment-order status and trigger the built-in payment webhook simulation.
Flow Summary
The current payment-order flow is:
Step 1. Read a payment orderGET /api/v2/payment-orders/{merchant_order_sn}
Step 2. Simulate a paid webhookPOST /api/v2/payment-orders/paid
Both routes should be treated as protected and require Authorization.
1. Get Payment Order By Merchant Order SN
GET /api/v2/payment-orders/{merchant_order_sn}
Returns the payment-order snapshot for one merchant order serial number.
Path parameter
merchant_order_snis required
Response shape
The response includes fields such as:
idorder_snmerchant_order_snamount_usdtactual_usdtmerchant_usdtchain_typepayment_addresspayment_urlstatustransaction_hashconfirmationswebhook_urlcallback_urlqr_codeevent_typeexchange_ratenet_amountexpires_atexpires_incard_type
Important backend behavior
- if
expires_athas already passed, the response can return the order asEXPIRED expires_inis calculated at response time in seconds; once expired, it becomes0card_typeis included when the order is linked to a card request
Error behavior
- missing path values return a logical
400 - unknown order numbers return a logical
404
2. Simulate Paid Webhook
POST /api/v2/payment-orders/paid
Triggers the built-in test webhook flow for a payment order.
Request body
{
"merchant_order_sn": "PO-20260228-0001"
}
Success response shape
The response returns a generated payload with fields such as:
order_snmerchant_order_snamount_usdtactual_usdtmerchant_usdtstatuschain_typetransaction_hashpaid_attimestamppayment_address
Important backend behavior
- this is a simulation/testing endpoint, not a real payment callback receiver
- it builds a synthetic
PAIDpayload and sends it to the configured webhook target merchant_usdtis currently simulated asamount_usdt * 0.9- the handler returns success immediately; it does not wait for the downstream webhook request to finish
- a successful API response here does not guarantee that the remote webhook accepted the request
Encryption note
- this route accepts plain JSON and the encrypted wrapper format described in the overview
Integration Notes
- Use
GET /api/v2/payment-orders/{merchant_order_sn}for status polling after card-request payment creation. - Do not treat
POST /api/v2/payment-orders/paidas a production settlement API; it is a simulation helper.