Skip to main content

Transaction statuses

A list of all statuses for transactions.

A transaction's status value can be one of the following depending on the state within the system and the status within the used payment service.

Authorization statuses​

statusDescription
processingThe transaction record has been created in the system and is now being processed with your payment services.
authorization_pendingThe transaction authorization is in progress with the payment service.
authorization_succeededThe transaction has been successfully authorized but not yet captured.
authorization_failedThe transaction could not be authorized with any payment service due to technical issues or limitations of the payment service.
authorization_voidThe transaction was successfully authorized but has since been voided before it was captured.

Buyer approval statuses​

statusDescription
buyer_approval_pendingThe transaction was created but needs approval from the buyer either by redirecting them to a hosted page or their bank for 3DS.
buyer_approval_succeededThe buyer has successfully completed the approval process.
buyer_approval_failedThe buyer approval process failed or was declined.
buyer_approval_timeoutThe buyer approval process timed out without completion.

Capture statuses​

statusDescription
capture_pendingThe transaction has successfully been submitted for capture with a payment service and is now pending with them.
capture_succeededThe transaction has been successfully authorized and captured.
capture_failedThe capture attempt failed after successful authorization.

Refund statuses​

statusDescription
refund_pendingA refund request has been submitted and is being processed.
refund_succeededThe refund has been successfully processed and funds returned to the buyer.
refund_failedThe refund attempt failed due to technical issues or payment service limitations.
refund_voidA pending refund has been cancelled/voided before completion.

Chargeback statuses​

statusDescription
chargeback_pendingA chargeback has been initiated and is under review.
chargeback_wonThe merchant successfully disputed the chargeback.
chargeback_lostThe chargeback was decided in favor of the cardholder.
chargeback_expiredThe chargeback case expired without resolution.

Final statuses​

statusDescription
settledThe transaction has been settled and funds transferred to the merchant account.
cancelledThe transaction was cancelled before completion.
expiredThe transaction expired without completion (e.g., buyer didn't complete approval in time).

State diagram​

The following state diagram serves as an overview of all the different status values and how they relate to each other.

Complete transaction lifecycle​

processing
    ↓
buyer_approval_pending (if required)
    ↓               ↓
buyer_approval_succeeded  buyer_approval_failed
    ↓                           ↓
authorization_succeeded      expired/cancelled
    ↓           ↓
authorization_void   capture_pending
    ↓               ↓
(end)           capture_succeeded
                    ↓
                settled ――→ refund_pending ――→ refund_succeeded
                    ↓           ↓
                    ↓       refund_failed
                    ↓
                chargeback_pending
                    ↓           ↓           ↓
            chargeback_won  chargeback_lost  chargeback_expired

Separate authorization and capture flow​

Transactions where the original intent is authorize:

processing
    ↓
buyer_approval_pending (if required)
    ↓
authorization_succeeded ――→ authorization_void
    ↓
capture_pending
    ↓        ↓
capture_succeeded  capture_failed
    ↓
settled
    ↓
[refund/chargeback flows]

Direct capture flow​

Transactions where the original intent is capture:

processing
    ↓
buyer_approval_pending (if required)
    ↓
capture_succeeded
    ↓
settled
    ↓
[refund/chargeback flows]

Status categories​

Active transaction states​

  • processing, buyer_approval_pending, authorization_pending, capture_pending, refund_pending, chargeback_pending

Successful completion states​

  • authorization_succeeded, capture_succeeded, settled, refund_succeeded, chargeback_won

Failure states​

  • authorization_failed, buyer_approval_failed, capture_failed, refund_failed, chargeback_lost

Terminal states​

  • authorization_void, settled, refund_succeeded, chargeback_won, chargeback_lost, chargeback_expired, cancelled, expired

Status usage guidelines​

For merchants​

  • Monitor buyer_approval_pending status to handle redirects and 3DS authentication
  • Use authorization_succeeded to confirm funds are reserved before fulfillment
  • Check capture_succeeded to confirm payment completion before shipping
  • Watch for chargeback_pending to prepare dispute documentation
  • Track refund_* statuses for customer service and reconciliation

For developers​

  • Implement webhook handlers for all status changes
  • Set appropriate timeouts for buyer_approval_pending states (typically 15-30 minutes)
  • Handle retry logic differently for authorization_failed vs buyer_approval_failed
  • Implement proper reconciliation flows for refund_* and chargeback_* statuses
  • Use terminal states to determine when transaction processing is complete

Common patterns​

  • Two-step payment: authorize → wait for fulfillment → capture → settled
  • Direct payment: capture immediately for digital goods → settled
  • Preauthorization: authorize → potential void if needed
  • Refund flow: settled → refund_pending → refund_succeeded
  • Dispute handling: settled → chargeback_pending → resolution
Powered by Docusaurus