Skip to main content
Gruv.ai logo
Payout batch API

Keep your system connected to each payout result

Send approved payout items from your system, follow the batch and bring the results back. Use request keys for unchanged retries and current item states for payment follow-up.

Discuss your payout integrationFollow one API request

Your payout system → Gruv

Import request · Idempotency-Key

september-run-218-import

Three approved payout items. One request identity.

Original batch response

pbt_218

Status at import

IMPORTED

Keep the original key when the response is uncertain

Your import completed, but your system lost the response. While that response is retained, retry the unchanged request with the same key to retrieve it.

Retry the import

september-run-218-import

Keep the account, request path and body unchanged. The stored response identifies pbt_218 as imported.

Read the current batch

Use a fresh batch read for the latest status. The replayed response describes the original operation; it does not refresh as payments move forward.

What if the request changed or is still running?

A different request with the same key conflicts with the original. A request still in progress can also return a conflict. Keep the original key for an unchanged retry and handle the returned status. Confirm key retention during integration setup.

Separate operation · Process pbt_218

Idempotency-Key: september-run-218-process

Processing uses its own request key and creates payment records for imported items that still need them. Approval and execution steps may follow. Processing is not confirmation that recipients have been paid.

Read the results behind a completed event

With batch webhooks enabled, your system can receive a completed event for pbt_218. Here, every item has reached a final state, but only two payments completed successfully.

Read the status counts and follow the item link to investigate the failed payment. Keep that result attached to its source record.

Does the event mean all recipients were paid?

No. A completed batch event can include failed or canceled items. Inspect the batch status and individual results before marking payments as paid in your own system.

payout_batch.completed

pbt_218

COMPLETED_WITH_FAILURES

Items
3
Completed
2
Failed
1

Use the batch and item links in the event to read the current result.

More in Mass Payouts

Explore more in Mass Payouts

Payout risk review

Review payout decisions and items that need attention before execution.

Mass payments

Follow an imported list through processing and individual payment results.

Payout review

Inspect source references, payment states and reason details.

Frequently Asked Questions

What can our system submit?+
Create a batch from structured items, or import exactly one CSV or items payload. Each item needs a beneficiary ID, currency and amount. Public API amounts are decimal values; use the appropriate template when preparing a portal import.
Does processing send every payment?+
Processing creates payment records for items that still need them. Required approval and execution steps remain separate. It does not retry an already linked failed payment.
Which batch events can we receive?+
Imported, processed and completed batch events are available when webhooks are enabled for the account. Read the status and item counts, then retrieve current details when your system needs the latest result.
What needs to be agreed during integration setup?+
Confirm account access, credentials, allowed operations, amount format, request-key retention and webhook configuration. We’ll work through the request and failure paths with your team.

Connect the request to the result

Tell us where your payout data lives and how your system handles payment updates. We’ll work through the integration and follow-up together.

Discuss your payout integration