> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

![payment lifecycle](https://goat-assets.production.core.primer.io/marketing/external-docs/concepts/payment-lifecycle/payment-lifecycle.png)

Payment lifecycle

> [card]
>
> PENDING
>
> The payment is awaiting a subsequent action or callback. This usually occurs with asynchronous processors. Prepare for this contingency by [setting up Webhooks](https://primer.io/docs/api-reference/get-started/configure-webhooks.md).

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

> [card]
>
> 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](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/capture-a-payment.md#body-amount). If you leverage this capability, the payment status will be set to PARTIALLY\_SETTLED.

> [card]
>
> 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.

> [card]
>
> FAILED
>
> This usually occurs when there is a processor gateway issue, such as a service
> disruption. Set up retries and [fallbacks](https://primer.io/docs/payment-services/fallbacks.md) to mitigate
> failures.

> [card]
>
> CANCELLED
>
> The payment was canceled prior to it being settled.

> [card]
>
> 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](https://primer.io/docs/api-reference/get-started/configure-webhooks.md).

### Enforcing the payments lifecycle

The [Payments API](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/get-a-payment.md) 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.

> [!NOTE]
>
> 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 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 |

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.