Creating your first payout

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.

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"
  }'

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

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.

For the full walkthrough including the readiness rules, see Onboarding a business customer. Don't skip it — patterns like calling /files for a business customer fail silently and leave the customer stuck.

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 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 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 fiat payout methods, such as bank_transfer, interac, ach, and wire. The API rejects unsupported methods.

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 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 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 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.