Payment Status API

Overview

Why an API status query is important even with webhooks

Webhooks are a convenient way to learn that a payment may have changed, but callbacks can be late, duplicated or missed. A Payment Status API gives your server a way to ask the provider directly what the current recorded status is. Think of it as checking the official parcel-tracking record after a delivery notification fails to arrive. The status endpoint does not create the payment, and its response still needs to be interpreted using the provider's documented labels and confirmation policy.

How the underlying system works

A robust integration retains the provider's payment reference and queries the relevant endpoint when it needs authoritative state. OxaPay documents <code>GET /v1/payment/{track_id}</code> with a merchant API key for payment information. The response can support reconciliation between the provider's payment lifecycle and the commerce database.

Polling should be deliberate rather than excessive: use backoff, handle rate limits, distinguish temporary HTTP failures from genuine negative states and avoid overwriting newer events with stale responses. A common failure is treating an unsuccessful network request as evidence that a payment failed. In reality, the payment may have progressed while the API was unreachable. For fulfillment, apply the same policy whether state was obtained through a verified webhook or an authenticated status inquiry.

A safe recovery workflow

Your store created a $45 invoice and saved its track ID. The customer pays, but the checkout page never updates because the callback endpoint is unreachable. A scheduled worker queries the payment information/status endpoint using authenticated server credentials. It verifies the response belongs to the expected invoice and checks the asset, amount and state. If the provider says paid under the relevant rules, the worker can advance the order through the same idempotent fulfillment path used by webhooks. If the query times out or returns a temporary service error, the order remains unresolved; the error is not proof that the customer did not pay.

Polling is a fallback, not an excuse to overload the provider

Use reasonable polling intervals, exponential backoff for temporary errors and service rate-limit guidance. Prefer monitoring active or overdue invoices instead of repeatedly querying all historical payments. Avoid a race between a webhook handler and a polling worker by using the same state-transition rules and deduplication keys. Keep the original invoice ID, last-known status, request timestamp and response evidence. The authoritative answer is the service's verified current record, not the most recent browser screen or an unverified customer message.

Further reading and related concepts

Reference documents: OxaPay — Payment Information.

Related glossary topics: Crypto Payment Status, Webhook, Webhook Retry.