Failed Payouts

A payout can fail for a variety of reasons — such as invalid recipient details, closed bank accounts, or compliance issues. When a payout fails, Acclaim updates its status, notifies you via webhook, and automatically returns the funds to the originating wallet.

Your system should be designed to listen for these events, update records, and, if appropriate, reissue the payout once the issue is corrected.

Common Causes

Payout failures can happen for several reasons:

• Incorrect payee details — wrong account number, routing number, or payment method.
• Closed or restricted accounts — the recipient’s bank rejected the payment.
• Insufficient wallet 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.

Each failed payout includes an error code and message to help you identify what went wrong.

Detecting Failures

You can detect failed payouts through several channels:

• 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 wallet adjustments in the Acclaim Console.

Example webhook event:

{
  "id": "evt_12345",
  "type": "payout.failed",
  "data": {
    "object": {
      "id": "po_456",
      "amount": 10000,
      "currency": "usd",
      "failure_code": "account_closed",
      "failure_message": "The recipient's account is closed."
    }
  },
  "created_at": "2025-10-08T18:20:31Z"
}

Resolving Failed Payouts

When a payout fails:

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

Failed payouts are automatically reversed — the full amount returns to the source wallet and becomes available for future payouts.

Webhook Events

Important events to handle when managing failed payouts:

These events can trigger automated workflows — such as retrying payouts, notifying your team, or updating accounting records.

Best Practices

• Ensure wallets 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.