Skip to main content

​
Overview

The Bila PHP library provides convenient access to the Bila REST API from applications written in PHP.

Named Arguments

Built for PHP 8.0+, taking advantage of named arguments for better IDE autocomplete and type safety.

Typed Models

Generated model classes for every request and response shape.

Comprehensive

Access to all Bila API features: Accounts, Transfers, Collections, and more.

Stainless Generated

Consistently structured and always up-to-date with the latest API changes.

​
Installation

composer require usebila/sdk
This library requires PHP 8.1+.

​
Quick Start

<?php
 
use Bila\Client;
 
$client = new Client(
    apiKey: getenv('BILA_API_KEY'), // This is the default and can be omitted
    environment: 'sandbox', // defaults to 'production'
);
 
$accounts = $client->accounts->list();
 
echo $accounts->message;
The SDK uses PHP 8.0+ named arguments throughout, so every call below passes its parameters by name rather than as an array — this gives you better IDE autocomplete and type checking at call sites.

​
API Classes

The SDK is organized into resources, each handling a specific domain:
ResourceDescription
AccountsRetrieve accounts, list accounts, and check balances
TransferRecipientsManage payout recipients for bank and mobile money transfers
TransfersSend payouts via bank transfer and mobile money
CollectionsCollect payments via mobile money
TransactionsRetrieve and list transaction history
WebhooksConfigure webhooks and manage delivery history
BanksList supported banks and financial institutions
ResolveVerify bank account and mobile money details

​
Accounts

Manage your Bila wallets and check balances.

​
Methods

$client->accounts->retrieve($id) Retrieve details for a specific account. 
$accountId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
 
$account = $client->accounts->retrieve($accountId);
echo $account;
Returns: AccountRetrieveResponse $client->accounts->list(...) List all accounts associated with your profile. 
$accounts = $client->accounts->list(
    page: 1,
    perPage: 50,
);
echo $accounts;
Returns: AccountListResponse $client->accounts->getBalance($id) Check the real-time balance of an account. 
$balance = $client->accounts->getBalance($accountId);
echo $balance;
Returns: AccountGetBalanceResponse

​
TransferRecipients

Manage payout recipients for bank and mobile money transfers.

​
Methods

$client->transferRecipients->retrieve($id) Retrieve details for a specific transfer recipient. 
$transferRecipientId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
 
$recipient = $client->transferRecipients->retrieve($transferRecipientId);
echo $recipient;
Returns: TransferRecipientRetrieveResponse $client->transferRecipients->list(...) List all transfer recipients. 
$recipients = $client->transferRecipients->list(
    page: 1,
    perPage: 50,
);
echo $recipients;
Returns: TransferRecipientListResponse $client->transferRecipients->createBankAccount(...) Create a new bank account transfer recipient. 
$bankRecipient = $client->transferRecipients->createBankAccount(
    accountNumber: '1234567890',
    bankId: 'bank-001',
    country: 'zm',
    name: 'John Doe',
);
echo $bankRecipient;
Returns: TransferRecipientCreateBankAccountResponse $client->transferRecipients->createMobileMoney(...) Create a new mobile money transfer recipient. 
$mobileRecipient = $client->transferRecipients->createMobileMoney(
    phone: '0977433571',
    operator: 'airtel',
    country: 'zm',
    name: 'Jane Doe',
);
echo $mobileRecipient;
Returns: TransferRecipientCreateMobileMoneyResponse

​
Transfers

Send funds to bank accounts or mobile money wallets.

​
Methods

$client->transfers->retrieve($id) Retrieve details for a specific transfer. 
$transferId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
 
$transfer = $client->transfers->retrieve($transferId);
echo $transfer;
Returns: TransferRetrieveResponse $client->transfers->list(...) List all transfers. 
$transfers = $client->transfers->list(
    accountId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
    startDate: '2024-01-01T00:00:00Z',
    endDate: '2024-12-31T23:59:59Z',
    page: 1,
    perPage: 50,
    status: 'pending',
    type: 'bank-account',
);
echo $transfers;
Returns: TransferListResponse $client->transfers->getStatusByReference($reference) Get the status of a transfer by its reference. 
$bankReference = 'transfer-001';
 
$status = $client->transfers->getStatusByReference($bankReference);
echo $status;
Returns: TransferGetStatusByReferenceResponse $client->transfers->initiateBankTransfer(...) Initiate a bank transfer. 
$bankTransfer = $client->transfers->initiateBankTransfer(
    accountId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
    amount: 1000,
    reference: 'transfer-001',
    accountNumber: '1234567890',
    bankId: 'bank-001',
    country: 'zm',
    narration: 'Payment for services',
    recipientName: 'Jane Doe',
    transferRecipientId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
    walletId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
);
echo $bankTransfer;
Returns: TransferInitiateBankTransferResponse $client->transfers->initiateMobileMoneyTransfer(...) Initiate a mobile money transfer. 
$mobileTransfer = $client->transfers->initiateMobileMoneyTransfer(
    amount: 250,
    country: 'zm',
    operator: 'airtel',
    phone: '0977433571',
    reference: 'mobile-transfer-001',
    narration: 'Mobile money payout',
    recipientName: 'Jane Doe',
    walletId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
);
echo $mobileTransfer;
Returns: TransferInitiateMobileMoneyTransferResponse

​
Collections

Accept mobile money payments from customers.

​
Methods

$client->collections->retrieve($id) Retrieve details for a specific collection. 
$collectionId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
 
