README

Official Laravel SDK for the Blaaiz RaaS (Remittance as a Service) API.

Installation

composer require blaaiz/blaaiz-laravel-sdk

Laravel package discovery is enabled automatically.

Quick Start

OAuth 2.0

OAuth is recommended for new integrations.

BLAAIZ_CLIENT_ID=your-client-id
BLAAIZ_CLIENT_SECRET=your-client-secret
BLAAIZ_API_URL=https://api-dev.blaaiz.com

use Blaaiz\LaravelSdk\Facades\Blaaiz;

$isConnected = Blaaiz::testConnection();
$currencies = Blaaiz::currencies()->list();

Legacy API key

You can also authenticate with a legacy API key:

BLAAIZ_API_KEY=your-api-key
BLAAIZ_API_URL=https://api-dev.blaaiz.com

use Blaaiz\LaravelSdk\Facades\Blaaiz;

$isConnected = Blaaiz::testConnection();
$wallets = Blaaiz::wallets()->list();

When both OAuth credentials and an API key are configured, OAuth is used.

Publish configuration

php artisan vendor:publish --tag=blaaiz-config

Basic usage with dependency injection

use Blaaiz\LaravelSdk\Blaaiz;

class RatesController
{
    public function __invoke(Blaaiz $blaaiz)
    {
        return response()->json($blaaiz->rates()->list());
    }
}

Configuration

The published config file exposes these options:

return [
    'api_key' => env('BLAAIZ_API_KEY', ''),
    'client_id' => env('BLAAIZ_CLIENT_ID', ''),
    'client_secret' => env('BLAAIZ_CLIENT_SECRET', ''),
    'oauth_scope' => env('BLAAIZ_OAUTH_SCOPE', ''),
    'base_url' => env('BLAAIZ_API_URL', 'https://api-dev.blaaiz.com'),
    'timeout' => env('BLAAIZ_TIMEOUT', 30),
    'webhook_secret' => env('BLAAIZ_WEBHOOK_SECRET', ''),
];

Available Services

customers()
collections()
payouts()
wallets()
virtualBankAccounts()
transactions()
banks()
currencies()
fees()
files()
webhooks()
rates()
swaps()
refunds()

These services are also exposed as public properties on the underlying SDK instance.

Common Examples

Create a customer

use Blaaiz\LaravelSdk\Facades\Blaaiz;

$customer = Blaaiz::customers()->create([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'type' => 'individual',
    'email' => 'john.doe@example.com',
    'country' => 'NG',
    'id_type' => 'passport',
    'id_number' => 'A12345678',
]);

List customers (with optional filters and pagination)

$customers = Blaaiz::customers()->list();

// With filters. Supported keys: email, id_number, registration_number,
// verification_status, type. Set `paginate => true` to receive a paginated
// response that includes `links` and `meta` (current_page, total, ...).
$verified = Blaaiz::customers()->list([
    'email' => 'john@example.com',
    'verification_status' => 'VERIFIED',
    'type' => 'individual',
    'paginate' => true,
]);

Initiate a payout

$payout = Blaaiz::payouts()->initiate([
    'wallet_id' => 'wallet-id',
    'customer_id' => 'customer-id',
    'method' => 'bank_transfer',
    'from_currency_id' => 'USD',
    'to_currency_id' => 'NGN',
    'from_amount' => 100,
    'bank_id' => 'bank-id',
    'account_number' => '0123456789',
    'merchant_reference' => 'order-12345', // optional, unique per business
]);

merchant_reference is an optional string of maximum 255 characters. It also works on collections. The value must be unique for each business. The API returns it on the transaction, transaction list items, and the payout and collection webhooks.

Upload a KYC document

$result = Blaaiz::customers()->uploadFileComplete('customer-id', [
    'file' => storage_path('app/private/passport.pdf'),
    'file_category' => 'identity',
]);

Verify a webhook

$event = Blaaiz::webhooks()->constructEvent(
    $request->getContent(),
    $request->header('X-Blaaiz-Signature', ''),
    $request->header('X-Blaaiz-Timestamp', ''),
    config('blaaiz.webhook_secret')
);

API Reference

Runnable Examples

See examples/README.md for Laravel-oriented example classes and snippets.

High-Level Helpers

The root SDK object includes:

testConnection()
createCompletePayout(array $config)
createCompleteCollection(array $config)

These helpers compose the lower-level services for common workflows.

Error Handling

use Blaaiz\LaravelSdk\Exceptions\BlaaizException;
use Blaaiz\LaravelSdk\Facades\Blaaiz;

try {
    $rates = Blaaiz::rates()->list();
} catch (BlaaizException $e) {
    report($e);

    return response()->json($e->toArray(), $e->getStatus() ?? 500);
}

Development

composer test
composer analyse
composer format

blaaiz / blaaiz-laravel-sdk

Maintainers

Package info

Statistics

Security