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 or webhook, 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 notification delivery and verification, 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.
End-to-end lifecycle#
This overview shows the main lifecycle families. Direct transitions and provider-specific branches are listed in the validated transition reference.
3DS and OTP
pending_3ds means that authentication is incomplete. Authentication success only allows the payment flow to continue; it does not prove that the purchase or authorization succeeded. After the challenge, wait for processed, authorized, or another reported payment status.
Some processor adapters use pending_otp internally. Current payment processing normalizes that result to public pending and supplies the required next-action metadata. If an older report or search filter contains pending_otp, treat it as awaiting customer action—not as payment success.
Authorization, capture, and void#
Two-step payment processing reserves funds first and collects them later. authorized is not captured money.
The state machine also permits a processor to report captured, partial_captured, or voided directly without first exposing the matching “-ing” status. Notifications are snapshots of authoritative state, not a guaranteed event-by-event sequence.
Choose single-step purchase or two-step authorization/capture at the processor connection level. Capture and void eligibility also depends on the processor, remaining amount, timing, and merchant configuration. Your DEUNA TAM can confirm compatible behavior.
For partial-capture modes and final_capture, see MPC — Multiple Partial Captures. The successful Void API returns HTTP 204 No Content; use the later payment state when the processor completes asynchronously.
Refunds and cancellation#
Refunds return collected funds. Voids release an authorization. They are not interchangeable.
A failed refund can restore the preceding financial state (processed, captured, or partial_captured). Preserve the successful payment and the failed refund attempt separately. See MPR — Multiple Partial Refunds for native and DEUNA-aggregated partial refund modes.
APM workflow#
Alternative payment methods commonly begin at pending, can expose processing, and complete at processed, denied, cancelled, or expired. Some APM connections support authorization and capture, so the same authorization statuses can apply.
The payment deadline is method- and configuration-specific. Do not infer expired from browser time or a redirect return; wait until DEUNA reports it.
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. | Await a webhook or retrieve the authoritative result before retrying. |
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#
- Verify every notification with the configured webhook-verification method.
- Identify the payment and related operation before changing local state.
- Store the reported status, confirmed amount, currency, operation identifier, and provider references.
- Process repeated notifications 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 late webhook 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.