Create a payout intent action

Creates the action that actually moves funds for a single type payout intent that is in the pending state. This is a one-to-one operation for single intents: once an action exists for a payout intent, subsequent attempts fail with a 400 error instructing you to use the retry endpoint instead. Bulk intents must use the bulk payout intent actions endpoint instead of this one.

The entity_id is always resolved from the authenticated caller and cannot be supplied in the request body.

Two action types are supported via type:

cash-offline — records an offline/manual disbursement. No provider or fee is resolved and the action is marked successful immediately.

payout — dispatches the disbursement through a live payment provider. The endpoint resolves an enabled provider and applicable fee for the destination currency, checks that the debited account has sufficient available ledger balance (returning 400 if it does not), creates the action in a pending state, and queues it for asynchronous processing.

account_id, currency, and amount are all optional and fall back to the values already set on the parent payout intent when omitted, letting you override any of them per-action. The counterparty object identifies the bank account the funds are sent to; if a matching counterparty and bank instrument already exist for the entity they are reused, otherwise new records are created as part of this call.

For a payout type action where the destination currency differs from the debited account's currency, quote_id must reference a previously created, still-active currency conversion quote whose from_currency matches the account currency; the quote is claimed exclusively by this action (reusing an already-consumed quote fails with a 409) and its from_amount, exchange rate, and fee are pinned onto the action as source_amount, source_currency, exchange_rate, and conversion_fee.

When called with a JWT session, this endpoint also requires a valid, unused money_action_confirmation_id (minted via POST /money-action-confirmations with action_type payout_action and reference_id set to the payout_intent_id, after the caller re-confirms their PIN) in the request body. This requirement is skipped entirely for secret-API-key requests, since PIN confirmation only applies to interactive human sessions.

For single intents, a successful call also advances the parent intent's status to processing (for payout) or successful (for cash-offline).

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-intent-actions' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "payout_intent_id": "01HXYZ9876543210ZYXWVUTSRQ", "type": "payout", "counterparty": { "email": "jane.doe@example.com", "account_number": "0123456789", "bank_code": "058", "bank_name": "Guaranty Trust Bank" } }'

{ "message": "Payout intent action created successfully", "status": "success", "data": { "id": "01HXYZAAAABBBBCCCCDDDDEEEE", "entity_id": "01HABC9999888877776666ZZZZ", "account_id": "01HXYZ1234567890ABCDEFGHIJ", "currency": "NGN", "amount": 50000, "payout_intent_id": "01HXYZ9876543210ZYXWVUTSRQ", "client_meta": null, "system_meta": null, "narration": "Vendor settlement for invoice #4521", "client_reference": null, "counterparty": { "id": "01HCPTYAAAABBBBCCCCDDDDEE", "account_number": "0123456789", "bank_code": "058", "bank_name": "Guaranty Trust Bank", "email": "jane.doe@example.com" }, "type": "payout", "status": "pending", "status_reason": null, "provider_code": "flutterwave", "applicable_fee": 250, "source_amount": 50000, "source_currency": "NGN", "exchange_rate": 1, "conversion_fee": 0, "quote_id": null, "occurrence_number": null, "scheduled_for": null, "created": 1754393520000, "updated": 1754393520000 } }

Create a payout intent action

Request

Responses