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. 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.
Individual customer
Business customer
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 if a customer has been PENDING for 5 hours or more.Listen for the customer.verified or customer.rejected 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.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:# 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.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"
}'
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
curl -X POST \
https://api-prod.blaaiz.com/api/external/customer/CUSTOMER_ID/submit \
-H "Authorization: Bearer ACCESS_TOKEN"
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 if a customer has been in PROCESSING for more than 5 business days. /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.
All Currencies
NGN
GBP
USD
EUR
CAD
The following requirements apply regardless of which currency you are sending to.Customer must be verifiedEvery 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 with owners and a formation document.Wallet must existThe 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 balanceYour wallet must have enough funds to cover both the payout amount and any applicable fees. We recommend calling the fees breakdown endpoint first to confirm the total cost before initiating the payout.Amount must exceed feesIf 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 supportedThe 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 currencyEach 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 DiligenceIf 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 DiligenceSimilarly, 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 detailsWhen 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 activeBefore 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 endpoint.Account name must matchWe 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 activeBefore 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 endpoint.Customer must be eligible for USD payoutsBefore 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 activeBefore 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 endpoint.Recipient’s bank must be SEPA reachableEUR 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 AccountsPayouts 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.
