Uploading is not the same as sending
Creating or importing a batch leaves it in draft. A separate process step moves accepted items forward.
Payout batch API
Send payout batches from your own systems
Create or import a batch, retry the same request with a unique key, inspect each item, and export current results. If webhooks are enabled, use batch events to update your systems.
JSON or CSV intakeRetry keysItem statusCSV results
terminal · zsh
// POST /v1/payout-batches/import
Idempotency-Key: <unique-key>
Content-Type: application/json
{ "items": [{ "beneficiary_id": "bnf_…", "currency": "<ISO currency>", "amount": "<decimal amount>" }] }response.json
{
"batch": { "id": "pbt_…", "derived_status": "DRAFT" },
"items_created": 1
}Batch events
payout_batch.imported
payout_batch.processed
payout_batch.completed
payout_batch.processed
payout_batch.completed
Available when webhooks are enabled for the account.
Input
JSON or CSV
Read
Batch + items
Actions
When available
Results
CSV export
Idempotency key
Reuse for the same request
What a payout integration needs to handle
A timeout should not create a new request
Reuse the same unique key when retrying the same instruction, so the API can recognize it as the original request.
Each failed row needs an explanation
Read the item status, reason code, and explanation instead of relying on the batch total alone.
Payout API
The API jobs your integration needs
API actions and webhooks are enabled per account. Once access is set up, your integration can create or import a batch, inspect it, move it forward, export the result, and receive the batch events available to that account.
Send JSON or CSV
Create a batch from structured items, or import one CSV or item payload.
Retry the same request
Changes require a unique idempotency key. Reuse that key only when retrying the same instruction.
Inspect the batch and its items
Read the batch, page through its items, and see source references, statuses, reasons, and linked payouts.
Move the batch forward
Process a draft batch, then use approval or execution actions when they are available to the account and valid for the item state.
Export the current result
Download batch items with their source fields, linked payouts, statuses, reason codes, and explanations.
Receive batch events
When webhooks are enabled for the account, receive imported, processed, and completed batch events.
How it works
From first request to the current result
More in Mass Payouts
Explore more in Mass Payouts
Payout risk review
See which payout instructions need attention, understand the reason, record the decision, and execute only approved item
Overview
Upload payout rows by CSV or API, catch field and beneficiary issues, review and process the batch, see each payout stat
Batch review
Review payment-run status, inspect individual payouts and reason codes, take the actions available to you, and download
Frequently Asked Questions
What can I submit through the payout batch API?+
Create a batch with structured items, or use the import endpoint with exactly one CSV or item payload. Each item needs a beneficiary, amount, and currency.
How should an integration use idempotency keys?+
Use a unique key for each supported change. If the response is uncertain, retry the same request with the same key. Reusing that key for a different request causes a conflict instead of silently changing the original operation.
Which payout batch webhook events are available?+
The batch workflow defines imported, processed, and completed events. Delivery requires webhooks to be enabled for the account.
How is API access set up?+
Access depends on your account, policy, credentials, and enabled features. Confirm test access, allowed actions, currencies, rate limits, and webhook configuration with Gruv during integration planning.
Next step
See where Gruv fits
Tell us what you are trying to do, where it needs to work, and how your team handles it today.
Contact the team