Order Status Guide
For each order status: what it means, what to show the user in your UI, and what to do next.
On-Ramp Order Statuses
| Status | What it means | Show the user | Your action |
|---|---|---|---|
fiatPending | Order created. Waiting for the user to make a fiat payment. | Payment details (bank account or UPI QR). A countdown timer showing the 3-hour expiry window. | Wait for user to pay. After payment, call POST /v1/orders/utr with the UTR number. Continue polling. |
fiatReceived | Onmeta confirmed receipt of the user's fiat payment. Crypto transfer will begin shortly. | "Payment received — processing your crypto transfer." | Continue polling. No user action needed. |
orderReceived | Crypto transfer has been initiated to the user's wallet. | "Your crypto is on its way — usually arrives within a few minutes." | Continue polling. No user action needed. |
transferred | Transfer confirmed on the blockchain. Transaction is irreversible. | "Transfer confirmed on blockchain." Show the transaction hash with a blockchain explorer link. | Continue polling for completed. You can show the explorer link now. |
completed ✅ | Order fully completed. User has received tokens in their wallet. | "You received [amount] [TOKEN]! Check your wallet." Show a success screen with the token amount and transaction hash. | Terminal status — stop polling. Trigger your success callback. |
expired ⏱ | No payment received within 3 hours. Order is cancelled. | "This order has expired." Offer a button to create a new order. | Terminal status — stop polling. Let user create a fresh order. Note: if the user already paid after expiry, ask user to create new order and use same utr. |
cancelled | Payment amount did not match the order amount. | "Order cancelled due to amount mismatch — Ask user to create new order with same amount they paid and use same utr." | Terminal status — stop polling. Create new order with same amount you paid and use same utr. |
fiatRefundInitiated | Payment received from an account not linked to the user's Onmeta profile. Refund process started. | "Payment received from an unregistered account — refund processing. This usually takes up to 24 hours." | Stop polling. Listen for the refunded webhook event — refunds are processed within 24 hours. Remind users to always pay from their registered bank/UPI to prevent this. |
refunding | Fiat refund is in progress. | "Your refund is being transferred back to your bank." | Stop polling. Listen for the refunded webhook event — polling over a 24-hour window is not efficient. |
refunded ✅ | Fiat has been successfully returned to the user's bank account. | "Your INR has been refunded to your bank account." | Terminal status — stop polling. |
UTR is mandatory
After a user makes a bank transfer or UPI payment, call POST /v1/orders/utr immediately. Without the UTR, the order stays at fiatPending indefinitely and will expire after 3 hours.
Off-Ramp Order Statuses
| Status | What it means | Show the user | Your action |
|---|---|---|---|
cryptoInit | Order created. Waiting for the user to send crypto to Onmeta's wallet. | The receiverWalletAddress from the order response — this is where user must send crypto. Show the exact token amount and chain. | Wait for user to send crypto. After sending, call POST /v1/offramp/orders/txnhash with the transaction hash. |
fiatPending | Crypto received and verified. INR payout to user's bank is being processed. | "Crypto received — processing your bank transfer. Standard settlement: 24 banking hours." | Continue polling. No user action needed. |
completed ✅ | INR has been settled to the user's bank account. | "INR transferred to your bank account — check your balance." | Terminal status — stop polling. Trigger your success callback. |
Transaction hash is mandatory
After a user sends crypto, call POST /v1/offramp/orders/txnhash with the blockchain transaction hash. Without this, Onmeta cannot verify receipt and the order will not progress.
Polling Recommendation
Poll the order status endpoint every 10–15 seconds. Stop polling as soon as you reach a terminal status:
- On-ramp terminal statuses:
completed,expired,cancelled,refunded - Off-ramp terminal statuses:
completed
Do not poll more frequently than every 10 seconds to avoid hitting rate limits.