Blaaiz Laravel SDK

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.

use Blaaiz\LaravelSdk\Facades\Blaaiz;

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

Legacy API key

You can also authenticate with a legacy API key:

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()
• momoOperators()
• currencies()
• fees()
• files()
• webhooks()
• rates()
• swaps()
• refunds()
• signa()

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' => '[email protected]',
    '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' => '[email protected]',
    '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')
);

Create a Signa verification session

$session = Blaaiz::signa()->createSession([
    'customer_reference' => 'customer-123',
    'idempotency_key' => 'signa-request-123',
    'requirements' => ['DOCUMENTS', 'SELFIE', 'FACE_MATCH'],
    'fulfilment_mode' => 'HOSTED',
    'applicant' => [
        'first_name' => 'Ada',
        'last_name' => 'Lovelace',
        'country' => 'GBR',
    ],
]);

$sessionId = $session['data']['data']['id'];

See Signa for the full set of methods: list, get, submit, cancel, document uploads, verification links, and reading captured applicant data and documents.

API Reference

• Root SDK helpers
• Customers
• Collections
• Payouts
• Wallets and virtual bank accounts
• Transactions, banks, currencies, and rates
• Fees and files
• Webhooks
• Swaps
• Refunds
• Signa

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