To help merchants understand the behavior of orders and payments during transactions, the following introduces the design logic of order validity period, payment validity period, order status, and exception tags.
The order expiration is set by the merchant in the backend or defined through the API's expires_in field when creating an order.
Its meaning is:
Users must complete payment within the order validity period, otherwise the order will be considered expired or partially paid.
- Control user payment duration
- Control inventory locking duration
- Prevent inventory occupation due to long-term non-payment
- Only serves as a basis for order status changes (pending → expired). After the order reaches a final state, the status will no longer change (final states include: expired, paid, partial_paid).
- Payments made by users after order expiration will still be identified as "late payment" by exception tags and will update confirming_amount and confirmed_amount.
👉 Order expiration only applies to Orders.
Payment expiration refers to the valid usage time limit for the payment address/QR code generated by each Payment. The default validity period is 1 hour.
Its meaning is:
Users need to complete payment within the payment validity period. After the payment expires, users can regenerate a new payment and obtain a new quote and payment address.
- User stays too long → Payment address expires → Generate new payment
- On-chain price fluctuation → User needs new quote → Generate new payment
👉 Payment expiration only applies to Payments.
Order status is determined by three key fields: expiration status, amount_confirming, and amount_confirmed.
| Status | Expired | amount_confirming | amount_confirmed | Business Meaning |
|---|---|---|---|---|
| pending | No | = 0 | = 0 | Initial state, waiting for user payment. |
| processing | No | > 0 | = 0 | User has paid, but on-chain transaction is still being confirmed. |
| processing | No | - | > 0 and < order_amount | Partial amount confirmed, but insufficient for order amount. |
| paid | No | - | ≥ order_amount | Full payment successful. |
| expired | Yes | = 0 | = 0 | Timeout without payment, order closed. |
| partial_paid | Yes | - | > 0 and < order_amount | Expired, but user has paid partial amount. Merchants can choose partial shipment, contact user for additional payment or refund. |
On-chain payments may encounter various abnormal situations, so Infini provides exception tags (exception_tags) to help merchants with customer service handling, financial reconciliation, and risk control judgment.
⚠️ Exception tags do not affect order status and can exist simultaneously.
| Tag Name | Description |
|---|---|
| late | User paid after order expiration. Different from expired (expired without payment). |
- Customer service follow-up (additional payment, refund, currency correction, etc.)
- Risk control handling (block risk assets)
- Financial reconciliation
- Combined with order status for business decisions