Create a payout intent

Creates a new payout intent representing an instruction to disburse funds from one of your accounts. The intent is created in a pending state, or pending-approval when the entity has a default maker-checker approver group configured for payouts — in that case, the intent must be fully approved before it can be actioned. Once created, you attach a payout intent action (via the intent actions API) to actually move the funds.

Supplying schedule (together with a required action_template) turns this into a schedule-managed intent: instead of you creating actions manually, the platform automatically creates and fires a payout intent action for you each time the schedule is due, using action_template as the blueprint. A schedule-managed intent starts as scheduled (fires once) or recurring (fires repeatedly), unless the entity also requires maker-checker approval, in which case it still starts as pending-approval and is only armed once fully approved. Scheduling is only supported for single intents, not bulk.

The client_reference you supply must be unique per entity; attempting to create a second intent with the same reference for the same entity fails with a 400 error rather than creating a duplicate.

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

curl --location '/payout-intents' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "account_id": "01HXYZ1234567890ABCDEFGHIJ", "currency": "NGN", "amount": 50000, "client_reference": "payout_88abc123" }'

{ "message": "Payout intent created successfully", "status": "success", "data": { "id": "01HXYZ9876543210ZYXWVUTSRQ", "entity_id": "01HABC9999888877776666ZZZZ", "account_id": "01HXYZ1234567890ABCDEFGHIJ", "currency": "NGN", "amount": 50000, "client_reference": "payout_88abc123", "client_meta": null, "system_meta": null, "status": "pending", "reason": null, "supporting_documents": [], "status_reason": null, "status_code": null, "type": "single", "maker_checker_approver_group_id": null, "fully_approved_at": null, "schedule": null, "action_template": null, "next_run_at": null, "occurrence_count": 0, "last_fired_at": null, "created": 1754393520000, "updated": 1754393520000 } }

Request

Responses