All Primer payments conform to a unified payment lifecycle, which makes them work the same way regardless of the payment services you need. A payment always has a payment status. Each payment will progress through some combination of the statuses listed below on their way through your workflow. A newly-created payment is assigned the status PENDING.
payment lifecycle

Payment lifecycle

PENDING

The payment is awaiting a subsequent action or callback. This usually occurs with asynchronous processors. Prepare for this contingency by setting up Webhooks.

AUTHORIZED

The processor has authorized the payment and no further status-altering actions have been defined in your Workflow.

SETTLED
PARTIALLY_SETTLED

The processor has settled funds in your account. If the entirety of the payment amount has been settled, the payment will have the status SETTLED.Some processors allow for the capture of only a part of the authorized amount. If you leverage this capability, the payment status will be set to PARTIALLY_SETTLED.

DECLINED

The processor has declined the payment and no further status-altering actions have been defined in your Workflow. You may want to consider retrying certain declined payments.

FAILED

This usually occurs when there is a processor gateway issue, such as a service disruption. Set up retries and fallbacks to mitigate failures.

CANCELLED

The payment was canceled prior to it being settled.

SETTLING

The payment has been submitted for settlement and funds will be settled later. This usually occurs with asynchronous processors. Prepare for this contingency by setting up Webhooks.

​
Enforcing the payments lifecycle

The Payments API enforces our payments lifecycle state machine and returns a validation error if an API call is attempted where the payment status doesn’t support that action.
The error status code returned is 400 with errorId = InvalidPaymentStatus
See below for the breakdown of the API requests and what’s supported for each payment status (table scrolls horizontally):
API RequestPENDINGAUTHORIZEDSETTLINGSETTLEDPARTIALLY_SETTLEDCANCELLEDDECLINEDFAILED
POST /authorizeAllowBlockBlockBlockBlockBlockAllowAllow
POST /cancelAllowAllowAllowBlockBlockBlockBlockBlock
POST /captureBlockAllowAllowBlockAllowBlockBlockBlock
POST /declineAllowBlockBlockBlockBlockBlockBlockBlock
POST /refundBlockBlockBlockAllowAllowBlockBlockBlock
Processors may not support all the actions for each payment status outlined in the above table e.g. some processors may support cancelling a SETTLING payment, whilst others may not.