Payment-status polling lets a merchant backend check whether a saved Coinvay invoice is Paid without relying solely on webhook delivery. Poll the authenticated invoice-by-ID endpoint and fulfill only after matching the response to your order.
Poll the specific invoice
Use GET /api/invoices/{id} from your backend with the merchant bearer key. The invoice list is bounded and is not a substitute for looking up a known older invoice. Keep the saved invoice ID alongside the order rather than searching by a customer-provided transaction hash. Your frontend can ask your server for a simplified order status; it should never receive the merchant API key.
Use bounded work and sensible delays
For example, a store can place unpaid order IDs into a background reconciliation queue, check a bounded batch, and schedule another pass while they remain pending. Increase delays after repeated provider or API errors, cap retries, and rotate through the backlog so one failing order does not starve others. Respect rate limits and distinguish a plan-restriction response from an unpaid customer invoice. Do not hammer the API every time the customer refreshes the page.
Define when to stop and review
Stop normal polling once an invoice is confirmed and your fulfillment job is recorded. Closed or expired requests need their own support policy, especially if a customer reports a late transfer. A provider outage should leave an order awaiting verification, not mark it paid or failed without evidence. For unattended monitoring and webhook processing inside the gateway, the deployment also needs its authenticated runner; an open checkout uses its own browser polling. Your store reconciliation worker remains a separate responsibility.
Practical checklist
- Keep polling on a backend or trusted scheduled worker, never in a secret-bearing browser call.
- Use the saved order amount, currency and invoice mapping before fulfillment.
- Record last-attempt time, retry count and an actionable review reason for failed checks.
Common questions
Can polling work without a webhook-enabled plan?+
Authenticated invoice lookup can support reconciliation where API access is available. Check your current plan permissions and choose an appropriate polling workload.
Does closing the browser stop my own worker?+
A properly scheduled server worker continues independently. Browser polling stops when its checkout page closes, so it cannot replace an unattended reconciliation process.
Sources and further reading
Primary references and Coinvay product documentation. Check the linked pages for current details.
AI-assisted drafting, published by Coinvay. Examples are illustrative. Read our editorial approach.