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 order
GET /api/v2/payment-orders/{merchant_order_sn}

Step 2. Simulate a paid webhook
POST /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_sn is required

Response shape

The response includes fields such as:

  • id
  • order_sn
  • merchant_order_sn
  • amount_usdt
  • actual_usdt
  • merchant_usdt
  • chain_type
  • payment_address
  • payment_url
  • status
  • transaction_hash
  • confirmations
  • webhook_url
  • callback_url
  • qr_code
  • event_type
  • exchange_rate
  • net_amount
  • expires_at
  • expires_in
  • card_type

Important backend behavior

  • if expires_at has already passed, the response can return the order as EXPIRED
  • expires_in is calculated at response time in seconds; once expired, it becomes 0
  • card_type is 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_sn
  • merchant_order_sn
  • amount_usdt
  • actual_usdt
  • merchant_usdt
  • status
  • chain_type
  • transaction_hash
  • paid_at
  • timestamp
  • payment_address

Important backend behavior

  • this is a simulation/testing endpoint, not a real payment callback receiver
  • it builds a synthetic PAID payload and sends it to the configured webhook target
  • merchant_usdt is currently simulated as amount_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

  1. Use GET /api/v2/payment-orders/{merchant_order_sn} for status polling after card-request payment creation.
  2. Do not treat POST /api/v2/payment-orders/paid as a production settlement API; it is a simulation helper.
Copyright © 2026