Skip to main content
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. For post-success returns or chargebacks, see Refunds and 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 or dispute. 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.

​
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 above
  • Most failures can be resolved and retried after correcting the issue
  • Refunds and disputes apply to successful payments, not failed payment requests
Last modified on June 14, 2026