> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# PHP SDK
> Complete reference for the Bila PHP SDK with all available methods and examples
## Overview
The Bila PHP library provides convenient access to the Bila REST API from applications written in PHP.
Built for PHP 8.0+, taking advantage of named arguments for better IDE autocomplete and type safety.
Generated model classes for every request and response shape.
Access to all Bila API features: Accounts, Transfers, Collections, and more.
Consistently structured and always up-to-date with the latest API changes.
## Installation
```bash theme={null}
composer require usebila/sdk
```
This library requires PHP 8.1+.
## Quick Start
```php theme={null}
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:
| Resource | Description |
| ----------------------------------------- | ------------------------------------------------------------ |
| [Accounts](#accounts) | Retrieve accounts, list accounts, and check balances |
| [TransferRecipients](#transferrecipients) | Manage payout recipients for bank and mobile money transfers |
| [Transfers](#transfers) | Send payouts via bank transfer and mobile money |
| [Collections](#collections) | Collect payments via mobile money |
| [Transactions](#transactions) | Retrieve and list transaction history |
| [Webhooks](#webhooks) | Configure webhooks and manage delivery history |
| [Banks](#banks) | List supported banks and financial institutions |
| [Resolve](#resolve) | Verify 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.
```php theme={null}
$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.
```php theme={null}
$accounts = $client->accounts->list(
page: 1,
perPage: 50,
);
echo $accounts;
```
Returns: `AccountListResponse`
**`$client->accounts->getBalance($id)`**
Check the real-time balance of an account.
```php theme={null}
$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.
```php theme={null}
$transferRecipientId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
$recipient = $client->transferRecipients->retrieve($transferRecipientId);
echo $recipient;
```
Returns: `TransferRecipientRetrieveResponse`
**`$client->transferRecipients->list(...)`**
List all transfer recipients.
```php theme={null}
$recipients = $client->transferRecipients->list(
page: 1,
perPage: 50,
);
echo $recipients;
```
Returns: `TransferRecipientListResponse`
**`$client->transferRecipients->createBankAccount(...)`**
Create a new bank account transfer recipient.
```php theme={null}
$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.
```php theme={null}
$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.
```php theme={null}
$transferId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
$transfer = $client->transfers->retrieve($transferId);
echo $transfer;
```
Returns: `TransferRetrieveResponse`
**`$client->transfers->list(...)`**
List all transfers.
```php theme={null}
$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.
```php theme={null}
$bankReference = 'transfer-001';
$status = $client->transfers->getStatusByReference($bankReference);
echo $status;
```
Returns: `TransferGetStatusByReferenceResponse`
**`$client->transfers->initiateBankTransfer(...)`**
Initiate a bank transfer.
```php theme={null}
$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.
```php theme={null}
$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.
```php theme={null}
$collectionId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
$collection = $client->collections->retrieve($collectionId);
echo $collection;
```
Returns: `CollectionRetrieveResponse`
**`$client->collections->list(...)`**
List all collections.
```php theme={null}
$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.
```php theme={null}
$reference = 'collection-001';
$status = $client->collections->getStatusByReference($reference);
echo $status;
```
Returns: `CollectionGetStatusByReferenceResponse`
**`$client->collections->initiateMobileMoneyCollection(...)`**
Initiate a mobile money collection.
```php theme={null}
$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.
```php theme={null}
$transactionId = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
$transaction = $client->transactions->retrieve($transactionId);
echo $transaction;
```
Returns: `TransactionRetrieveResponse`
**`$client->transactions->list(...)`**
List all transactions.
```php theme={null}
$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.
```php theme={null}
$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.
```php theme={null}
$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.
```php theme={null}
$webhooks = $client->webhooks->list();
echo $webhooks;
```
Returns: `WebhookListResponse`
**`$client->webhooks->deactivate($id)`**
Deactivate a webhook.
```php theme={null}
$deactivated = $client->webhooks->deactivate($webhookId);
echo $deactivated;
```
Returns: `WebhookDeactivateResponse`
**`$client->webhooks->getDeliveries($id, ...)`**
Get delivery history for a specific webhook.
```php theme={null}
$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.
```php theme={null}
$events = $client->webhooks->listEvents();
echo $events;
```
Returns: `WebhookListEventsResponse`
**`$client->webhooks->rotateSecret($id)`**
Rotate the signing secret for a webhook.
```php theme={null}
$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.
```php theme={null}
$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.
```php theme={null}
$resolution = $client->resolve->bankAccount(
accountNumber: '1234567890',
bankId: 'bank-001',
);
echo $resolution;
```
Returns: `ResolveBankAccountResponse`
**`$client->resolve->mobileMoney(...)`**
Verify mobile money details.
```php theme={null}
$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.
```php theme={null}
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
Store your API key in an environment variable and read it with `getenv('BILA_API_KEY')` rather than hardcoding it in source.
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.
Instantiate a single `Bila\Client` instance per request lifecycle and reuse it across calls.
Catch `APIStatusException` separately from generic exceptions to distinguish API-level errors from connectivity issues.
## Next Steps
Complete integration guide with examples
Learn about initiating transfers
Set up webhook notifications
Complete REST API documentation