Send a payout

Raise a payout and commit the money to it. The money is reserved before this returns, whether or not the payout needs approval. A `requires_approval` response therefore means "the funds are held and somebody must sign", not "nothing has happened yet". In **test mode** the payout is settled as it is raised: no rail is involved, so the response already carries the outcome. `amount_minor` and the destination decide what that outcome is — see the sandbox guide for the values that produce a decline, a timeout, a return or a review hold.

Raise a payout and commit the money to it.

The money is reserved before this returns, whether or not the payout needs approval. A requires_approval response therefore means "the funds are held and somebody must sign", not "nothing has happened yet".

In test mode the payout is settled as it is raised: no rail is involved, so the response already carries the outcome. amount_minor and the destination decide what that outcome is — see the sandbox guide for the values that produce a decline, a timeout, a return or a review hold.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

What a payout is made of.

Every field carries a description and an example, and both are load-bearing rather than decoration — E11-16. The description is what a reader sees on the operation page; the example is what the reference's playground fills the field with, so "Send" on a freshly-opened page sends a request that is valid rather than one made of "string" and 1. A playground whose default body is refused teaches an integrator that the endpoint is fussy, when what it actually taught them is that nobody filled in an example.

idempotency_key*Idempotency Key

Your reference for this attempt. Send the same key again and you get the original payout back rather than a second one — which is how you retry safely after a timeout, the only sane thing to do when you did not hear our answer.

Length8 <= length <= 128

Example"payroll-2026-08-0042"

amount_minor*Amount Minor

What the recipient receives, in minor units — 150,000 RWF is 15000000. Never a decimal: a decimal amount is a rounding argument waiting to happen.

Range0 < value

Example15000000

currency*Currency

ISO 4217, three letters. RWF, UGX or EUR.

Length3 <= length <= 3

Example"RWF"

method*PayoutMethod

How the money is delivered. Decides the rail together with the corridor, and decides the shape of destination.

Example"mobile_money"

Value in

"bank"
"mobile_money"
"card"
"bill"

transaction_type*PayoutTransactionType

B2P paying a person, B2B paying a business. Required, never inferred: it is a different product to the partner and a different line in a regulator's report, so guessing it would be guessing at money.

Example"b2p"

Value in

"b2p"
"b2b"

category?|

What the money was for, for cash-flow reporting — payroll, vendor, bill or other. Optional, and a different question to transaction_type: that records who is paid for corridor policy, this records what for. Leave it out and one is derived where the system can be certain — a bill method is a bill, a payout raised by a payroll run is payroll — so in practice only vendor needs stating, because nothing else distinguishes a supplier from a one-off contractor.

Example"vendor"

fee_minor?|

Leave it out. InversePay's fee is priced from your plan and comes back on the payout as fee_minor, added to amount_minor to make total_minor, what leaves your balance - the recipient still receives amount_minor. Anything but 0 is refused.

Examplenull

beneficiary_id?|

A saved, screened recipient. Its name, country and destination fill in anything omitted here. Preferred over a raw destination for anything you will pay twice, and the only way to have the account name-checked before money is committed.

destination?||

Where the money goes. Omit it when you send beneficiary_id — a saved beneficiary carries its own.

The shape depends on method. These are the shapes our rails read; the field itself is not yet validated against them, so a mistyped key is accepted here and fails at the rail. If you want the account checked before anything is committed, save a beneficiary and pay that instead — it is name-checked and screened.

recipient_name?|

The name on the account. Taken from the beneficiary when you send one, and shown on statements either way.

Example"Aline Uwase"

country_code?|

ISO 3166-1 alpha-2. Decides the corridor when the currency does not — RWF is enough for Rwanda, and a euro payout needs to say which country.

Example"RW"

reference?|

Your own reference for this payment. Returned on every read and shown on statements.

Example"AUG-SALARY-0042"

mfa_code?|

A code from your authenticator app, required for a large payout when you have one set up. Send the payout without it first: the refusal names the threshold and says a code is needed, so there is no need to guess whether this one crosses it.

Example"123456"

Response Body

`application/json`

curl -X POST "https://example.com/api/b/v1/payouts" \  -H "Content-Type: application/json" \  -d '{    "idempotency_key": "payroll-2026-08-0042",    "amount_minor": 15000000,    "currency": "RWF",    "method": "mobile_money",    "transaction_type": "b2p"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "reference": "string",  "amount_minor": 0,  "fee_minor": 0,  "total_minor": 0,  "currency": "string",  "status": "created",  "method": "string",  "transaction_type": "string",  "category": "string",  "recipient_name": "string",  "country_code": "string",  "rail": "string",  "provider_reference": "string",  "failure_reason": "string",  "approval_id": "15af2260-72db-4fc4-b587-6b841d6a3d55",  "created_at": "2019-08-24T14:15:22Z",  "completed_at": "2019-08-24T14:15:22Z"}

Request Body

Response Body

201application/json

400application/json

402application/json

409application/json

422application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`