Failed Payouts

​

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,
      "payment_currency": "usd",
      "failure_code": "payout.beneficiary_account_closed",
      "failure_message": "The beneficiary account is closed and cannot receive funds."
      // 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.