Batch payouts let you send multiple payouts in a single operation.
Use them for claims runs, vendor payments, or scheduled disbursements where you need to process many payouts together and track outcomes as a group.
When to use batch payouts
Use batch payouts when you need to:
- Send large volumes of payouts at once
- Group related payouts into a single execution
- Track outcomes collectively (e.g. by run, file, or event)
- Reduce operational overhead compared to individual payouts
How batch payouts work
A batch groups multiple payouts into a single unit of execution.
-
Create a batch
Define a batch and include one or more payouts.
-
Validate payouts
Each payout is validated for required details, payout method compatibility, and readiness.
-
Lock FX (if applicable)
For cross-border payouts, Acclaim generates a single FX quote per currency pair within the batch.
This ensures consistent conversion rates across all payouts sharing the same source and destination currencies.
-
Process the batch
Payouts are submitted for processing. Each payout progresses through its own lifecycle and status.
-
Track results
Monitor outcomes at both the batch level and individual payout level.
Batch vs individual payouts
- A batch is a container for multiple payouts
- Each payout inside the batch is processed independently
This means:
- Some payouts may succeed while others fail
- Failures do not block the entire batch
- Each payout maintains its own status and lifecycle
For cross-border payouts:
- FX is grouped at the batch level
- Execution and delivery remain independent per payout
Creating batch payouts
You can create batch payouts using:
- API: programmatically create and submit batches
- File uploads: upload a structured file containing payouts
- Console: create and review batches manually
File uploads are commonly used for high-volume batch workflows.
Validation and readiness
Before processing, each payout in a batch must be in a valid state.
Common requirements:
- Payee details are complete
- A valid payout method is available
- Required approvals are completed (if applicable)
Payouts that are not ready will remain in:
- RequiresPayeeInfo
- RequiresPayoutMethod
- NeedsApproval
Only payouts in ReadyToProcess will move into execution.
FX and currency conversion
When a batch includes payouts across currencies:
- A single FX quote is generated per currency pair (e.g. USD → EUR)
- All payouts using that pair share the same rate
- This ensures consistency and predictability across the batch
Benefits:
- Simplified reconciliation
- Consistent recipient outcomes
- Reduced rate fragmentation across payouts
Processing behavior
When a batch is processed:
- Eligible payouts move to Processing
- Payouts are sent through their selected payout methods
- Status updates occur asynchronously
Batch execution does not guarantee simultaneous delivery. Timing may vary based on:
- Payout method
- Country and currency
- External payment networks
Tracking batch results
Track batch performance at two levels:
Batch level
- Total number of payouts
- Number of payouts by status
- FX quotes applied per currency pair
- Overall progress and completion
Payout level
- Individual payout status
- Failure reasons
- Delivery confirmations
This allows you to quickly identify:
- Which payouts succeeded
- Which require action
Handling failures in batches
Failures are handled at the payout level.
If a payout fails:
- Review the failure reason
- Correct any issues (e.g. payee details, payout method)
- Retry the payout independently
You do not need to reprocess the entire batch.
Best practices
- Validate data upfront to minimize failures
- Group logically related payouts (e.g. by run or event)
- Use batches to consolidate FX exposure across payouts
- Monitor batch results during and after processing
- Use webhooks to track status changes programmatically
Summary
- Batch payouts enable scalable payout execution
- FX is grouped per currency pair, ensuring consistent rates
- Each payout maintains its own lifecycle and status
- Failures are isolated and recoverable
- Batches provide visibility and operational efficiency for high-volume workflows
Last modified on March 29, 2026
