Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.withacclaim.com/llms.txt

Use this file to discover all available pages before exploring further.

The lifecycle is designed to support:
  • Card payments (including 3-D Secure authentication)
  • Wallet payments
  • Bank-based methods
  • Apple Pay and Google Pay
  • PSP fallbacks and retries
  • Multi-step flows where payers provide payment details interactively
This guide explains each lifecycle state and the transitions between them.

​
Overview of States

A payment request can move through the following states:
  • RequiresPaymentMethod
  • RequiresAction
  • 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.

​
RequiresPaymentMethod

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.

​
RequiresAction

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:
    RequiresPaymentMethod → RequiresAction → 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.
Last modified on May 23, 2026