v1.5.0

1.5.0 (2026-09-28)

Features

• oauth: request the compliance-kyc scopes by default (2073b93)
• oauth: request the compliance-kyc:pii:read scope by default (fd2b6e6)
• signa: add Signa merchant KYC session service (6404e2c)
• signa: read captured applicant data and documents (0fcf2cc)

v1.4.0

1.4.0 - 2026-08-28

This release brings the SDK up to date with the current Blaaiz API. All Blaaiz SDKs move to 1.4.0 together, so the same version means the same features in every language.

Added

• Merchant reference on payouts and collections. Blaaiz saves it, returns it, and lets you find the transaction by it.
• Swaps: move money between two of your business wallets.
• Refunds: start a refund and get a refund.
• Rates: list the exchange rates for your business.
• Bank checks: verify a GBP account (payee) and a EUR IBAN.
• Interac money request: ask a payer for money by email.
• Business customer KYB: add and remove owners, upload owner ID files, upgrade to full KYB, and submit for review.
• Business customer documents: upload, list, get, update, and delete.

Fixed

• Create a business customer without personal ID fields. The API does not allow them for a business.
• Upload customer files with the correct request method.
• Start a collection without the old, unused currency field.
• Update and replay a webhook on the correct address.

Version 1.2.0

What's new

OAuth 2.0 client-credentials authentication. You can now authenticate with OAuth instead of an API key:

# OAuth (recommended)
blaaiz = Blaaiz(
    client_id=os.environ["BLAAIZ_CLIENT_ID"],
    client_secret=os.environ["BLAAIZ_CLIENT_SECRET"],
    # oauth_scope optional — defaults to all scopes
)

# Legacy API key (still works)
blaaiz = Blaaiz("your-api-key")

The SDK fetches a token from /oauth/token using the client_credentials grant, caches it, refreshes it ~60s before expiry, and sends it as Authorization: Bearer.

Backward compatibility

• API-key auth (x-blaaiz-api-key) is unchanged — existing code keeps working.
• When both OAuth credentials and an API key are set, OAuth is preferred.

Version 1.1.1

Added

• customers.list() accepts optional filters (email, id_number, registration_number, verification_status, type) and paginate=True for opt-in pagination (#1).

Version (1.1.0)

Release Notes - v1.1.0

Release Date: January 2026

This release aligns the Python SDK with the latest Blaaiz API documentation and adds several new features and improvements.

New Features

Customer Service

• list_beneficiaries(customer_id) - List all beneficiaries for a customer
• get_beneficiary(customer_id, beneficiary_id) - Get a specific beneficiary

Collection Service

• accept_interac_money_request(data) - Accept Interac money requests for CAD transfers

Payout Service

• ACH Payouts (USD) - Send payouts via ACH with routing number, account details
• Wire Payouts (USD) - Send wire transfers with SWIFT code support
• Crypto Payouts (USD) - Send payouts to crypto wallets (USDT, etc.)

Virtual Bank Account Service

• close(vba_id, reason) - Close a virtual bank account
• get_identification_type(customer_id, country, type) - Get ID type requirements for VBA creation

Webhook Service

• simulate_interac_webhook(data) - Simulate Interac webhooks in non-production environments

Breaking Changes

Webhook Signature Verification

The webhook signature format has changed from payload to timestamp.payload. This affects:

• verify_signature() - Now requires 4 parameters: raw_body, signature, timestamp, secret
• construct_event() - Now requires 4 parameters: payload, signature, timestamp, secret

Before (v1.0.0):

is_valid = blaaiz.webhooks.verify_signature(payload, signature, secret)
event = blaaiz.webhooks.construct_event(payload, signature, secret)

After (v1.1.0):

is_valid = blaaiz.webhooks.verify_signature(payload, signature, timestamp, secret)
event = blaaiz.webhooks.construct_event(payload, signature, timestamp, secret)

The timestamp is provided in the x-blaaiz-timestamp HTTP header.

Collection Service

• initiate() now requires customer_id and currency fields

Payout Service

• initiate() now requires customer_id field
• Supports either from_amount OR to_amount (not both required)

Customer Service

• create() validation updated: first_name/last_name only required for type: "individual"
• Business customers require business_name instead

Improvements

Currency-Specific Payout Validation

Bank transfer payouts now validate required fields based on currency:

Currency	Required Fields
NGN	bank_id, account_number
GBP	sort_code, account_number, account_name
EUR	iban, bic_code, account_name

Interac Payout Validation

Interac payouts (CAD) now require:

• email
• interac_first_name
• interac_last_name

ACH/Wire Payout Validation

ACH and Wire payouts (USD) require:

• type (individual/business)
• account_number
• account_name
• account_type (checking/savings)
• bank_name
• routing_number
• swift_code (Wire only)

Crypto Payout Validation

Crypto payouts require:

• wallet_address
• wallet_token
• wallet_network

Fees Service

• Now supports to_amount as an alternative to from_amount for reverse fee calculation

Virtual Bank Account Service

• list() now supports filtering by customer_id in addition to wallet_id

Migration Guide

1. Update Webhook Handlers

# Flask example
@app.route('/webhooks/collection', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('x-blaaiz-signature')
    timestamp = request.headers.get('x-blaaiz-timestamp')  # NEW
    payload = request.get_data(as_text=True)

    event = blaaiz.webhooks.construct_event(
        payload, signature, timestamp, WEBHOOK_SECRET  # timestamp added
    )

2. Update Collection Calls

# Add customer_id and currency
collection = blaaiz.collections.initiate({
    'customer_id': "customer-id",  # NEW - required
    'wallet_id': "wallet-id",
    'amount': 100,
    'currency': "NGN",  # NEW - required
    'method': "card",
})

3. Update Payout Calls

# Add customer_id
payout = blaaiz.payouts.initiate({
    'wallet_id': "wallet-id",
    'customer_id': "customer-id",  # NEW - required
    'method': "bank_transfer",
    'from_amount': 1000,
    'from_currency_id': "NGN",
    'to_currency_id': "NGN",
    'bank_id': "1",
    'account_number': "0123456789",
})

Installation

pip install --upgrade blaaiz

Full Changelog

See README.md for the complete changelog.

Support

• Documentation: https://docs.business.blaaiz.com
• Email: onboarding@blaaiz.com
• Issues: https://github.com/blaaiz/blaaiz-python-sdk/issues

Version (1.0.5)

v1.0.5

bump version

Version (1.0.4)

v1.0.4

bumped version

Version (1.0.3)

v1.0.3

updated version -2

Version (1.0.2)

v1.0.2

bump version