Batch payouts let you send multiple payouts in a single operation.
They are designed for workflows where you need to process many payouts together, such as claims runs, vendor payments, or scheduled disbursements.
Using batches provides visibility, control, and efficiency when operating at scale.
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
