Payment Workflow & Statuses
Understand every public payment status, the operations that produce it, and the transitions merchants must handle.
On this page
Use payment.data.status as the source of truth for a payment. When the payment is wrapped in an order response, read order.payment.data.status. The order container does not change the meaning of the payment status.
Always evaluate the status together with confirmed amounts and operation history. An accepted API request or an HTTP 2xx response can mean that an asynchronous operation started; it does not always mean that money moved.
For fraud decisions, see Fraud workflow and statuses. For asynchronous provider updates, see DEUNA Webhooks.
Status families#
The labels below explain how merchants should handle the values; they are not additional API fields.
| Family | Statuses | Merchant handling |
|---|---|---|
| Waiting for action or confirmation | pending, pending_3ds, processing, authorizing, capturing, partial_capturing, voiding, refunding, partial_refunding, manual_review | Keep the payment unresolved. Complete any required customer action and wait for, or retrieve, an authoritative result. |
| Confirmed and still operable | processed, authorized, captured, partial_captured, partial_refunded | Record the confirmed financial result. A later eligible capture, refund, or void can still change the status. |
| Unsuccessful but recoverable | denied | Do not fulfill from this attempt. A retry or routing decision can move the same payment back into an active state, so do not model denied as terminal. |
| Cancellation awaiting financial resolution | cancelled | Inspect prior financial activity. A refund or void can still follow. |
| Terminal | voided, refunded, expired | The core payment state machine has no outgoing transition from these values. |
partial_captured and partial_refunded can be the last state required by the merchant's business process even though they are not terminal API statuses. Keep the real status and cumulative amounts; never replace a partial status locally with captured or refunded.
Choose the payment workflow#
Card payments and alternative payment methods do not move through the same customer actions or processing states. Start with the workflow that matches the payment method, then return here for the canonical status and transition references.
The diagrams on those pages show the normal merchant-facing path. Direct transitions, retries, reconciliation paths, and provider-specific branches remain authoritative in the validated transition reference.
Payment status reference#
Values are case-sensitive lowercase strings.
| Status | Meaning | What the merchant should do |
|---|---|---|
pending | Payment created; customer action, routing, or provider confirmation may still be required. | Follow next_action or method instructions and keep fulfillment blocked. |
pending_3ds | 3DS authentication is incomplete. | Complete the challenge, then evaluate the resulting payment status. |
processing | A purchase or APM payment is in progress. | Retrieve the authoritative result after DEUNA processes the provider update; do not retry prematurely. |
processed | A single-step purchase completed. | Record success and apply the fulfillment policy; refunds may follow. |
authorizing | The authorization request is in progress. | Do not treat funds as captured or reserved yet. |
authorized | Funds were successfully reserved. | Capture or void when eligible. |
capturing | A full capture is in progress. | Track the operation and wait for confirmation. |
partial_capturing | A partial capture is in progress. | Keep pending and confirmed captured amounts separate. |
partial_captured | A partial amount was captured. | Record the confirmed amount and remaining capture/refund eligibility. |
captured | Capture completed. | Record the collected amount; refunds may follow. |
voiding | Release of an authorization is in progress. | Wait for voided or a restored/failed result. |
voided | The authorization was released. | Record terminal completion. |
refunding | A full or remaining-balance refund is in progress. | Wait for confirmation; request acceptance is not proof of returned funds. |
partial_refunding | A partial refund is in progress. | Track pending and confirmed refunded amounts separately. |
partial_refunded | A partial refund completed. | Record the amount and remaining refundable balance. |
refunded | The refundable balance represented by the lifecycle was returned. | Record terminal completion. |
manual_review | The payment is held for a risk decision. | Keep fulfillment blocked until the payment receives a new status. |
denied | The current attempt was rejected. | Do not fulfill. Preserve the reason; a configured retry can re-enter the active flow. |
cancelled | The method or merchant cancelled the payment. | Check whether a refund or void must still complete. |
expired | The allowed completion window closed before payment finished. | Record terminal completion; create a new payment if the customer tries again. |
not_authorized and failed are used by processor or operation-level adapters, but they are not canonical values in the core payment.data.status transition graph. Do not merge provider-operation statuses, capture/refund operation statuses, or local timeout markers into the payment status field.
Validated transition reference#
The following transitions match the Payments core state machine. Repeated delivery of the same state is omitted except where it is explicitly accepted. A listed transition does not guarantee that every processor or payment method supports the corresponding operation.
| Current status | Allowed next statuses |
|---|---|
pending | pending, pending_3ds, authorizing, authorized, processing, processed, cancelled, voided, denied, manual_review, expired |
pending_3ds | pending_3ds, authorizing, authorized, processing, processed, cancelled, denied, manual_review, expired |
processing | processed, cancelled, denied, manual_review, partial_refunding, refunding, partial_refunded, refunded |
processed | refunding, refunded, partial_refunding, partial_refunded, voided |
authorizing | authorized, captured, voiding, cancelled, denied, manual_review |
authorized | capturing, captured, partial_capturing, partial_captured, voiding, voided, cancelled |
capturing | captured, denied; for supported pending-capture recovery flows: authorized, partial_capturing, partial_refunding, partial_refunded, refunding, refunded |
partial_capturing | capturing, partial_captured, captured, denied |
partial_captured | captured, partial_refunding, partial_refunded, refunding, refunded |
captured | partial_refunding, partial_refunded, refunding, refunded |
voiding | voided, denied, authorized |
refunding | refunded, partial_refunded, voided, processed, captured |
partial_refunding | partial_refunded, refunding, refunded, denied, processed, captured, partial_captured |
partial_refunded | partial_refunding, refunding, refunded |
manual_review | processed, captured, denied |
denied | pending, pending_3ds, processing, processed, authorizing, authorized, manual_review, denied |
cancelled | refunded, voided |
voided | None (terminal) |
refunded | None (terminal) |
expired | None (terminal) |
Settlement-file reconciliation can enable additional recovery transitions while DEUNA reconciles an external processor result. These transitions do not change the public meaning of the statuses.
Some processor profiles can accept a refund while an asynchronous capture is still pending. In that flow, DEUNA can cancel or reverse the pending capture and refund the original authorization, which enables the additional transitions listed for capturing. Do not initiate this flow unless DEUNA has confirmed support for the processor connection.
Handle updates safely#
- Retrieve the authoritative payment before changing local state.
- Identify the payment and related operation before applying the update.
- Store the reported status, confirmed amount, currency, operation identifier, and provider references.
- Process repeated retrieval and client retries idempotently. Do not deduplicate by status alone.
- Keep fulfillment blocked for transient, review, or unknown states.
- Reconcile missing or conflicting outcomes through the supported payment retrieval flow.
An HTTP timeout, lost response, or delayed provider update does not prove denied or expired. Follow idempotent request guidance, retrieve the payment, and distinguish a retry of the same request from a new payment attempt.