Failures and reversals

Not all payouts complete successfully. When a payout fails, it reaches the Failed final state, Acclaim returns the funds to your treasury account, and you receive a specific failure_code and message explaining why. This guide covers what happens when a payout fails, the available failure codes, how returned funds are handled, and how to retry safely. For status transitions and lifecycle context, see Payout lifecycle.

---

​

When a payout fails

A payout fails after processing begins and Acclaim cannot complete delivery. At that point:

• The payout moves to the final Failed state and will not be sent
• Acclaim includes a failure_code and matching message on the payout
• Funds are returned to the treasury account that funded the payout
• You can review the failure in the Console or through webhooks and the API

Fund return is part of every failed payout, not a separate outcome that applies only in some cases.

---

​

Failure codes

When a payout fails, Acclaim includes a failure_code and matching message. All API codes use the payout.* format. The groups below describe what each failure means in plain language, with the exact code shown for reference.

​

Beneficiary account

• Account closed — The beneficiary account is closed and cannot receive funds.
  Code: payout.beneficiary_account_closed
• Invalid account — The beneficiary account details are invalid.
  Code: payout.invalid_beneficiary_account
• Account not found — The beneficiary account could not be found.
  Code: payout.beneficiary_account_not_found
• Account inactive — The beneficiary account is inactive and cannot receive funds.
  Code: payout.beneficiary_account_inactive
• Account restricted — The beneficiary account is restricted and cannot receive funds.
  Code: payout.beneficiary_account_restricted

​

Amount and currency

• Insufficient balance — There are insufficient funds available to complete the payout.
  Code: payout.insufficient_balance
• Invalid amount — The payout amount is invalid.
  Code: payout.amount_invalid
• Currency not supported — The selected currency is not supported for this payout.
  Code: payout.currency_not_supported
• Account currency mismatch — The beneficiary account does not support the selected payout currency.
  Code: payout.account_currency_mismatch

​

Bank details

• Invalid bank information — The bank account information provided is invalid or incomplete.
  Code: payout.invalid_bank_information
• Invalid routing number — The routing number provided is invalid.
  Code: payout.invalid_routing_number
• Invalid IBAN — The IBAN provided is invalid.
  Code: payout.invalid_iban
• Invalid beneficiary name — The beneficiary name provided is invalid or does not match the account details.
  Code: payout.invalid_beneficiary_name

​

Compliance

• Sanctions blocked — The payout could not be completed due to sanctions restrictions.
  Code: payout.sanctions_blocked
• Compliance blocked — The payout could not be completed due to compliance requirements.
  Code: payout.compliance_blocked
• Purpose of payment rejected — The purpose of payment is not valid for this payout.
  Code: payout.purpose_of_payment_rejected

​

Processing

• Cutoff missed — The payout missed the processing cutoff time and could not be completed.
  Code: payout.cutoff_missed
• Duplicate payout — A duplicate payout was detected and was not processed.
  Code: payout.duplicate_payout
• Bank returned payout — The beneficiary’s bank returned the payout.
  Code: payout.beneficiary_bank_returned
• Recall requested — A recall was requested for this payout.
  Code: payout.recall_requested
• Processor unavailable — The payout processor is temporarily unavailable. Please try again later.
  Code: payout.processor_unavailable
• Processor failure — The payout could not be completed due to a processing error.
  Code: payout.processor_failure
• Unknown failure — The payout could not be completed for an unknown reason.
  Code: payout.unknown_failure

---

​

Returned funds

When a payout fails, Acclaim returns the funds to the treasury account that funded the payout. The payout remains in Failed, and a treasury transaction records the return when applicable. Timing depends on the payout method and external network, but the return is automatic. You do not need to request it separately.

​

Cross-border and FX payouts

For cross-border payouts, currency conversion may occur before delivery. If the payout fails after FX has already run:

• The returned amount is in the payment currency
• Funds are not automatically converted back to the original funding currency
• The original FX transaction has already been completed

You can then:

1. Retry using the returned funds — create a new payout funded with the returned payment-currency balance
2. Convert back to the original currency — perform a new FX conversion if you need funds in the original funding currency

---

​

Retrying failed payouts

After funds are returned and the underlying issue is fixed, you can send the payout again. Best practice:

1. Review the failure_code and message
2. Correct the issue, such as payee details or payout method
3. Create a new payout once funds are available again

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

---

​

Monitoring and alerts

To respond quickly to failed payouts:

• Monitor payouts in the Console
• Track status changes via webhooks
• Set up internal alerts for Failed payouts

For webhook and API handling details, see Failed payouts.

---

​

Summary

• Failed is a final state reached when a payout cannot be completed after processing begins
• Every failed payout returns funds to the treasury account that funded it
• Use failure_code and the matching message to diagnose the issue; see Failure codes above
• FX payouts may return funds in the payment currency; currencies that cannot be held in your treasury account are converted back to the funding currency automatically
• Most failures can be resolved and retried after correcting the issue