API parameters

Request parameters

While interacting with our API, you may encounter specific parameters in the request body for various endpoints. Below are key parameters and their possible values.

Do not use method: "crypto" with the Payout API. Use the Crypto API for wallet swaps and on-chain crypto payouts. Crypto collections remain available for eligible, crypto-enabled businesses.

Method

The method parameter appears in the Payout API when initiating a payout. It represents the channel through which the money will be sent.

bank_transfer – Sends the payout via bank transfer (available for NGN, GBP, EUR transactions).
interac – Sends the payout using Interac (available for CAD transactions).
ach - Sends the payout using ACH (available for USD transactions).
wire - Sends the payout using Wire (available for USD transactions).
mobile_money – Sends the payout to a mobile money account (available for KES, UGX, TZS, XOF, and GHS transactions). The destination currency must support the method.

Use the value that matches the payout method and the payout currency.

When method is mobile_money, you must send phone_number, mobile_money_operator_id, and account_name. The account_name is the name on the mobile money account. You do not need bank fields. See Mobile money operator and Phone number.

For the Collection API, the currently documented value is:

card - Creates a card collection request for a business wallet.

Destination currency

The to_currency_id parameter appears in the Payout API. It sets the currency that the recipient gets. You can send the currency ID or the currency 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. Get the ID from the List all currencies endpoint. Each currency in the response includes country_id and country.
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.

For a mobile money payout, the destination currency decides the country.

Mobile money operator

The mobile_money_operator_id parameter appears in the Payout API when method is mobile_money. It identifies the mobile money operator of the recipient, for example M-Pesa.

Get the value from the List mobile money operators endpoint. Use the id field of the operator.
Send the currency_id query parameter with the ID of the destination currency. The endpoint then returns only the operators for that country.
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.

Phone number

The phone_number parameter appears in the Payout API when method is mobile_money. It is the phone number of the recipient's mobile money account.

Use the international format with a leading +, for example +254712345678.

Merchant reference

The optional merchant_reference parameter appears in the Payout API and the Collection API. Send your own identifier for the transaction, for example an order ID or an invoice number. You then do not have to keep a map between your identifier and the Blaaiz transaction ID.

Blaaiz accepts any string up to 255 characters. No format is enforced.
Each value must be unique for your business. If an earlier payout or collection already uses the value, the request fails with 422 and this message: Could not proceed. Kindly check your merchant reference and try again.
Two different businesses can use the same value.
Blaaiz returns the value on the transaction endpoints. It also sends the value on the collection, payout and payout-initiated webhooks.
Get transaction accepts the value in place of the transaction ID. Blaaiz reads the transaction ID first, then the transaction reference, then your merchant_reference.
List transactions accepts the value as a filter.

Blaaiz keeps the reference after it creates the transaction, whatever the final status. If a payout or a collection fails, use a new merchant_reference for the retry.

File category

The file_category parameter appears in the File API when requesting a pre-signed URL for upload. It represents the type of file you want to upload, for individual customers only.

The File API and file_category apply to individual customers (type=individual) only. For type=business customers, use the dedicated KYB upload endpoints — see Business customer KYB. Calling the File API for a business customer does not trigger verification.

identity – Identity document. Required to verify an individual customer. Must be a Driver's License, Passport, or Resident Permit. ID cards (National Identity Cards) are not accepted. No other document types are supported at this category.
identity_back – Back side of the identity document. Use this when the identity document is two-sided (e.g. driver's license). Not required for single-sided documents (e.g. passport).
proof_of_address – Proof of address.
liveness_check – Liveness check.

All uploaded documents must be clear, legible, and authentic. Blurry, cropped, obscured, or otherwise unclear images will not be reviewed and will be rejected. Fraudulent or falsified documents will not be tolerated — repeated attempts to submit false or invalid documents will result in the customer being permanently blacklisted from the platform. There are no exceptions or compromises.

Id type

The id_type parameter appears in the Customer API when creating or updating a customer.

For individual customers, id_type is required at create time. Only the following are accepted:

drivers_license – Driver's License.
passport – Passport.
resident_permit – Resident Permit.

For business customers, id_type and id_number are prohibited — sending either returns 422. Businesses identify via registration_number + incorporation_country. The actual certificate of incorporation goes into the KYB document collection (type=CERTIFICATE_OF_INCORPORATION), not through the File API. See Business customer KYB.

No other identity document types are accepted at the customer level. ID cards (National Identity Cards) are not accepted. Individual customers must provide a Driver's License, Passport, or Resident Permit. Business customers do not need to provide a customer-level identity document.

Customer type

The type parameter appears in the Customer API when creating a new customer. It represents the type of customer to be created, i.e. individual or business.

individual – Individual.
business – Business.

TIN

The tin parameter appears in the Customer API for countries and customer types where a tax identification field is required.

Do not hardcode the label shown to your users.
Use the Get identification type endpoint to retrieve the correct country-specific label or field before collecting the value.

On this page