$collection = $client->collections->retrieve($collectionId);
echo $collection;
Returns: CollectionRetrieveResponse $client->collections->list(...) List all collections. 
$collections = $client->collections->list(
    accountId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
    startDate: '2024-01-01T00:00:00Z',
    endDate: '2024-12-31T23:59:59Z',
    page: 1,
    perPage: 50,
    status: 'pending',
);
echo $collections;
Returns: CollectionListResponse $client->collections->getStatusByReference($reference) Get the status of a collection by its reference. 
$reference = 'collection-001';
 
$status = $client->collections->getStatusByReference($reference);
echo $status;
Returns: CollectionGetStatusByReferenceResponse $client->collections->initiateMobileMoneyCollection(...) Initiate a mobile money collection. 
$initiated = $client->collections->initiateMobileMoneyCollection(
    amount: 100.5,
    country: 'zm',
    operator: 'airtel',
    phone: '0977433571',
    reference: 'collection-001',
    walletId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
    bearer: 'customer',
    customerName: 'John Doe',
    narration: 'Payment for subscription',
);
echo $initiated;
Returns: CollectionInitiateMobileMoneyCollectionResponse

​
Transactions

View and manage transaction history.

​
Methods

$client->transactions->retrieve($id) Retrieve details for a specific transaction. 
$transactionId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
 
$transaction = $client->transactions->retrieve($transactionId);
echo $transaction;
Returns: TransactionRetrieveResponse $client->transactions->list(...) List all transactions. 
$transactions = $client->transactions->list(
    page: 1,
    perPage: 50,
);
echo $transactions;
Returns: TransactionListResponse

​
Webhooks

Configure endpoints to receive real-time event notifications.

​
Methods

$client->webhooks->create(...) Register a new webhook endpoint. 
$webhook = $client->webhooks->create(
    events: ['payment.completed', 'withdrawal.completed', 'transfer.completed'],
    url: 'https://example.com/webhooks',
);
echo $webhook;
Returns: WebhookCreateResponse $client->webhooks->update($id, ...) Update an existing webhook. 
$webhookId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
 
$updatedWebhook = $client->webhooks->update(
    $webhookId,
    events: ['payment.completed', 'collection.completed', 'transfer.failed'],
    url: 'https://example.com/webhooks/v2',
    isActive: true,
);
echo $updatedWebhook;
Returns: WebhookUpdateResponse $client->webhooks->list() List all registered webhooks. 
$webhooks = $client->webhooks->list();
echo $webhooks;
Returns: WebhookListResponse $client->webhooks->deactivate($id) Deactivate a webhook. 
$deactivated = $client->webhooks->deactivate($webhookId);
echo $deactivated;
Returns: WebhookDeactivateResponse $client->webhooks->getDeliveries($id, ...) Get delivery history for a specific webhook. 
$deliveries = $client->webhooks->getDeliveries(
    $webhookId,
    startDate: '2026-04-01T00:00:00.000Z',
    endDate: '2026-04-30T23:59:59.999Z',
    eventType: 'payment.completed',
    page: 1,
    perPage: 20,
    status: 'DELIVERED',
);
echo $deliveries;
Returns: WebhookGetDeliveriesResponse $client->webhooks->listEvents() List all supported webhook events. 
$events = $client->webhooks->listEvents();
echo $events;
Returns: WebhookListEventsResponse $client->webhooks->rotateSecret($id) Rotate the signing secret for a webhook. 
$rotated = $client->webhooks->rotateSecret($webhookId);
echo $rotated;
Returns: WebhookRotateSecretResponse

​
Banks

Utilities for listing supported financial institutions.

​
Methods

$client->banks->list(...) List supported banks for a specific country. 
$banks = $client->banks->list(country: 'zm');
echo $banks;
Returns: BankListResponse

​
Resolve

Utilities for verifying account details.

​
Methods

$client->resolve->bankAccount(...) Verify the owner of a bank account. 
$resolution = $client->resolve->bankAccount(
    accountNumber: '1234567890',
    bankId: 'bank-001',
);
echo $resolution;
Returns: ResolveBankAccountResponse $client->resolve->mobileMoney(...) Verify mobile money details. 
$resolution = $client->resolve->mobileMoney(
    phone: '0977433571',
    operator: 'airtel',
    country: 'zm',
);
echo $resolution;
Returns: ResolveMobileMoneyResponse

​
Error Handling

When the library is unable to connect to the API, or the API returns a non-success status code, an exception extending Bila\Exceptions\APIException is thrown. 
use Bila\Exceptions\APIStatusException;
 
try {
    $client->accounts->retrieve('invalid-id');
} catch (APIStatusException $e) {
    echo 'Status: ' . $e->getStatusCode() . PHP_EOL;
    echo 'Message: ' . $e->getMessage() . PHP_EOL;
} catch (\Exception $e) {
    echo 'Unexpected error: ' . $e->getMessage() . PHP_EOL;
}

​
Best Practices

1

Use Environment Variables

Store your API key in an environment variable and read it with getenv('BILA_API_KEY') rather than hardcoding it in source.
2

Use Named Arguments

Pass parameters using named arguments (page: 1, perPage: 50) rather than arrays. This gives you better IDE autocomplete and catches typos at the editor level.
3

Reuse the Client

Instantiate a single Bila\Client instance per request lifecycle and reuse it across calls.
4

Handle Errors Gracefully

Catch APIStatusException separately from generic exceptions to distinguish API-level errors from connectivity issues.

​
Next Steps

SDK Quickstart

Complete integration guide with examples

Transfers

Learn about initiating transfers

Webhooks

Set up webhook notifications

API Reference

Complete REST API documentation