Create a payout

Do not use method: "crypto" with this endpoint. Use the Crypto API for wallet swaps and on-chain crypto payouts.

Use this endpoint to start a payout from a business wallet to a recipient with a supported fiat payout method.

Call the fees breakdown endpoint to get the current fees before you create a payout.

To pay a mobile money account, set method to mobile_money. Send phone_number, mobile_money_operator_id, and account_name. You do not need bank fields. Mobile money is available for KES, UGX, TZS, XOF, and GHS. Call the list mobile money operators endpoint to get the operator ID.

Blaaiz sends a webhook when the payout completes. For some currencies, such as CAD, Blaaiz also sends a webhook when processing starts. Required scope: payout:create.

POSTapi-prod.blaaiz.com/api/external/payout

Authorization

oauth2ClientCredentials payout:create

AuthorizationBearer <token>

Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.

In: header

Scope: payout:create

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

wallet_id*string

Business wallet ID

customer_id*string

The ID of your own business customer. You make this payout on behalf of that customer, not to that customer. The customer must belong to your business and have verification_status=VERIFIED. Both type=individual (verified through the legacy KYC flow) and type=business (verified through the KYB flow) are accepted. You describe the recipient in separate fields, such as account_number, iban, routing_number, interac_first_name, and interac_last_name, depending on the payout method and currency.

method*string

Payout method. Use mobile_money to pay a mobile money account in KES, UGX, TZS, XOF, or GHS. The destination currency must support the method.

Value in

"bank_transfer"
"interac"
"wire"
"ach"
"mobile_money"

from_amount?number

Amount being sent (omit if using to_amount)

to_amount?number

Exact amount the recipient should receive

from_currency_id*string

Currency the business pays with (ID or code)

to_currency_id*string

Currency the recipient gets (ID or code). XOF is offered in more than one country, for example Benin and Côte d'Ivoire. Each country has its own XOF currency ID. Send the currency ID for XOF. If you send the code XOF, you must also send country_id. If you do not, the request fails with 422 on to_currency_id. The destination currency sets the country of a mobile money payout.

type?string

Required if method is ach/wire

Value in

"individual"
"business"

phone_number?string

Required when method is mobile_money. The phone number of the mobile money account, in international format with a leading +, for example +254712345678.

email?string

Required for interac

interac_first_name?string

Required for interac

interac_last_name?string

Required for interac

bank_id?string

Required when method=bank_transfer and currency=NGN

account_number?string

Required for bank_transfer/ach/wire when currency not EUR/CAD

account_name?string

Required for bank_transfer/ach/wire when currency is USD/GBP/EUR. Also required when method is mobile_money. For mobile money, this is the name on the mobile money account.

mobile_money_operator_id?integer

Required when method is mobile_money. The id of the mobile money operator, from the list mobile money operators endpoint (GET /api/external/momo-operator). The operator must belong to the country of the destination currency. If it does not, the request fails with 422 on mobile_money_operator_id.

account_type?string

Required for ach/wire when currency=USD

Value in

"checking"
"savings"

bank_name?string

Required for ach/wire when currency=USD

routing_number?string

Required for ach/wire when currency=USD

swift_code?string

Required for wire when currency=USD

sort_code?string

Required for bank_transfer when currency=GBP

iban?string

Required for bank_transfer when currency=EUR

bic_code?string

Required for bank_transfer when currency=EUR

country?string

Required for bank_transfer/ach/wire when currency is USD/EUR/GBP

state?string

Required for ach/wire when currency=USD

street?string

Required for bank_transfer/ach/wire when currency is USD/EUR/GBP

city?string

Required for bank_transfer/ach/wire when currency is USD/EUR/GBP

zip_code?string

Required for bank_transfer/ach/wire when currency is USD/EUR/GBP

country_id?string

Optional country helper. Send it with the code XOF in to_currency_id to choose the country. You do not need it when you send a currency ID.

note?string

Narration; defaults to business name if empty

merchant_reference?string

Your own reference for this payout. Blaaiz stores the value and returns it on the transaction endpoints and the webhooks. Each value must be unique for your business. Maximum 255 characters.

Lengthlength <= 255

Response Body

`application/json`

Create a payout

curl --request POST \  --url 'https://example.com/api/external/payout' \  --header 'Content-Type: application/json' \  --data '{  "wallet_id": "b18ed308-5ac5-4e9e-bb16-8c03ec2d3c01",  "customer_id": "9d4c4ec5-59ea-4130-bf8a-6a5edec401ee",  "method": "bank_transfer",  "from_amount": 5000,  "from_currency_id": "NGN",  "to_currency_id": "NGN",  "account_number": "0222500691",  "bank_id": "1"}'

{  "message": "Payout Initiated Successfully.",  "transaction": {    "id": "f20199fd-bdaf-483b-8ff1-08f9ab12f4ca",    "business_id": "9d46461e-f991-423e-9f23-1dbff4079119",    "business_customer_id": "9d4c4ec5-59ea-4130-bf8a-6a5edec401ee",    "business_wallet_id": "9228327b-d448-43f4-a78a-0211edad4365",    "status": "SUCCESSFUL",    "reference": "ef5ba1ca-2a5f-4092-b19d-11f9f7ecbbac",    "external_reference": null,    "currency": "NGN",    "amount": 473,    "amount_without_fee": 473,    "fee": 0,    "rate": 1,    "date": "2024-10-18T11:38:17.000000Z",    "recipient": {      "id": "6c258e65-de94-4d9d-87fb-117480a9d0e7",      "account_number": "1234567890",      "account_name": "Tunde Balogun",      "amount": 473,      "currency": "NGN",      "bank_name": "Access Bank",      "bank_code": "044"    }  }}

Create a payout

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`