Payment States

There are a number of statuses that individual payments may be, as well as order-level rollup statuses that summarize the states of all payments on the order. These states are associated with particular actions that are possible to perform during that state.

Payment Statuses

The following table lists all payment-level statuses and the available payment actions for each status. These statuses are reflected in payment object data when interfacing with order data via API, and apply individually to each payment method.

To learn more about the payment actions, refer to the corresponding table on actions.

Payment Status	Available Actions
New	AuthAndCapture AuthorizePayment CapturePayment CreatePayment CreditPayment DeclinePayment RequestCheck RequestPayment VoidPayment
Pending	AuthAndCapture AuthorizePayment CapturePayment DeclinePayment VoidPayment
Authorized	CapturePayment ClosePaymentAuth DeclinePayment InvoicePayment VoidPayment
Collected	CreditPayment DeclinePayment Rollback VoidPayment
Declined	AuthAndCapture AuthorizePayment CapturePayment Rollback VoidPayment
Voided	Rollback
Credited	CreditPayment Rollback
CreditPending	CreditPayment Rollback
PaymentRequested	AuhtorizePayment VoidPayment
Invoiced	CapturePayment ClosePaymentAuth VoidPayment

Order Payment Rollup Status

However, there is also an order-level payment rollup status that summarizes the overall payment status across all payments that belong to the order even if they are in different individual statuses of their own. This status is displayed on the order details page of the Admin UI as well as order object data in the API.

This order-level status determines whether or not a shipment is able to be fulfilled. A shipment can only be fulfilled if the order payment status is Pending, Paid, Pending and Errored, or Paid and Errored. If the status is Unpaid or Errored, then all shipments on the order will be blocked from being fulfilled through either API or the Fulfiller UI regardless of any individual shipment's current state.

For more information on this behavior and how to opt out, see the fulfillment documentation.

These rollup statuses are:

Order Payment Status	Description
Unpaid	There are no valid payments on the order and no balance has been collected.
Pending	There are valid payments on the order to collect the entire order balance.
Paid	There is zero balance remaining across all payment methods on the order.
Pending And Errored	There are pending payments as well as payments with errors of the type Void or Credit.
Paid And Errored	The order is fully collected but there are Credit errors.
Errored	Something is wrong with the payments on the order and at least one valid payment is still needed to cover the order balance. Not every payment has to be errored to trigger this status - for example, if a single payment failure means that there isn't enough payment to cover the order balance, the order will enter this Errored state.

Payment Workflows

The exact workflow that a payment goes through to reach the above statuses differs depending on the payment type. Credit cards, gateway gift cards, and third-party payment methods use the below workflow:

Diagram of the payment workflow with many stages and events

Store credit and store gift cards follow a simpler process:

Diagram of the store credit and store gift card workflow

Checks follow their own unique workflow:

Diagram of the check workflow

Purchase orders also have a unique workflow:

Diagram of the purchase order workflow

Payment Actions

The following table lists the available payment actions and describes when they can occur.

Action	Can Occur When Any of the Following are True
CreatePayment	A new payment can be added on the order.
RequestCheck	A check has a New status.
RequestPayment	A purchase order has a New status.
AuthorizePayment	A credit card has a New or Declined status. A purchase order has a PaymentRequested status.
InvoicePayment	A purchase order has an Authorized status.
ClosePaymentAuth	A purchase order has an Authorized or Invoiced status, and the amount requested exceeds the amount collected.
AuthAndCapture	An external payment has a New status. A credit card has a New or Declined status.
CapturePayment	An external payment has a New, Authorized, or Pending status. A check has a Pending or Declined status. A credit card has an Authorized status. A purchase order has an Authorized or Invoiced status. A PayPal Express payment has a New, Authorized, or Pending status. A store credit has a New status.
CreditPayment	A payment has a Collected status. The payment is a check or store credit. The payment has a Credited or CreditPending status, and the amount collected exceeds the amount credited.
VoidPayment	Note: This action cannot occur for any payment type that has a Null status. An external payment has a New, Authorized, or Pending status. A credit card has a New, Pending, or Authorized status. A credit card has a Collected status and the last interaction is a manual interaction. A check has a New, Pending, Authorized, or Collected status. A store credit has a New, Pending, or Authorized status. A PayPal Express payment has a New status. A purchase order has a New, Pending, PaymentRequested, Authorized, or Invoiced status, and there is no amount collected on the payment.
DeclinePayment	A check has a Pending status. A credit card has an Authorized status. An external payment has an Authorized status.
Rollback	The last non-rollbacked interaction on a payment is a manual interaction, and that interaction is not the first one performed on a payment.

Payment Statuses

Order Payment Rollup Status

Payment Workflows

Payment Actions

Related Articles