Failed Payouts

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.

​

Common Causes

• Incorrect payee details — wrong account number, routing number, or payment method.
• Closed or restricted accounts — the recipient’s bank rejected the payment.
• Insufficient account balance — not enough funds were available at the time of execution.
• Currency or jurisdiction mismatch — the payment route was not supported for the destination country or currency.
• Compliance or sanctions hold — payment blocked due to screening requirements.

​

Detecting Failures

• Webhooks: Subscribe to the payout.failed event to receive instant notification when a payout cannot be completed.
• API: Retrieve a payout by ID and inspect the status field — it will show failed.
• Console: View detailed failure reasons, timestamps, and related account adjustments in the Acclaim Console.

{
  "id": "evt_MjdYqzLbsS",
  "type": "payout.failed",
  "data": {
    "object": {
      "id": "po_vkj7BPRPr9",
      "payment_amount": 10000,
      "paymetn_currency": "usd",
      "failure_code": "account_closed",
      "failure_message": "The recipient's account is closed."
      // truncated for brevity
    }
  }
}

​

Resolving Failed Payouts

1. Review the failure reason — check the failure_code and failure_message fields.
2. Correct the issue — update payee information, verify account balance, or contact your banking team if necessary.
3. Reissue the payout — create a new payout once the issue is resolved.

​

Webhook Events

​

Best Practices

• Ensure accounts remain adequately funded before initiating large batches.
• Implement webhook listeners to handle failures automatically.
• Avoid retrying the same payout ID; always create a new one after correction.