Payment lifecycle
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.
See below for the breakdown of the API requests and what’s supported for each payment status (table scrolls horizontally):
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.
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.
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.
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.
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.
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.
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.
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| API Request | PENDING | AUTHORIZED | SETTLING | SETTLED | PARTIALLY_SETTLED | CANCELLED | DECLINED | FAILED |
|---|---|---|---|---|---|---|---|---|
POST /authorize | Allow | Block | Block | Block | Block | Block | Allow | Allow |
POST /cancel | Allow | Allow | Allow | Block | Block | Block | Block | Block |
POST /capture | Block | Allow | Allow | Block | Allow | Block | Block | Block |
POST /decline | Allow | Block | Block | Block | Block | Block | Block | Block |
POST /refund | Block | Block | Block | Allow | Allow | Block | Block | Block |
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.