Preview bulk payout intent actions

Performs a dry-run validation of a batch of payout intent action items against a bulk type payout intent that is in the pending state, without creating or persisting anything. Use this to surface per-item problems (bad shape, unresolvable bank account) to a caller before they submit the same items array to the POST /bulk-payout-intent-actions endpoint.

The entity_id is always resolved from the authenticated caller and cannot be supplied in the request body. The referenced payout_intent_id must belong to the authenticated entity, must be a bulk type intent (otherwise a 400 is returned), and must currently be in the pending status (otherwise a 400 is returned). The items array is capped at 200 entries; exceeding that limit returns a 400 before any per-item work is done.

Each entry in items is validated independently against the same per-item schema used at creation time. Items that pass validation are then checked against Flutterwave's account resolution service to confirm the destination account_number/bank_code pair resolves to a real account holder name. A resolution failure (invalid account, provider timeout, etc.) does not fail the whole request — it is recorded as a name_unresolved item alongside the underlying error message. The response always reflects the outcome of every submitted item, in the same order they were submitted, plus a summary count by outcome. Nothing is written to the database and no processing queue is used; calling this endpoint has no side effects on the payout intent or its actions.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

application/json

Preview computed successfully. This does not mean every item is valid — check summary and each item's status/error to see the per-item outcome.

Bodyapplication/json

curl --location '/bulk-payout-intent-action-previews' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "payout_intent_id": "01HXYZ9876543210ZYXWVUTSRQ", "items": [ { "type": "payout", "counterparty": { "email": "jane.doe@example.com", "account_number": "0123456789", "bank_code": "058" } } ] }'

{ "message": "Bulk payout intent actions previewed successfully", "status": "success", "data": { "payout_intent_id": "01HXYZ9876543210ZYXWVUTSRQ", "summary": { "total": 2, "valid": 1, "invalid": 1, "name_unresolved": 0 }, "items": [ { "index": 0, "status": "valid", "account_name": "JANE ADAEZE DOE", "error": null }, { "index": 1, "status": "invalid", "account_name": null, "error": "counterparty.email is required" } ] } }

Preview bulk payout intent actions

Request

Responses