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

# Payment failures

> Understand why payins fail, how failure codes help you diagnose issues, and how to retry or monitor failed payment requests.

Not all payment requests complete successfully. When a payment fails, it reaches the **Failed** final state, no funds are collected, and you receive a specific `failure_code` and message explaining why.

This guide covers what happens when a payment fails, the available failure codes, and how to retry or monitor failed payins safely.

For status transitions and lifecycle context, see [Payment lifecycle](/guides/collect/payment-lifecycle). For post-success returns or chargebacks, see [Refunds](/guides/collect/refunds) and [Disputes](/guides/collect/disputes).

***

## When a payment fails

A payment fails after processing begins and Acclaim cannot complete collection.

At that point:

* The payment request moves to the final **Failed** state and will not be charged
* Acclaim includes a `failure_code` and matching message on the payment request
* No funds are collected from the payer
* You can review the failure in the **Console** or through webhooks and the API

A failed payment is not the same as a [refund](/guides/collect/refunds) or [dispute](/guides/collect/disputes). Those apply after a payment has succeeded.

***

## Failure codes

When a payment fails, Acclaim includes a `failure_code` and matching message. All API codes use the `payin.*` format.

The groups below describe what each failure means in plain language, with the exact code shown for reference.

### Account

* **Account closed** — The account is closed and cannot be charged.\
  Code: `payin.account_closed`
* **Account frozen** — The account is frozen and cannot be charged.\
  Code: `payin.account_frozen`
* **Invalid account** — The account details are invalid.\
  Code: `payin.invalid_account`
* **Account not found** — The account could not be found.\
  Code: `payin.account_not_found`

### Amount and limits

* **Insufficient funds** — There are insufficient funds available to complete the payment.\
  Code: `payin.insufficient_funds`
* **Invalid amount** — The payment amount is invalid.\
  Code: `payin.amount_invalid`
* **Currency not supported** — The selected currency is not supported for this payment.\
  Code: `payin.currency_not_supported`
* **Limit exceeded** — The payment exceeds an allowed limit.\
  Code: `payin.limit_exceeded`

### Payment method

* **Expired payment method** — The payment method has expired.\
  Code: `payin.expired_payment_method`
* **Payment method declined** — The payment method was declined.\
  Code: `payin.payment_method_declined`
* **Unsupported payment method** — The payment method is not supported.\
  Code: `payin.unsupported_payment_method`
* **Invalid security code** — The security code provided is invalid.\
  Code: `payin.invalid_cvc`
* **Address verification failed** — Address verification failed for this payment method.\
  Code: `payin.address_verification_failed`

### Authentication

* **Authentication required** — Additional authentication is required to complete the payment.\
  Code: `payin.authentication_required`
* **Authentication failed** — Authentication failed and the payment could not be completed.\
  Code: `payin.authentication_failed`
* **Unauthorized** — The payment was not authorized by the account holder.\
  Code: `payin.unauthorized`

### Compliance and fraud

* **Suspected fraud** — The payment was declined due to suspected fraud.\
  Code: `payin.suspected_fraud`
* **Payment blocked** — The payment was blocked and could not be completed.\
  Code: `payin.payment_blocked`
* **Compliance blocked** — The payment could not be completed due to compliance requirements.\
  Code: `payin.compliance_blocked`

### Request and session

* **Invalid request** — The payment request is invalid.\
  Code: `payin.invalid_request`
* **Duplicate payment** — A duplicate payment was detected and was not processed.\
  Code: `payin.duplicate_payment`
* **Expired session** — The payment session has expired.\
  Code: `payin.expired_session`
* **Configuration error** — The payment could not be completed due to a configuration issue.\
  Code: `payin.configuration_error`

### Processing

* **Processor unavailable** — The payment processor is temporarily unavailable. Please try again later.\
  Code: `payin.processor_unavailable`
* **Processor failure** — The payment could not be completed due to a processing error.\
  Code: `payin.processor_failure`
* **Unknown failure** — The payment could not be completed for an unknown reason.\
  Code: `payin.unknown_failure`

***

## Retrying failed payments

After the underlying issue is fixed, you can attempt collection again.

Best practice:

1. Review the `failure_code` and message
2. Correct the issue, such as payment method details or payer information
3. Create a new payment request or prompt the payer to try again

Avoid retrying without changes. The same issue is likely to cause another failure.

***

## Monitoring and alerts

To respond quickly to failed payments:

* Monitor payment requests in the **Console**
* Track status changes via **webhooks**
* Set up internal alerts for **Failed** payments

For webhook and API handling details, see [Collect](/developers/collect).

***

## Summary

* **Failed** is a final state reached when a payment cannot be completed after processing begins
* No funds are collected when a payment fails
* Use `failure_code` and the matching message to diagnose the issue; see [Failure codes](#failure-codes) above
* Most failures can be resolved and retried after correcting the issue
* Refunds and disputes apply to successful payments, not failed payment requests