Bulk Disbursement Pattern

Use this pattern when your integration needs to send many outbound payments efficiently, with route-aware batching, per-item idempotency, and webhook-driven reconciliation for each outcome.

✅ Before you start

Complete these steps before you implement the bulk disbursement pattern:

1. Authenticate with the merged Login service and store the returned token and companyId.
2. Confirm the source wallet has enough availableBalance for the planned batch.
3. Create and store beneficiary records for every recipient before the batch begins.
4. Register webhook endpoints so you can reconcile each payout outcome asynchronously.
5. Generate a unique paymentId or idempotency key for every item in the batch — never one for the batch as a whole.

📚 Use this page with the recipe

This guide explains when to use the bulk disbursement pattern and the minimum sequence. For the implementation walkthrough, use the recipe:

Bulk Disbursement Pattern Recipe →

The bulk disbursement pattern

This integration pattern follows a strict sequence:

1. Group payouts by route or currency to take advantage of route-specific batching.
2. Validate beneficiary readiness for every item before submission.
3. Submit each payout with its own idempotency key so retries reuse the original operation.
4. Track each payout independently through webhooks rather than polling.
5. Reconcile completed, failed, rejected, or refunded items back into your source system per record.
6. Retry only the affected items when a subset of the batch fails or times out.

What makes this pattern different?

Unlike a single payout flow, bulk disbursement needs to:

• isolate per-item failures from the rest of the batch
• keep idempotency keys at the item level for safe retries
• support partial batch processing across multiple corridors
• drive reconciliation from webhooks rather than synchronous responses

Where to go deeper

• Bulk Supplier Disbursement
• Send
• Beneficiary Management Guide
• Webhooks
• Errors and Retries

Troubleshooting

Next steps