Retry with confidence.
Prevent duplicate payments, handle pending outcomes and distinguish a payment identifier from a support request ID.
One payment, one UUID
Create and persist a UUID with your order before sending a payment. Pass it as Idempotency-Key. Keep the same UUID and semantically identical payload when retrying after a timeout or connection error.
| Request | Response |
|---|---|
| First accepted payment | HTTP 202 with the new payment. |
| Same UUID and same normalized payment | HTTP 200 with the existing payment. |
| Same UUID, different payload or operation | HTTP 409 with idempotency_conflict. |
Do not generate a fresh UUID simply because an HTTP response was lost. A fresh UUID represents a separate payment request. UUID scope is independent across applications and live/test modes.
Handle uncertain outcomes
| Status | What it means | What to do |
|---|---|---|
process | Accepted, pending, or under Finance review. | Wait for a newer webhook or read the transaction. |
success | The payment is confirmed. | You can fulfil the order. |
failed | The payment failed. | Inspect the result. A failed payout reports its refund state. |
Finance review is represented as process, status_label: Under review and status_reason: review_required. Continue waiting for an authoritative newer outcome. Status reads return local state and do not dispatch or query the provider again.
Payment IDs and support IDs
| Identifier | Purpose |
|---|---|
reference | NuePay’s reference for the payment. |
idempotency_key / data.request_id | The original payment UUID, stable across retries. |
X-Request-Id | A different support identifier for each HTTP attempt. Errors echo it as top-level request_id. |
merchant_reference | Your optional order or business reference; it is not the duplicate-payment safeguard. |
Webhooks can repeat or arrive out of order
Store processed event IDs and apply only newer payment version values. A failed payment can later enter review if contradictory provider evidence appears. Your receiver should preserve the latest authoritative version.
On HTTP 429 or a transient connection error, wait with bounded backoff before retrying. Keep the same payment UUID and check existing payment state before starting a separate attempt.