Cancel a payout intent

DELETE

/payout-intents/{id}

Cancels a payout intent outright, before any payout intent action has been created against it. The intent must belong to the authenticated entity — the entity_id from the bearer token is automatically applied as a scoping condition, so callers cannot cancel payout intents belonging to other entities. Only intents in the new or pending state can be cancelled through this endpoint; once an action has been created (or the intent has moved past those states for any other reason) it can no longer be cancelled here. The transition is race-safe: it is applied as an atomic, status-guarded update, so a cancellation that lands concurrently with a POST /payout-intent-actions request for the same intent cannot succeed against an intent an action has just been created for. This endpoint is unrelated to DELETE /payout-intent-schedules/{id}, which cancels an active recurring/scheduled intent's schedule rather than the intent itself.

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 ********************

Path Params

Responses

🟢200

application/json

The payout intent was cancelled successfully. The full, current representation of the intent is returned with status set to cancelled.

Bodyapplication/json

🟠400

🟠401

🟠404

Request Example

Shell

JavaScript

Java

Swift

curl --location --request DELETE '/payout-intents/01J3KQZM0000000000000000AB' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Success

{
    "message": "Payout intent cancelled successfully",
    "status": "success",
    "data": {
        "id": "01J3KQZM0000000000000000AB",
        "entity_id": "01HQZR2BKPFQ8MXJVT3G7LWNA",
        "account_id": "01HQZR2BKPFQ8MXJVT3G7LWNE",
        "currency": "NGN",
        "amount": 500000,
        "client_reference": "payout-ref-20260812-001",
        "client_meta": {
            "invoice_id": "inv-88213"
        },
        "system_meta": null,
        "status": "cancelled",
        "reason": "Vendor reimbursement for Q3 logistics",
        "supporting_documents": [
            {
                "title": "Vendor invoice",
                "type": "invoice",
                "url": "https://files.example.com/invoices/inv-88213.pdf"
            }
        ],
        "status_reason": null,
        "status_code": null,
        "type": "single",
        "counterparty": {
            "email": "vendor@example.com",
            "account_number": "0123456789",
            "bank_code": "058"
        },
        "maker_checker_approver_group_id": null,
        "fully_approved_at": null,
        "schedule": null,
        "action_template": null,
        "next_run_at": null,
        "occurrence_count": null,
        "last_fired_at": null,
        "created": 1754524800000,
        "updated": 1754611200000
    }
}

Modified at 2026-09-30 00:29:45

Edit a payout intent's active schedule

Create a virtual card