Retry a failed payout intent action

Creates a new action to retry a payout_intent_id whose most recent action failed. The parent payout intent must currently be in the failed status and must have no pending or processing action outstanding, otherwise the request fails with a 400 error.

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

Any of account_id, currency, amount, narration, client_reference, client_meta, and counterparty may be supplied to override the corresponding value on the retry. Any field omitted falls back to the value already recorded on the payout intent's most recent (failed) action — for example, omitting counterparty reuses the email, account_number, bank_code, and bank_name captured on that prior action. The type (cash-offline or payout) is always inherited from the last action and cannot be changed on retry.

As with creating an action, payout type retries resolve an enabled provider and applicable fee for the destination currency, check that the debited account has sufficient available ledger balance (returning 400 if it does not), create the new action in a pending state, and queue it for asynchronous processing. cash-offline type retries complete immediately in the successful state with no provider or fee resolution.

A successful retry does not by itself change the parent payout intent's status back from failed; the intent's status updates as the newly queued action is processed.

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-action-retries' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "payout_intent_id": "01HXYZ9876543210ZYXWVUTSRQ" }'

{ "message": "Payout intent action retried successfully", "status": "success", "data": { "id": "01HXYZBBBBCCCCDDDDEEEEFFFF", "entity_id": "01HABC9999888877776666ZZZZ", "account_id": "01HXYZ1234567890ABCDEFGHIJ", "currency": "NGN", "amount": 50000, "payout_intent_id": "01HXYZ9876543210ZYXWVUTSRQ", "client_meta": { "internal_ref": "acct-payout-77-retry" }, "system_meta": null, "narration": "Vendor settlement for invoice #4521 (retry)", "client_reference": "action_ref_88abc123_retry", "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, "created": 1754393520000, "updated": 1754393520000 } }

Retry a failed payout intent action

Request

Responses