Record a payout intent action as returned

Marks a previously successful payout intent action as returned when the disbursed funds bounce back (e.g. an invalid destination bank account rejects the transfer). Only an action currently in the successful status is eligible; attempting this on an action in any other status fails with a 400 error.

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

On success, the action's status is set to returned and its status_reason/system_meta.return are updated with the return details. A reversing ledger transaction is created against the debited account for amount_returned, crediting the funds back. If the parent payout intent is a single type intent, its status is also advanced to returned. amount_returned must not exceed the action's original amount, otherwise the request fails with a 400 error. This operation is not idempotent — calling it again for the same action after it has already been returned fails because the action is no longer in the successful status.

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-returns' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "payout_intent_action_id": "01HXYZ9876543210ZYXWVUTSRQ", "amount_returned": 50000, "return_reason": "Invalid destination account number" }'

{ "message": "Payout intent action returned successfully", "status": "success", "data": { "id": "01HXYZ9876543210ZYXWVUTSRQ", "entity_id": "01HABC1234567890ENTITYIDXX", "account_id": "01HXYZ1234567890ABCDEFGHIJ", "currency": "NGN", "amount": 50000, "payout_intent_id": "01HXYZAAAAAAAAAAAAAAAAAAAA", "client_meta": null, "system_meta": { "return": { "amount_returned": 50000, "returned_at": 1735689600000, "return_reason": "Invalid destination account number" } }, "narration": "Vendor settlement for invoice #4521", "client_reference": "action_ref_88abc123", "counterparty": { "email": "jane.doe@example.com", "account_number": "0123456789", "bank_code": "058" }, "type": "payout", "status": "returned", "status_reason": "Invalid destination account number", "provider_code": "flutterwave", "applicable_fee": 100, "source_amount": null, "source_currency": null, "exchange_rate": null, "conversion_fee": null, "quote_id": null, "occurrence_number": null, "scheduled_for": null, "created": 1735603200000, "updated": 1735689600000 } }

Record a payout intent action as returned

Request

Responses