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.

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.

The SDK does not request the signa-id:release scope by default. To call the signaId() release methods, set the OAuth scope to signa-id:release, preferably on a dedicated credential. See Signa ID release.

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()
• signaId()

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')
);

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, web SDK access tokens, reading captured applicant data and documents, and Signa ID release. To link an approved Signa session to a customer, see Verify a customer with a Signa session.

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