Retry Timed-Out Payouts

Retry a Timed-Out Payout Safely

Use this flow when a payout request times out or your network fails before you receive a confirmed API response, and you need to retry without risking a duplicate payment.

✅ Before you start

Complete these steps before you implement timeout recovery for payouts:

1. Generate a unique Idempotency-Key for every payout request.
2. Store that key with your internal payment reference before you call the send endpoint.
3. Register webhook endpoints so you can reconcile payout state changes after the request returns or times out.
4. Make sure your retry logic can resend the exact same request without generating a new key.

📚 Use this page with the recipe

This guide explains when to use the timeout-retry flow and the minimum sequence. For the step-by-step implementation, use the recipe:

Retry a Timed-Out Payout Safely Recipe →

The timeout-retry workflow

This use case follows a strict safety sequence:

1. Create the payout with a unique Idempotency-Key.
2. Treat a timeout as an unknown result instead of assuming the payout failed.
3. Retry the request with the same key so the original operation is reused if it already exists.
4. Reconcile the final state through webhooks and update your internal payment record.

What makes this use case different?

Unlike a normal payout flow, this guide is specifically for situations where:

• the API request may have succeeded even though your app did not receive the response
• creating a new payout would risk sending money twice
• webhook-driven reconciliation is the safest source of truth for the final outcome

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

• Send
• Errors and Retries
• Webhooks

Success indicators

Troubleshooting

Next steps