# Blaaiz Python SDK
A comprehensive Python SDK for the Blaaiz RaaS (Remittance as a Service) API. This SDK provides easy-to-use methods for payment processing, collections, payouts, customer management, and more.
## Installation
```bash
pip install blaaiz-python-sdk
```
## Quick Start
```python
from blaaiz import Blaaiz
# Initialize the SDK
blaaiz = Blaaiz('your-api-key-here', base_url='https://api-dev.blaaiz.com')
# Test the connection
is_connected = blaaiz.test_connection()
print(f'API Connected: {is_connected}')
```
## Features
- **Customer Management**: Create, update, and manage customers with KYC verification
- **Collections**: Support for multiple collection methods (Open Banking, Card, Crypto, Bank Transfer)
- **Payouts**: Bank transfers and Interac payouts across multiple currencies
- **Virtual Bank Accounts**: Create and manage virtual accounts for NGN collections
- **Wallets**: Multi-currency wallet management
- **Transactions**: Transaction history and status tracking
- **Webhooks**: Webhook configuration and management with signature verification
- **Files**: Document upload with pre-signed URLs
- **Fees**: Real-time fee calculations and breakdowns
- **Banks & Currencies**: Access to supported banks and currencies
## Supported Currencies & Methods
### Collections
- **CAD**: Interac (push mechanism)
- **NGN**: Bank Transfer (VBA) and Card Payment
- **USD**: Card Payment
- **EUR/GBP**: Open Banking
### Payouts
- **Bank Transfer**: All supported currencies
- **Interac**: CAD transactions
## API Reference
### Customer Management
#### Create a Customer
```python
customer = blaaiz.customers.create({
'first_name': "John",
'last_name': "Doe",
'type': "individual", # or "business"
'email': "john.doe@example.com",
'country': "NG",
'id_type': "passport", # drivers_license, passport, id_card, resident_permit
'id_number': "A12345678",
# 'business_name': "Company Name" # Required if type is "business"
})
print(f'Customer ID: {customer["data"]["data"]["id"]}')
```
#### Get Customer
```python
customer = blaaiz.customers.get('customer-id')
print(f'Customer: {customer["data"]}')
```
#### List All Customers
```python
customers = blaaiz.customers.list()
print(f'Customers: {customers["data"]}')
```
#### Update Customer
```python
updated_customer = blaaiz.customers.update('customer-id', {
'first_name': "Jane",
'email': "jane.doe@example.com"
})
```
### File Management & KYC
#### Upload Customer Documents
**Method 1: Complete File Upload (Recommended)**
```python
# Option A: Upload from bytes
with open('passport.jpg', 'rb') as f:
file_data = f.read()
result = blaaiz.customers.upload_file_complete('customer-id', {
'file': file_data,
'file_category': 'identity', # identity, proof_of_address, liveness_check
'filename': 'passport.jpg',
'content_type': 'image/jpeg'
})
# Option B: Upload from Base64 string
result = blaaiz.customers.upload_file_complete('customer-id', {
'file': 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
'file_category': 'identity'
})
# Option C: Upload from Data URL
result = blaaiz.customers.upload_file_complete('customer-id', {
'file': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
'file_category': 'identity'
})
# Option D: Upload from Public URL
result = blaaiz.customers.upload_file_complete('customer-id', {
'file': 'https://example.com/documents/passport.jpg',
'file_category': 'identity'
})
print(f'Upload complete: {result["data"]}')
print(f'File ID: {result["file_id"]}')
```
**Method 2: Manual 3-Step Process**
```python
# Step 1: Get pre-signed URL
presigned_url = blaaiz.files.get_presigned_url({
'customer_id': 'customer-id',
'file_category': 'identity'
})
# Step 2: Upload file to the pre-signed URL (implement your file upload logic)
# Step 3: Associate file with customer
file_association = blaaiz.customers.upload_files('customer-id', {
'id_file': presigned_url['data']['data']['file_id']
})
```
### Collections
#### Initiate Open Banking Collection (EUR/GBP)
```python
collection = blaaiz.collections.initiate({
'method': "open_banking",
'amount': 100.00,
'customer_id': "customer-id",
'wallet_id': "wallet-id",
'phone': "+1234567890" # Optional
})
print(f'Payment URL: {collection["data"]["url"]}')
print(f'Transaction ID: {collection["data"]["transaction_id"]}')
```
#### Initiate Card Collection (NGN/USD)
```python
collection = blaaiz.collections.initiate({
'method': "card",
'amount': 5000,
'customer_id': "customer-id",
'wallet_id': "wallet-id"
})
print(f'Payment URL: {collection["data"]["url"]}')
```
#### Crypto Collection
```python
# Get available networks
networks = blaaiz.collections.get_crypto_networks()
print(f'Available networks: {networks["data"]}')
# Initiate crypto collection
crypto_collection = blaaiz.collections.initiate_crypto({
'amount': 100,
'network': "ethereum",
'token': "USDT",
'wallet_id': "wallet-id"
})
```
#### Attach Customer to Collection
```python
attachment = blaaiz.collections.attach_customer({
'customer_id': "customer-id",
'transaction_id': "transaction-id"
})
```
### Payouts
#### Bank Transfer Payout
```python
payout = blaaiz.payouts.initiate({
'wallet_id': "wallet-id",
'customer_id': "customer-id",
'method': "bank_transfer",
'from_amount': 1000,
'from_currency_id': "1", # NGN
'to_currency_id': "1", # NGN
'account_number': "0123456789",
'bank_id': "1",
'phone_number': "+2348012345678"
})
print(f'Payout Status: {payout["data"]["transaction"]["status"]}')
```
#### Interac Payout (CAD)
```python
interac_payout = blaaiz.payouts.initiate({
'wallet_id': "wallet-id",
'customer_id': "customer-id",
'method': "interac",
'from_amount': 100,
'from_currency_id': "2", # CAD
'to_currency_id': "2", # CAD
'email': "recipient@example.com",
'interac_first_name': "John",
'interac_last_name': "Doe"
})
```
### Virtual Bank Accounts
#### Create Virtual Bank Account
```python
vba = blaaiz.virtual_bank_accounts.create({
'wallet_id': "wallet-id",
'account_name': "John Doe"
})
print(f'Account Number: {vba["data"]["account_number"]}')
print(f'Bank Name: {vba["data"]["bank_name"]}')
```
#### List Virtual Bank Accounts
```python
vbas = blaaiz.virtual_bank_accounts.list("wallet-id")
print(f'Virtual Accounts: {vbas["data"]}')
```
### Wallets
#### List All Wallets
```python
wallets = blaaiz.wallets.list()
print(f'Wallets: {wallets["data"]}')
```
#### Get Specific Wallet
```python
wallet = blaaiz.wallets.get("wallet-id")
print(f'Wallet Balance: {wallet["data"]["balance"]}')
```
### Transactions
#### List Transactions
```python
transactions = blaaiz.transactions.list({
'page': 1,
'limit': 10,
'status': "SUCCESSFUL" # Optional filter
})
print(f'Transactions: {transactions["data"]}')
```
#### Get Transaction Details
```python
transaction = blaaiz.transactions.get("transaction-id")
print(f'Transaction: {transaction["data"]}')
```
### Banks & Currencies
#### List Banks
```python
banks = blaaiz.banks.list()
print(f'Available Banks: {banks["data"]}')
```
#### Bank Account Lookup
```python
account_info = blaaiz.banks.lookup_account({
'account_number': "0123456789",
'bank_id': "1"
})
print(f'Account Name: {account_info["data"]["account_name"]}')
```
#### List Currencies
```python
currencies = blaaiz.currencies.list()
print(f'Supported Currencies: {currencies["data"]}')
```
### Fees
#### Get Fee Breakdown
```python
fee_breakdown = blaaiz.fees.get_breakdown({
'from_currency_id': "1", # NGN
'to_currency_id': "2", # CAD
'from_amount': 100000
})
print(f'You send: {fee_breakdown["data"]["you_send"]}')
print(f'Recipient gets: {fee_breakdown["data"]["recipient_gets"]}')
print(f'Total fees: {fee_breakdown["data"]["total_fees"]}')
```
### Webhooks
#### Register Webhooks
```python
webhook = blaaiz.webhooks.register({
'collection_url': "https://your-domain.com/webhooks/collection",
'payout_url': "https://your-domain.com/webhooks/payout"
})
```
#### Get Webhook Configuration
```python
webhook_config = blaaiz.webhooks.get()
print(f'Webhook URLs: {webhook_config["data"]}')
```
#### Replay Webhook
```python
replay = blaaiz.webhooks.replay({
'transaction_id': "transaction-id"
})
```
## Advanced Usage
### Complete Payout Workflow
```python
complete_payout_result = blaaiz.create_complete_payout({
'customer_data': {
'first_name': "John",
'last_name': "Doe",
'type': "individual",
'email': "john@example.com",
'country': "NG",
'id_type': "passport",
'id_number': "A12345678"
},
'payout_data': {
'wallet_id': "wallet-id",
'method': "bank_transfer",
'from_amount': 1000,
'from_currency_id': "1",
'to_currency_id': "1",
'account_number': "0123456789",
'bank_id': "1",
'phone_number': "+2348012345678"
}
})
print(f'Customer ID: {complete_payout_result["customer_id"]}')
print(f'Payout: {complete_payout_result["payout"]}')
print(f'Fees: {complete_payout_result["fees"]}')
```
### Complete Collection Workflow
```python
complete_collection_result = blaaiz.create_complete_collection({
'customer_data': {
'first_name': "Jane",
'last_name': "Smith",
'type': "individual",
'email': "jane@example.com",
'country': "NG",
'id_type': "drivers_license",
'id_number': "ABC123456"
},
'collection_data': {
'method': "card",
'amount': 5000,
'wallet_id': "wallet-id"
},
'create_vba': True # Optionally create a virtual bank account
})
print(f'Customer ID: {complete_collection_result["customer_id"]}')
print(f'Collection: {complete_collection_result["collection"]}')
print(f'Virtual Account: {complete_collection_result["virtual_account"]}')
```
### Context Manager Support
```python
with Blaaiz('your-api-key') as blaaiz:
customers = blaaiz.customers.list()
print(f'Total customers: {len(customers["data"])}')
```
## Error Handling
The SDK uses a custom `BlaaizError` class that provides detailed error information:
```python
from blaaiz import Blaaiz, BlaaizError
try:
blaaiz = Blaaiz('your-api-key')
customer = blaaiz.customers.create(invalid_data)
except BlaaizError as e:
print(f'Blaaiz API Error: {e.message}')
print(f'Status Code: {e.status}')
print(f'Error Code: {e.code}')
except Exception as e:
print(f'Unexpected Error: {str(e)}')
```
## Webhook Handling
### Webhook Signature Verification
The SDK provides built-in webhook signature verification:
```python
from blaaiz import Blaaiz
blaaiz = Blaaiz('your-api-key')
# Method 1: Verify signature manually
is_valid = blaaiz.webhooks.verify_signature(
payload, # Raw webhook payload (string or dict)
signature, # Signature from webhook headers
webhook_secret # Your webhook secret key
)
if is_valid:
print('Webhook signature is valid')
else:
print('Invalid webhook signature')
# Method 2: Construct verified event (recommended)
try:
event = blaaiz.webhooks.construct_event(
payload, # Raw webhook payload
signature, # Signature from webhook headers
webhook_secret # Your webhook secret key
)
print(f'Verified event: {event}')
# event['verified'] will be True
# event['timestamp'] will contain verification timestamp
except ValueError as e:
print(f'Webhook verification failed: {str(e)}')
```
### Flask Webhook Handler Example
```python
from flask import Flask, request, jsonify
from blaaiz import Blaaiz
import os
app = Flask(__name__)
blaaiz = Blaaiz(os.getenv('BLAAIZ_API_KEY'))
# Webhook secret (get this from your Blaaiz dashboard)
WEBHOOK_SECRET = os.getenv('BLAAIZ_WEBHOOK_SECRET')
@app.route('/webhooks/collection', methods=['POST'])
def handle_collection_webhook():
signature = request.headers.get('x-blaaiz-signature')
payload = request.get_data(as_text=True)
try:
# Verify webhook signature and construct event
event = blaaiz.webhooks.construct_event(payload, signature, WEBHOOK_SECRET)
print(f'Verified collection event: {event}')
# Process the collection
# Update your database, send notifications, etc.
return jsonify({'received': True}), 200
except ValueError as e:
print(f'Webhook verification failed: {str(e)}')
return jsonify({'error': 'Invalid signature'}), 400
@app.route('/webhooks/payout', methods=['POST'])
def handle_payout_webhook():
signature = request.headers.get('x-blaaiz-signature')
payload = request.get_data(as_text=True)
try:
# Verify webhook signature and construct event
event = blaaiz.webhooks.construct_event(payload, signature, WEBHOOK_SECRET)
print(f'Verified payout event: {event}')
# Process the payout completion
# Update your database, send notifications, etc.
return jsonify({'received': True}), 200
except ValueError as e:
print(f'Webhook verification failed: {str(e)}')
return jsonify({'error': 'Invalid signature'}), 400
if __name__ == '__main__':
app.run(debug=True)
```
## Environment Configuration
```python
# Development
blaaiz_dev = Blaaiz('dev-api-key', base_url='https://api-dev.blaaiz.com')
# Production (when available)
blaaiz_prod = Blaaiz('prod-api-key', base_url='https://api.blaaiz.com')
```
## Best Practices
1. **Always validate customer data before creating customers**
2. **Use the fees API to calculate and display fees to users**
3. **Always verify webhook signatures using the SDK's built-in methods**
4. **Store customer IDs and transaction IDs for tracking**
5. **Handle rate limiting gracefully with exponential backoff**
6. **Use environment variables for API keys and webhook secrets**
7. **Implement proper error handling and logging**
8. **Test webhook endpoints thoroughly with signature verification**
9. **Use the context manager for automatic resource cleanup**
10. **Return appropriate HTTP status codes from webhook handlers**
## Development
To set up the development environment:
```bash
# Clone the repository
git clone https://github.com/blaaiz/blaaiz-python-sdk.git
cd blaaiz-python-sdk
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
flake8 blaaiz/
black blaaiz/
# Run type checking
mypy blaaiz/
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For support and additional documentation:
- Email: onboarding@blaaiz.com
- Documentation: https://docs.business.blaaiz.com
- Issues: https://github.com/blaaiz/blaaiz-python-sdk/issues
## Changelog
### 1.0.0
- Initial release
- Support for all Blaaiz API endpoints
- Comprehensive error handling
- Webhook signature verification
- File upload functionality
- Complete workflow helpers
- Context manager support
Raw data
{
"_id": null,
"home_page": "https://github.com/blaaiz/blaaiz-python-sdk",
"name": "blaaiz-python-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "blaaiz, remittance, payment, fintech, api, sdk",
"author": "Blaaiz Team",
"author_email": "Blaaiz Team <onboarding@blaaiz.com>",
"download_url": "https://files.pythonhosted.org/packages/e9/5d/90ee4a3c5aae4ff1de05d6813a1a652d9623ca44d88b55f9088f8b419caf/blaaiz_python_sdk-1.0.5.tar.gz",
"platform": null,
"description": "# Blaaiz Python SDK\n\nA comprehensive Python SDK for the Blaaiz RaaS (Remittance as a Service) API. This SDK provides easy-to-use methods for payment processing, collections, payouts, customer management, and more.\n\n## Installation\n\n```bash\npip install blaaiz-python-sdk\n```\n\n## Quick Start\n\n```python\nfrom blaaiz import Blaaiz\n\n# Initialize the SDK\nblaaiz = Blaaiz('your-api-key-here', base_url='https://api-dev.blaaiz.com')\n\n# Test the connection\nis_connected = blaaiz.test_connection()\nprint(f'API Connected: {is_connected}')\n```\n\n## Features\n\n- **Customer Management**: Create, update, and manage customers with KYC verification\n- **Collections**: Support for multiple collection methods (Open Banking, Card, Crypto, Bank Transfer)\n- **Payouts**: Bank transfers and Interac payouts across multiple currencies\n- **Virtual Bank Accounts**: Create and manage virtual accounts for NGN collections\n- **Wallets**: Multi-currency wallet management\n- **Transactions**: Transaction history and status tracking\n- **Webhooks**: Webhook configuration and management with signature verification\n- **Files**: Document upload with pre-signed URLs\n- **Fees**: Real-time fee calculations and breakdowns\n- **Banks & Currencies**: Access to supported banks and currencies\n\n## Supported Currencies & Methods\n\n### Collections\n- **CAD**: Interac (push mechanism)\n- **NGN**: Bank Transfer (VBA) and Card Payment\n- **USD**: Card Payment\n- **EUR/GBP**: Open Banking\n\n### Payouts\n- **Bank Transfer**: All supported currencies\n- **Interac**: CAD transactions\n\n## API Reference\n\n### Customer Management\n\n#### Create a Customer\n\n```python\ncustomer = blaaiz.customers.create({\n 'first_name': \"John\",\n 'last_name': \"Doe\",\n 'type': \"individual\", # or \"business\"\n 'email': \"john.doe@example.com\",\n 'country': \"NG\",\n 'id_type': \"passport\", # drivers_license, passport, id_card, resident_permit\n 'id_number': \"A12345678\",\n # 'business_name': \"Company Name\" # Required if type is \"business\"\n})\n\nprint(f'Customer ID: {customer[\"data\"][\"data\"][\"id\"]}')\n```\n\n#### Get Customer\n\n```python\ncustomer = blaaiz.customers.get('customer-id')\nprint(f'Customer: {customer[\"data\"]}')\n```\n\n#### List All Customers\n\n```python\ncustomers = blaaiz.customers.list()\nprint(f'Customers: {customers[\"data\"]}')\n```\n\n#### Update Customer\n\n```python\nupdated_customer = blaaiz.customers.update('customer-id', {\n 'first_name': \"Jane\",\n 'email': \"jane.doe@example.com\"\n})\n```\n\n### File Management & KYC\n\n#### Upload Customer Documents\n\n**Method 1: Complete File Upload (Recommended)**\n```python\n# Option A: Upload from bytes\nwith open('passport.jpg', 'rb') as f:\n file_data = f.read()\n\nresult = blaaiz.customers.upload_file_complete('customer-id', {\n 'file': file_data,\n 'file_category': 'identity', # identity, proof_of_address, liveness_check\n 'filename': 'passport.jpg',\n 'content_type': 'image/jpeg'\n})\n\n# Option B: Upload from Base64 string\nresult = blaaiz.customers.upload_file_complete('customer-id', {\n 'file': 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',\n 'file_category': 'identity'\n})\n\n# Option C: Upload from Data URL\nresult = blaaiz.customers.upload_file_complete('customer-id', {\n 'file': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',\n 'file_category': 'identity'\n})\n\n# Option D: Upload from Public URL\nresult = blaaiz.customers.upload_file_complete('customer-id', {\n 'file': 'https://example.com/documents/passport.jpg',\n 'file_category': 'identity'\n})\n\nprint(f'Upload complete: {result[\"data\"]}')\nprint(f'File ID: {result[\"file_id\"]}')\n```\n\n**Method 2: Manual 3-Step Process**\n```python\n# Step 1: Get pre-signed URL\npresigned_url = blaaiz.files.get_presigned_url({\n 'customer_id': 'customer-id',\n 'file_category': 'identity'\n})\n\n# Step 2: Upload file to the pre-signed URL (implement your file upload logic)\n# Step 3: Associate file with customer\nfile_association = blaaiz.customers.upload_files('customer-id', {\n 'id_file': presigned_url['data']['data']['file_id']\n})\n```\n\n### Collections\n\n#### Initiate Open Banking Collection (EUR/GBP)\n\n```python\ncollection = blaaiz.collections.initiate({\n 'method': \"open_banking\",\n 'amount': 100.00,\n 'customer_id': \"customer-id\",\n 'wallet_id': \"wallet-id\",\n 'phone': \"+1234567890\" # Optional\n})\n\nprint(f'Payment URL: {collection[\"data\"][\"url\"]}')\nprint(f'Transaction ID: {collection[\"data\"][\"transaction_id\"]}')\n```\n\n#### Initiate Card Collection (NGN/USD)\n\n```python\ncollection = blaaiz.collections.initiate({\n 'method': \"card\",\n 'amount': 5000,\n 'customer_id': \"customer-id\",\n 'wallet_id': \"wallet-id\"\n})\n\nprint(f'Payment URL: {collection[\"data\"][\"url\"]}')\n```\n\n#### Crypto Collection\n\n```python\n# Get available networks\nnetworks = blaaiz.collections.get_crypto_networks()\nprint(f'Available networks: {networks[\"data\"]}')\n\n# Initiate crypto collection\ncrypto_collection = blaaiz.collections.initiate_crypto({\n 'amount': 100,\n 'network': \"ethereum\",\n 'token': \"USDT\",\n 'wallet_id': \"wallet-id\"\n})\n```\n\n#### Attach Customer to Collection\n\n```python\nattachment = blaaiz.collections.attach_customer({\n 'customer_id': \"customer-id\",\n 'transaction_id': \"transaction-id\"\n})\n```\n\n### Payouts\n\n#### Bank Transfer Payout\n\n```python\npayout = blaaiz.payouts.initiate({\n 'wallet_id': \"wallet-id\",\n 'customer_id': \"customer-id\",\n 'method': \"bank_transfer\",\n 'from_amount': 1000,\n 'from_currency_id': \"1\", # NGN\n 'to_currency_id': \"1\", # NGN\n 'account_number': \"0123456789\",\n 'bank_id': \"1\",\n 'phone_number': \"+2348012345678\"\n})\n\nprint(f'Payout Status: {payout[\"data\"][\"transaction\"][\"status\"]}')\n```\n\n#### Interac Payout (CAD)\n\n```python\ninterac_payout = blaaiz.payouts.initiate({\n 'wallet_id': \"wallet-id\",\n 'customer_id': \"customer-id\",\n 'method': \"interac\",\n 'from_amount': 100,\n 'from_currency_id': \"2\", # CAD\n 'to_currency_id': \"2\", # CAD\n 'email': \"recipient@example.com\",\n 'interac_first_name': \"John\",\n 'interac_last_name': \"Doe\"\n})\n```\n\n### Virtual Bank Accounts\n\n#### Create Virtual Bank Account\n\n```python\nvba = blaaiz.virtual_bank_accounts.create({\n 'wallet_id': \"wallet-id\",\n 'account_name': \"John Doe\"\n})\n\nprint(f'Account Number: {vba[\"data\"][\"account_number\"]}')\nprint(f'Bank Name: {vba[\"data\"][\"bank_name\"]}')\n```\n\n#### List Virtual Bank Accounts\n\n```python\nvbas = blaaiz.virtual_bank_accounts.list(\"wallet-id\")\nprint(f'Virtual Accounts: {vbas[\"data\"]}')\n```\n\n### Wallets\n\n#### List All Wallets\n\n```python\nwallets = blaaiz.wallets.list()\nprint(f'Wallets: {wallets[\"data\"]}')\n```\n\n#### Get Specific Wallet\n\n```python\nwallet = blaaiz.wallets.get(\"wallet-id\")\nprint(f'Wallet Balance: {wallet[\"data\"][\"balance\"]}')\n```\n\n### Transactions\n\n#### List Transactions\n\n```python\ntransactions = blaaiz.transactions.list({\n 'page': 1,\n 'limit': 10,\n 'status': \"SUCCESSFUL\" # Optional filter\n})\n\nprint(f'Transactions: {transactions[\"data\"]}')\n```\n\n#### Get Transaction Details\n\n```python\ntransaction = blaaiz.transactions.get(\"transaction-id\")\nprint(f'Transaction: {transaction[\"data\"]}')\n```\n\n### Banks & Currencies\n\n#### List Banks\n\n```python\nbanks = blaaiz.banks.list()\nprint(f'Available Banks: {banks[\"data\"]}')\n```\n\n#### Bank Account Lookup\n\n```python\naccount_info = blaaiz.banks.lookup_account({\n 'account_number': \"0123456789\",\n 'bank_id': \"1\"\n})\n\nprint(f'Account Name: {account_info[\"data\"][\"account_name\"]}')\n```\n\n#### List Currencies\n\n```python\ncurrencies = blaaiz.currencies.list()\nprint(f'Supported Currencies: {currencies[\"data\"]}')\n```\n\n### Fees\n\n#### Get Fee Breakdown\n\n```python\nfee_breakdown = blaaiz.fees.get_breakdown({\n 'from_currency_id': \"1\", # NGN\n 'to_currency_id': \"2\", # CAD\n 'from_amount': 100000\n})\n\nprint(f'You send: {fee_breakdown[\"data\"][\"you_send\"]}')\nprint(f'Recipient gets: {fee_breakdown[\"data\"][\"recipient_gets\"]}')\nprint(f'Total fees: {fee_breakdown[\"data\"][\"total_fees\"]}')\n```\n\n### Webhooks\n\n#### Register Webhooks\n\n```python\nwebhook = blaaiz.webhooks.register({\n 'collection_url': \"https://your-domain.com/webhooks/collection\",\n 'payout_url': \"https://your-domain.com/webhooks/payout\"\n})\n```\n\n#### Get Webhook Configuration\n\n```python\nwebhook_config = blaaiz.webhooks.get()\nprint(f'Webhook URLs: {webhook_config[\"data\"]}')\n```\n\n#### Replay Webhook\n\n```python\nreplay = blaaiz.webhooks.replay({\n 'transaction_id': \"transaction-id\"\n})\n```\n\n## Advanced Usage\n\n### Complete Payout Workflow\n\n```python\ncomplete_payout_result = blaaiz.create_complete_payout({\n 'customer_data': {\n 'first_name': \"John\",\n 'last_name': \"Doe\",\n 'type': \"individual\",\n 'email': \"john@example.com\",\n 'country': \"NG\",\n 'id_type': \"passport\",\n 'id_number': \"A12345678\"\n },\n 'payout_data': {\n 'wallet_id': \"wallet-id\",\n 'method': \"bank_transfer\",\n 'from_amount': 1000,\n 'from_currency_id': \"1\",\n 'to_currency_id': \"1\",\n 'account_number': \"0123456789\",\n 'bank_id': \"1\",\n 'phone_number': \"+2348012345678\"\n }\n})\n\nprint(f'Customer ID: {complete_payout_result[\"customer_id\"]}')\nprint(f'Payout: {complete_payout_result[\"payout\"]}')\nprint(f'Fees: {complete_payout_result[\"fees\"]}')\n```\n\n### Complete Collection Workflow\n\n```python\ncomplete_collection_result = blaaiz.create_complete_collection({\n 'customer_data': {\n 'first_name': \"Jane\",\n 'last_name': \"Smith\",\n 'type': \"individual\",\n 'email': \"jane@example.com\",\n 'country': \"NG\",\n 'id_type': \"drivers_license\",\n 'id_number': \"ABC123456\"\n },\n 'collection_data': {\n 'method': \"card\",\n 'amount': 5000,\n 'wallet_id': \"wallet-id\"\n },\n 'create_vba': True # Optionally create a virtual bank account\n})\n\nprint(f'Customer ID: {complete_collection_result[\"customer_id\"]}')\nprint(f'Collection: {complete_collection_result[\"collection\"]}')\nprint(f'Virtual Account: {complete_collection_result[\"virtual_account\"]}')\n```\n\n### Context Manager Support\n\n```python\nwith Blaaiz('your-api-key') as blaaiz:\n customers = blaaiz.customers.list()\n print(f'Total customers: {len(customers[\"data\"])}')\n```\n\n## Error Handling\n\nThe SDK uses a custom `BlaaizError` class that provides detailed error information:\n\n```python\nfrom blaaiz import Blaaiz, BlaaizError\n\ntry:\n blaaiz = Blaaiz('your-api-key')\n customer = blaaiz.customers.create(invalid_data)\nexcept BlaaizError as e:\n print(f'Blaaiz API Error: {e.message}')\n print(f'Status Code: {e.status}')\n print(f'Error Code: {e.code}')\nexcept Exception as e:\n print(f'Unexpected Error: {str(e)}')\n```\n\n## Webhook Handling\n\n### Webhook Signature Verification\n\nThe SDK provides built-in webhook signature verification:\n\n```python\nfrom blaaiz import Blaaiz\n\nblaaiz = Blaaiz('your-api-key')\n\n# Method 1: Verify signature manually\nis_valid = blaaiz.webhooks.verify_signature(\n payload, # Raw webhook payload (string or dict)\n signature, # Signature from webhook headers\n webhook_secret # Your webhook secret key\n)\n\nif is_valid:\n print('Webhook signature is valid')\nelse:\n print('Invalid webhook signature')\n\n# Method 2: Construct verified event (recommended)\ntry:\n event = blaaiz.webhooks.construct_event(\n payload, # Raw webhook payload\n signature, # Signature from webhook headers \n webhook_secret # Your webhook secret key\n )\n \n print(f'Verified event: {event}')\n # event['verified'] will be True\n # event['timestamp'] will contain verification timestamp\nexcept ValueError as e:\n print(f'Webhook verification failed: {str(e)}')\n```\n\n### Flask Webhook Handler Example\n\n```python\nfrom flask import Flask, request, jsonify\nfrom blaaiz import Blaaiz\nimport os\n\napp = Flask(__name__)\nblaaiz = Blaaiz(os.getenv('BLAAIZ_API_KEY'))\n\n# Webhook secret (get this from your Blaaiz dashboard)\nWEBHOOK_SECRET = os.getenv('BLAAIZ_WEBHOOK_SECRET')\n\n@app.route('/webhooks/collection', methods=['POST'])\ndef handle_collection_webhook():\n signature = request.headers.get('x-blaaiz-signature')\n payload = request.get_data(as_text=True)\n \n try:\n # Verify webhook signature and construct event\n event = blaaiz.webhooks.construct_event(payload, signature, WEBHOOK_SECRET)\n \n print(f'Verified collection event: {event}')\n \n # Process the collection\n # Update your database, send notifications, etc.\n \n return jsonify({'received': True}), 200\n \n except ValueError as e:\n print(f'Webhook verification failed: {str(e)}')\n return jsonify({'error': 'Invalid signature'}), 400\n\n@app.route('/webhooks/payout', methods=['POST'])\ndef handle_payout_webhook():\n signature = request.headers.get('x-blaaiz-signature')\n payload = request.get_data(as_text=True)\n \n try:\n # Verify webhook signature and construct event\n event = blaaiz.webhooks.construct_event(payload, signature, WEBHOOK_SECRET)\n \n print(f'Verified payout event: {event}')\n \n # Process the payout completion\n # Update your database, send notifications, etc.\n \n return jsonify({'received': True}), 200\n \n except ValueError as e:\n print(f'Webhook verification failed: {str(e)}')\n return jsonify({'error': 'Invalid signature'}), 400\n\nif __name__ == '__main__':\n app.run(debug=True)\n```\n\n## Environment Configuration\n\n```python\n# Development\nblaaiz_dev = Blaaiz('dev-api-key', base_url='https://api-dev.blaaiz.com')\n\n# Production (when available)\nblaaiz_prod = Blaaiz('prod-api-key', base_url='https://api.blaaiz.com')\n```\n\n## Best Practices\n\n1. **Always validate customer data before creating customers**\n2. **Use the fees API to calculate and display fees to users**\n3. **Always verify webhook signatures using the SDK's built-in methods**\n4. **Store customer IDs and transaction IDs for tracking**\n5. **Handle rate limiting gracefully with exponential backoff**\n6. **Use environment variables for API keys and webhook secrets**\n7. **Implement proper error handling and logging**\n8. **Test webhook endpoints thoroughly with signature verification**\n9. **Use the context manager for automatic resource cleanup**\n10. **Return appropriate HTTP status codes from webhook handlers**\n\n## Development\n\nTo set up the development environment:\n\n```bash\n# Clone the repository\ngit clone https://github.com/blaaiz/blaaiz-python-sdk.git\ncd blaaiz-python-sdk\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run linting\nflake8 blaaiz/\nblack blaaiz/\n\n# Run type checking\nmypy blaaiz/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor support and additional documentation:\n- Email: onboarding@blaaiz.com\n- Documentation: https://docs.business.blaaiz.com\n- Issues: https://github.com/blaaiz/blaaiz-python-sdk/issues\n\n## Changelog\n\n### 1.0.0\n- Initial release\n- Support for all Blaaiz API endpoints\n- Comprehensive error handling\n- Webhook signature verification\n- File upload functionality\n- Complete workflow helpers\n- Context manager support\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive Python SDK for the Blaaiz RaaS (Remittance as a Service) API",
"version": "1.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/blaaiz/blaaiz-python-sdk/issues",
"Documentation": "https://docs.business.blaaiz.com",
"Homepage": "https://github.com/blaaiz/blaaiz-python-sdk",
"Repository": "https://github.com/blaaiz/blaaiz-python-sdk"
},
"split_keywords": [
"blaaiz",
" remittance",
" payment",
" fintech",
" api",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5099816ba7a6d06ef25cde48b862c2e3557c079566b776eb18a3735ef432513c",
"md5": "a39dabbcef0da736b26d7ad776ddf9d0",
"sha256": "15d3a229bfd2ab2fbf0ce57a9e85e2384b805df3808bcac48a2eb646297067f2"
},
"downloads": -1,
"filename": "blaaiz_python_sdk-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a39dabbcef0da736b26d7ad776ddf9d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21477,
"upload_time": "2025-07-18T18:35:17",
"upload_time_iso_8601": "2025-07-18T18:35:17.786638Z",
"url": "https://files.pythonhosted.org/packages/50/99/816ba7a6d06ef25cde48b862c2e3557c079566b776eb18a3735ef432513c/blaaiz_python_sdk-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e95d90ee4a3c5aae4ff1de05d6813a1a652d9623ca44d88b55f9088f8b419caf",
"md5": "1ee403eeceb2f7b964c291c72d203f25",
"sha256": "aa12018924c933a460505caa6bcfdb4926823a2f657436a18f9b131de0400bf3"
},
"downloads": -1,
"filename": "blaaiz_python_sdk-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "1ee403eeceb2f7b964c291c72d203f25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39614,
"upload_time": "2025-07-18T18:35:18",
"upload_time_iso_8601": "2025-07-18T18:35:18.630169Z",
"url": "https://files.pythonhosted.org/packages/e9/5d/90ee4a3c5aae4ff1de05d6813a1a652d9623ca44d88b55f9088f8b419caf/blaaiz_python_sdk-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 18:35:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "blaaiz",
"github_project": "blaaiz-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "blaaiz-python-sdk"
}
JSON
