Overview of States

A payment request can move through the following states:

requires_payment_method
requires_action
processing
authorized
succeeded
failed
canceled

Each state has clearly defined meaning and transition rules.

State Definitions

A payment request is created when your backend calls POST /payment_requests. From here, the request will branch into the next appropriate state based on what Acclaim needs.

`requires_payment_method`

Acclaim needs a payment method before it can proceed.

A payment request enters this state when:

No payment method was provided at creation, and
You intend for the payer to complete the payment through the UI

You will typically render a Payment Element here. Once the payer enters a payment method, your UI should call:

paymentElement.submit();

This moves the request forward into processing.

`requires_action`

Acclaim requires payer interaction, such as authentication (e.g. 3-D Secure).

This state occurs when:

The card issuer requires authentication
A payment method triggers a regulatory confirmation
The PSP indicates a user approval step is needed

Your UI should guide the payer through the action. Acclaim.js automatically handles supported flows.

Once completed, the request transitions to processing.

`processing`

The payment is being transmitted to the PSP, but the outcome is not yet final.

A request enters processing when:

A valid payment method has been provided, and
No further user action is required

Acclaim handles:

Authorization attempts
Network routing
PSP-specific flows
Fallback logic

From processing, the payment may transition to:

authorized
succeeded
failed

`authorized`

The PSP has authorized the payment, but settlement has not yet occurred.

This state only appears for payment methods that support two-step Authorization and Capture flows. You have to select an auth capture flow when creating the payment request. Acclaim automatically captures the payment in most insurance workflows instead of doing it as a separate step.

Once capture succeeds, the payment transitions to succeeded.

`succeeded`

The payment is fully settled.

This is the terminal success state. You receive a payment_request.succeeded webhook. You can trigger downstream events such as:

Policy activation
Coverage reinstatement
Claim evaluation
Ledger reconciliation

`failed`

The payment could not be completed.

A payment request enters failed when:

The payment method is declined
Authentication fails
The payer exits required-action flow
The PSP returns an unrecoverable error
Network or routing issues prevent completion

You receive a payment_request.failed webhook. Your system may:

Prompt the payer to update their payment method
Initiate a fallback PSP route
Retry with additional validation
Mark the invoice or policy period as unpaid

`canceled`

A payment request can be canceled intentionally. This state appears when you call the Cancel Payment Request API before the payment request is succeeded. Canceled payments do not attempt collection and are not considered failures.

Lifecycle Diagram

A diagram of the full lifecycle is shown below:

Summary

A Payment Request is the core object for charging payers.
It moves through well-defined states describing what Acclaim needs next.
UI-driven payments flow through:
requires_payment_method → requires_action → processing
Server-driven payments typically flow through:
created → processing → succeeded
Webhooks should be used to reliably update internal systems.

The lifecycle design supports modern multi-PSP flows, authentication steps, retries, and clear back-office reconciliation.