Payment Status API

Overview

A payment status API lets applications retrieve or monitor the current lifecycle state of one or more payment records programmatically. The API can report states such as pending, detected, confirming, completed, failed, expired, refunded, or provider-specific equivalents. Clients use it for polling, support, callback verification, recovery after downtime, and reconciliation. The returned state can advance after the query, while excessive polling consumes quota. Integrations should map every documented status to explicit local behavior, use bounded polling with backoff, compare amount and currency, and enforce monotonic or legal transitions. A successful transport result from Payment Status API should not be interpreted beyond the exact API state documented by the provider.

For Payment Status API, developers should retain one correlation path across these stages because an immediate response can differ from later provider, blockchain, payment, accounting, or settlement state. For Payment Status API, metrics should separate transport success from business success. Status labels are not universal and may not equal blockchain finality or merchant fulfillment eligibility. Local systems must not regress when an older response arrives after a newer event. The Payment Status API owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate. For Payment Status API, the application should preserve a correlation path from request construction through response, asynchronous completion, and final business state.

Webhooks and status queries should complement each other. Reconciliation resolves missed events and long-running ambiguous payments.

Data handled by Payment Status API should use documented types, units, timestamp rules, nullable fields, and enum behavior to prevent silent interpretation errors.