Check Invoice Status via API: Polling Alongside Webhooks
Learn how to check invoice status with the MercanPay API using invoice ID or order_id, how often to poll, and how to combine polling with webhooks safely.

Checking invoice status through the API is the simplest way to back up your webhooks with a safety net. With MercanPay you can use GET /v1/invoices/:id and GET /v1/invoices/by-order/:order_id to learn the current state of an invoice whenever you need it. This guide explains when, how and how often to poll invoice status.
Why poll invoice status at all?
Webhooks are the main notification channel: when a payment arrives, MercanPay sends events such as invoice.paid to your server and retries failed deliveries with backoff. Polling still helps when:
- Your server was briefly down for maintenance and you suspect a missed event.
- A customer returns to your site from the payment page and you must show the order state right away.
- Your support team wants to verify the payment state of a single order by hand.
- Your end-of-day reconciliation needs to sweep invoices that were left open.
For webhook setup, see Crypto Payment Webhook Events and Webhook Retries and Idempotent Handling. Polling works next to them, not instead of them.
Two ways to look up an invoice
1. By invoice ID: GET /v1/invoices/:id
When you create an invoice, MercanPay returns an invoice ID. If you store it with your order, you can use this endpoint directly.
2. By order number: GET /v1/invoices/by-order/:order_id
If you passed your own order number as order_id when creating the invoice, you can go from order to invoice without storing the invoice ID. The details are covered in Idempotent Invoices with order_id.
For request headers, the authentication format and the full list of response fields, check the current documentation; this article only describes the flow.
Invoice states and what they mean
Over its life an invoice passes through states tied to these events:
| Event | Meaning |
|---|---|
invoice.paid |
Payment completed and credited after 20 block confirmations |
invoice.partial |
An underpayment arrived; the invoice is extended so the customer can send the rest |
invoice.overpaid |
More than the invoice amount arrived |
invoice.expired |
The time ran out (invoices stay open 24 hours at most) |
invoice.cancelled |
The invoice was cancelled |
Late payments are still credited, so even when you poll an expired invoice, a payment may have arrived afterwards. See Handling Crypto Underpayments, Overpayments and Late Payments.
Designing the polling flow
It helps to settle the logic before writing code:
- When creating the order, create the invoice with an
order_idand save the invoice ID. - When the customer returns to your success page, read the order state from your own database first; the webhook has most likely been processed already.
- If the record is not yet "paid", query the invoice from the API and show the result.
- If a payment is detected and confirming, show "your payment is being confirmed". Confirmation usually takes about a minute.
- When the state is final, complete the order, and do it only once.
Frequency and limits
- Use 10-30 second intervals rather than several requests per second. Confirmation takes minutes, so faster polling adds nothing.
- An invoice stays open for 24 hours at most, so there is no reason to poll longer than that.
- Stop polling once the state is paid, expired or cancelled.
- Polling and the webhook must not complete the same order twice: make the handler idempotent.
Common mistakes
- Relying on polling only. Between polls you notice changes late; webhooks should remain your main channel.
- Trusting only the browser redirect. A customer landing on your success page does not prove payment; verify on the server side.
- Completing an order twice. When both the webhook and the poll say "paid", do not repeat fulfillment.
- Putting the API key in the browser. Make these calls from your server only.
- Not saving the invoice ID. If you do not use
order_id, keep the ID on your order record.
Frequently asked questions
Do I need polling if I have webhooks?
It is not mandatory but recommended as a safety net. Webhooks are retried, yet you can still catch a missed event by querying.
Can I find an invoice by my order number?
Yes. If you created it with an order_id, query GET /v1/invoices/by-order/:order_id.
How often should I poll?
10-30 second intervals are enough. Payment confirmation usually takes about a minute.
What if a payment arrives on an expired invoice?
Late payments are still credited. On USD-priced TRX invoices, a late payment is re-priced at the current rate.
Get started with MercanPay
Use webhooks and polling together to automate orders safely. Apply as a merchant and explore every endpoint in the documentation.


