> ## Documentation Index
> Fetch the complete documentation index at: https://docs.business.blaaiz.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating your first payout
> Step-by-step guide to creating your first payout
## Payout process
To help you get started with the payout process, we'll walk through the steps of creating your first payout using our API. We'll assume that you have completed the onboarding process, been whitelisted for API services, created your OAuth credentials, obtained an access token, and set up your webhooks for both collections and payouts. The following steps will guide you through the payout process:
### Step 1: Create a customer
Before you can make any payouts, you need to associate them with a customer. Every payout (and collection) must be linked to a customer in the system.
* **Endpoint**: `/customer`
* **Purpose**: This endpoint bootstraps the customer record in our system.
* **Status**: When a customer is first created, their `verification_status` is `PENDING`.
Make sure to save the `customer_id` returned from this endpoint as you'll need it in future steps.
The customer's `country` must match the identity document provided for KYC / KYB. Only `NON-VERIFIED` customers can be fully updated; once a customer is `VERIFIED`, only fields that are currently `null` can be updated. If you need to correct a mistake on a verified customer, see [Customer data corrections](/guides/customer-data-corrections).
For **individual customers**, the customer-level `id_type` is required and must be **Driver's License** (`drivers_license`), **Passport** (`passport`), or **Resident Permit** (`resident_permit`). **ID cards (National Identity Cards) are not accepted.** For **business customers**, the canonical identifier is `registration_number` + `incorporation_country` — the legacy `id_type` / `id_number` fields are **prohibited** on businesses (returns `422`). The actual incorporation document file goes into the KYB document collection (see Step 2 below), not through `/files`.
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.
### Step 2: Verify the customer
The verification flow depends on the customer's `type`. **Pick the path that matches your customer.** Mixing the two paths does not work.
The legacy KYC flow. Upload identity files, then verification triggers automatically when `id_file` is included.
#### 2.1 Request pre-signed URLs for document upload
* **Endpoint**: `/file`
* **Purpose**: Provides a pre-signed URL that allows you to upload documents for the customer.
* **Request**: Specify the `customer_id` and the `file_category` (`identity`, `identity_back`, `proof_of_address`, or `liveness_check`).
* **Response**: You'll receive a URL, a set of headers, and a `file_id`. The URL is where you will upload the actual document.
#### 2.2 Upload the document
* **Method**: Use the pre-signed URL to upload the document.
* **Request**: Perform a `PUT` request to the pre-signed URL, uploading the document as a binary file using the URL and headers provided.
Repeat this process for each required document.
#### 2.3 Add files to the customer
After uploading the documents, associate them with the customer using the `file_id` returned in the previous step.
* **Endpoint**: `POST /api/external/customer/{id}/files`
* **Request**: Pass the `customer_id` as a URL parameter, then include the `file_id` for each document in the request body.
* **Purpose**: Updates the customer by attaching the uploaded files to their profile. The customer status will remain `PENDING` while the documents are reviewed.
**`id_file` triggers verification.** Including `id_file` (the front identity document) in the request signals that document upload is complete and triggers the verification process. Other files (`id_file_back`, `proof_of_address_file`, `liveness_check_file`) can be uploaded before or alongside `id_file`, but verification will only begin once `id_file` is included in the request. If the identity document is two-sided (e.g. driver's license), upload the back side using `identity_back` as the file category and include `id_file_back` in the request.
**Verification is not instant.** Review typically completes within a few minutes; under additional screening it can take up to 2 hours. Do not raise support tickets within that window — they will not be attended to. Only escalate to [support@blaaiz.com](mailto:support@blaaiz.com) if a customer has been `PENDING` for 5 hours or more.
Listen for the [`customer.verified`](/guides/webhooks/customer) or [`customer.rejected`](/guides/webhooks/customer) webhook. Do not poll.
Business-type customers go through the **KYB flow** — beneficial owners, KYB document collection, and an explicit `/submit`. The legacy `/files` endpoint is **not used** for business customers.
#### 2.1 Add beneficial owners
Add owners by sending an `owners` array on `POST /customer` (at create time) or `PUT /customer/{id}` later. Up to 5 owners; their `ownership_percentage` values must sum to exactly 100 before submit.
```bash theme={null}
curl -X PUT https://api-prod.blaaiz.com/api/external/customer/CUSTOMER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"owners": [
{ "first_name": "Jane", "last_name": "Doe", "ownership_percentage": 60, "is_beneficial_owner": true },
{ "first_name": "John", "last_name": "Smith", "ownership_percentage": 40, "is_beneficial_owner": true }
]
}'
```
#### 2.2 Upload each owner's ID files
For each owner, two-step upload:
```bash theme={null}
# Step 1: get a presigned URL
curl -X POST \
https://api-prod.blaaiz.com/api/external/customer/CUSTOMER_ID/owner/OWNER_ID/file/presigned-url \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "file_category": "id_document_front" }'
# Step 2: PUT the file to the returned url, then register
curl -X POST \
https://api-prod.blaaiz.com/api/external/customer/CUSTOMER_ID/owner/OWNER_ID/files \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "id_document_front": "FILE_ID" }'
```
#### 2.3 Register KYB documents
The certificate of incorporation and any other corporate paperwork (articles, share register, bank statements, proof of address) go into the KYB document collection. Same two-step pattern: presigned URL → PUT to S3 → register.
```bash theme={null}
curl -X POST \
https://api-prod.blaaiz.com/api/external/customer/CUSTOMER_ID/document/presigned-url \
-H "Authorization: Bearer ACCESS_TOKEN"
# After PUTting the file...
curl -X POST \
https://api-prod.blaaiz.com/api/external/customer/CUSTOMER_ID/document \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "CERTIFICATE_OF_INCORPORATION",
"name": "Acme Corp — Certificate of Incorporation.pdf",
"file_id": "FILE_ID"
}'
```
You must register at least one document of a formation type (`CERTIFICATE_OF_INCORPORATION`, `ARTICLES_OF_INCORPORATION`, `BENEFICIAL_OWNERSHIP_CERTIFICATE`, `INCORPORATION_DOCUMENTS`, or `CAC_STATUS_REPORT`) before submit will accept the customer.
#### 2.4 Submit for verification
```bash theme={null}
curl -X POST \
https://api-prod.blaaiz.com/api/external/customer/CUSTOMER_ID/submit \
-H "Authorization: Bearer ACCESS_TOKEN"
```
The customer flips to `PROCESSING`. All `PENDING` owners and documents flip to `PROCESSING` along with it.
**Business KYB review typically takes 1–5 business days** — significantly longer than individual KYC. Wait for the `customer.status_changed` webhook. Do not poll. Only escalate to [support@blaaiz.com](mailto:support@blaaiz.com) if a customer has been in `PROCESSING` for more than 5 business days.
For the full walkthrough including the readiness rules, see [Onboarding a business customer](/guides/kyb/onboarding). Don't skip it — patterns like calling `/files` for a business customer fail silently and leave the customer stuck.
### Step 3: Create a payout
Now that the customer is verified (you have received the `customer.verified` webhook), you can proceed to create a payout.
* **Endpoint**: `/payout`
* **Purpose**: Initiate a payout associated with the verified customer.
Before initiating a payout, ensure the following prerequisites are in place for a smooth experience — requirements vary depending on the destination currency.
The following requirements apply regardless of which currency you are sending to.
**Customer must be verified**
Every payout must be linked to a verified customer. If the customer's identity has not been verified, the payout will be rejected. Make sure you have completed Step 1 and Step 2 above before attempting a payout — for `type=individual`, that means the legacy KYC flow with an accepted document type (Driver's License, Passport, or Resident Permit); for `type=business`, that means the [KYB flow](/guides/kyb/overview) with owners and a formation document.
**Wallet must exist**
The `wallet_id` you pass in the request must belong to your business. If the wallet does not exist or the ID is incorrect, the payout will fail.
**Sufficient balance**
Your wallet must have enough funds to cover both the payout amount and any applicable fees. We recommend calling the [fees breakdown](/api-reference/fees/get-breakdown) endpoint first to confirm the total cost before initiating the payout.
**Amount must exceed fees**
If you are specifying a `from_amount` (the amount you want to send), it must be greater than the total applicable fees. If the fees are equal to or exceed the amount, the payout will be rejected.
**Currency pair must be supported**
The combination of `from_currency_id` and `to_currency_id` must be an active, supported pair. If sending between those two currencies is not currently enabled, the payout will not go through.
**Payout method must be valid for the currency**
Each currency supports specific payout methods (e.g. `bank_transfer`, `interac`, `crypto`, `ach`, `wire`). If you use a method that is not available for the destination currency, the request will be rejected.
**Business must not be under Enhanced Due Diligence**
If your business has been placed under Enhanced Due Diligence (EDD) review, all payouts will be blocked until the review is resolved. Contact our support team if you encounter this.
**Customer must not be under Enhanced Due Diligence**
Similarly, if a specific customer has been flagged for Enhanced Due Diligence, payouts for that customer will be blocked. Reach out to support for assistance.
**Valid bank account details**
When making a payout to NGN via `bank_transfer`, the `bank_id` and `account_number` must be correct and match a real bank account. We perform a name enquiry to validate the account before processing. If the account is invalid, the payout will fail.
**Virtual Bank Account must be active**
Before you can make GBP payouts, your business (or your business customer) must have an active Virtual Bank Account for GBP. If the Virtual Bank Account has been created but is still pending activation, you will need to wait for it to be activated before proceeding.
To create a Virtual Bank Account, use the [create virtual bank account](/api-reference/virtual-bank-account/create) endpoint.
**Account name must match**
We perform a Confirmation of Payee (CoP) check for GBP payouts. The `account_name` you provide must match the name the recipient's bank has on file. If there is a mismatch, the payout will be rejected. Double-check the exact name on the recipient's bank account before submitting.
**Virtual Bank Account must be active**
Before you can make USD payouts, your business must have an active Virtual Bank Account for USD. If the Virtual Bank Account has been created but is still pending activation, you will need to wait for it to be activated before proceeding.
To create a Virtual Bank Account, use the [create virtual bank account](/api-reference/virtual-bank-account/create) endpoint.
**Customer must be eligible for USD payouts**
Before you can make a USD payout for a customer, the customer must have a USD Virtual Bank Account created. If this has not been done, the payout will be rejected.
**Virtual Bank Account must be active**
Before you can make EUR payouts, your business (or your business customer) must have an active Virtual Bank Account for EUR. If the Virtual Bank Account has been created but is still pending activation, you will need to wait for it to be activated before proceeding.
To create a Virtual Bank Account, use the [create virtual bank account](/api-reference/virtual-bank-account/create) endpoint.
**Recipient's bank must be SEPA reachable**
EUR payouts are processed via the SEPA network. If the recipient's bank (identified by their IBAN and BIC code) is not reachable through SEPA, the payout cannot be completed. Verify that the recipient's bank supports SEPA transfers.
**Cannot send to Blaaiz Virtual Bank Accounts**
Payouts to IBAN numbers that belong to Blaaiz Virtual Bank Accounts are not permitted. If you need to transfer funds to another Blaaiz user, use the Blaaiz retail app and send via P2P instead.
CAD payouts are sent via **Interac**. There are no additional prerequisites beyond the general requirements listed in the "All Currencies" tab. Ensure you provide the recipient's `email`, `interac_first_name`, and `interac_last_name` in your request.