> ## 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.
# TypeScript SDK
> Complete reference for the Bila TypeScript SDK with all available methods and examples
## Overview
The Bila TypeScript SDK provides a complete, type-safe client library for integrating Bila's fintech services into your server-side applications.
Full TypeScript support with comprehensive request and response types.
Modern async/await API for clean, readable integration.
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}
npm install @usebila/sdk
```
## Quick Start
```typescript theme={null}
import Bila from '@usebila/sdk';
const client = new Bila({
apiKey: process.env.BILA_API_KEY ?? 'sk_test_your_api_key_here',
environment: 'sandbox', // either production or sandbox
});
const accounts = await client.accounts.list();
```
## 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.
Types: `BilaResponse`, `AccountRetrieveResponse`, `AccountListResponse`, `AccountGetBalanceResponse`
### Methods
**`client.accounts.retrieve(id)`**
Retrieve details for a specific account.
```typescript theme={null}
const ACCOUNT_ID = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
const account: Bila.AccountRetrieveResponse = await client.accounts.retrieve(ACCOUNT_ID);
console.log('retrieve:', account);
```
Returns: `AccountRetrieveResponse`
**`client.accounts.list(params?)`**
List all accounts associated with your profile.
```typescript theme={null}
const listParams: Bila.AccountListParams = {
page: 1,
perPage: 50,
};
const accounts: Bila.AccountListResponse = await client.accounts.list(listParams);
console.log('list:', accounts);
```
Returns: `AccountListResponse`
**`client.accounts.getBalance(id)`**
Check the real-time balance of an account.
```typescript theme={null}
const balance: Bila.AccountGetBalanceResponse = await client.accounts.getBalance(ACCOUNT_ID);
console.log('getBalance:', balance);
```
Returns: `AccountGetBalanceResponse`
## TransferRecipients
Manage payout recipients for bank and mobile money transfers.
Types: `TransferRecipientRetrieveResponse`, `TransferRecipientListResponse`, `TransferRecipientCreateBankAccountResponse`, `TransferRecipientCreateMobileMoneyResponse`
### Methods
**`client.transferRecipients.retrieve(id)`**
Retrieve details for a specific transfer recipient.
```typescript theme={null}
const TRANSFER_RECIPIENT_ID = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
const recipient: Bila.TransferRecipientRetrieveResponse =
await client.transferRecipients.retrieve(TRANSFER_RECIPIENT_ID);
console.log('retrieve:', recipient);
```
Returns: `TransferRecipientRetrieveResponse`
**`client.transferRecipients.list(params?)`**
List all transfer recipients.
```typescript theme={null}
const listParams: Bila.TransferRecipientListParams = {
page: 1,
perPage: 50,
};
const recipients: Bila.TransferRecipientListResponse =
await client.transferRecipients.list(listParams);
console.log('list:', recipients);
```
Returns: `TransferRecipientListResponse`
**`client.transferRecipients.createBankAccount(params)`**
Create a new bank account transfer recipient.
```typescript theme={null}
const bankRecipient: Bila.TransferRecipientCreateBankAccountResponse =
await client.transferRecipients.createBankAccount({
accountNumber: '1234567890',
bankId: 'bank-001',
country: 'zm',
name: 'John Doe',
});
console.log('createBankAccount:', bankRecipient);
```
Returns: `TransferRecipientCreateBankAccountResponse`
**`client.transferRecipients.createMobileMoney(params)`**
Create a new mobile money transfer recipient.
```typescript theme={null}
const mobileRecipient: Bila.TransferRecipientCreateMobileMoneyResponse =
await client.transferRecipients.createMobileMoney({
phone: '0977433571',
operator: 'airtel',
country: 'zm',
name: 'Jane Doe',
});
console.log('createMobileMoney:', mobileRecipient);
```
Returns: `TransferRecipientCreateMobileMoneyResponse`
## Transfers
Send funds to bank accounts or mobile money wallets.
Types: `TransferRetrieveResponse`, `TransferListResponse`, `TransferGetStatusByReferenceResponse`, `TransferInitiateBankTransferResponse`, `TransferInitiateMobileMoneyTransferResponse`
### Methods
**`client.transfers.retrieve(id)`**
Retrieve details for a specific transfer.
```typescript theme={null}
const TRANSFER_ID = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
const transfer: Bila.TransferRetrieveResponse = await client.transfers.retrieve(TRANSFER_ID);
console.log('retrieve:', transfer);
```
Returns: `TransferRetrieveResponse`
**`client.transfers.list(params?)`**
List all transfers.
```typescript theme={null}
const listParams: Bila.TransferListParams = {
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',
};
const transfers: Bila.TransferListResponse = await client.transfers.list(listParams);
console.log('list:', transfers);
```
Returns: `TransferListResponse`
**`client.transfers.getStatusByReference(reference)`**
Get the status of a transfer by its reference.
```typescript theme={null}
const BANK_REFERENCE = 'transfer-001';
const status: Bila.TransferGetStatusByReferenceResponse =
await client.transfers.getStatusByReference(BANK_REFERENCE);
console.log('getStatusByReference:', status);
```
Returns: `TransferGetStatusByReferenceResponse`
**`client.transfers.initiateBankTransfer(params)`**
Initiate a bank transfer.
```typescript theme={null}
const bankParams: Bila.TransferInitiateBankTransferParams = {
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',
};
const bankTransfer: Bila.TransferInitiateBankTransferResponse =
await client.transfers.initiateBankTransfer(bankParams);
console.log('initiateBankTransfer:', bankTransfer);
```
Returns: `TransferInitiateBankTransferResponse`
**`client.transfers.initiateMobileMoneyTransfer(params)`**
Initiate a mobile money transfer.
```typescript theme={null}
const mobileParams: Bila.TransferInitiateMobileMoneyTransferParams = {
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',
};
const mobileTransfer: Bila.TransferInitiateMobileMoneyTransferResponse =
await client.transfers.initiateMobileMoneyTransfer(mobileParams);
console.log('initiateMobileMoneyTransfer:', mobileTransfer);
```
Returns: `TransferInitiateMobileMoneyTransferResponse`
## Collections
Accept mobile money payments from customers.
Types: `CollectionRetrieveResponse`, `CollectionListResponse`, `CollectionGetStatusByReferenceResponse`, `CollectionInitiateMobileMoneyCollectionResponse`
### Methods
**`client.collections.retrieve(id)`**
Retrieve details for a specific collection.
```typescript theme={null}
const COLLECTION_ID = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
const collection: Bila.CollectionRetrieveResponse = await client.collections.retrieve(COLLECTION_ID);
console.log('retrieve:', collection);
```
Returns: `CollectionRetrieveResponse`
**`client.collections.list(params?)`**
List all collections.
```typescript theme={null}
const listParams: Bila.CollectionListParams = {
accountId: '68f11209-451f-4a15-bfcd-d916eb8b09f4',
startDate: '2024-01-01T00:00:00Z',
endDate: '2024-12-31T23:59:59Z',
page: 1,
perPage: 50,
status: 'pending',
};
const collections: Bila.CollectionListResponse = await client.collections.list(listParams);
console.log('list:', collections);
```
Returns: `CollectionListResponse`
**`client.collections.getStatusByReference(reference)`**
Get the status of a collection by its reference.
```typescript theme={null}
const REFERENCE = 'collection-001';
const status: Bila.CollectionGetStatusByReferenceResponse =
await client.collections.getStatusByReference(REFERENCE);
console.log('getStatusByReference:', status);
```
Returns: `CollectionGetStatusByReferenceResponse`
**`client.collections.initiateMobileMoneyCollection(params)`**
Initiate a mobile money collection.
```typescript theme={null}
const initiateParams: Bila.CollectionInitiateMobileMoneyCollectionParams = {
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',
};
const initiated: Bila.CollectionInitiateMobileMoneyCollectionResponse =
await client.collections.initiateMobileMoneyCollection(initiateParams);
console.log('initiateMobileMoneyCollection:', initiated);
```
Returns: `CollectionInitiateMobileMoneyCollectionResponse`
## Transactions
View and manage transaction history.
Types: `TransactionRetrieveResponse`, `TransactionListResponse`
### Methods
**`client.transactions.retrieve(id)`**
Retrieve details for a specific transaction.
```typescript theme={null}
const TRANSACTION_ID = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
const transaction: Bila.TransactionRetrieveResponse = await client.transactions.retrieve(TRANSACTION_ID);
console.log('retrieve:', transaction);
```
Returns: `TransactionRetrieveResponse`
**`client.transactions.list(params?)`**
List all transactions.
```typescript theme={null}
const listParams: Bila.TransactionListParams = {
page: 1,
perPage: 50,
};
const transactions: Bila.TransactionListResponse = await client.transactions.list(listParams);
console.log('list:', transactions);
```
Returns: `TransactionListResponse`
## Webhooks
Configure endpoints to receive real-time event notifications.
Types: `WebhookCreateResponse`, `WebhookUpdateResponse`, `WebhookListResponse`, `WebhookGetDeliveriesResponse`, `WebhookListEventsResponse`, `WebhookRotateSecretResponse`
### Methods
**`client.webhooks.create(params)`**
Register a new webhook endpoint.
```typescript theme={null}
const createParams: Bila.WebhookCreateParams = {
events: ['payment.completed', 'withdrawal.completed', 'transfer.completed'],
url: 'https://example.com/webhooks',
};
const webhook: Bila.WebhookCreateResponse = await client.webhooks.create(createParams);
console.log('create:', webhook);
```
Returns: `WebhookCreateResponse`
**`client.webhooks.update(id, params)`**
Update an existing webhook.
```typescript theme={null}
const WEBHOOK_ID = '68f11209-451f-4a15-bfcd-d916eb8b09f4';
const updateParams: Bila.WebhookUpdateParams = {
events: ['payment.completed', 'collection.completed', 'transfer.failed'],
url: 'https://example.com/webhooks/v2',
isActive: true,
};
const updatedWebhook: Bila.WebhookUpdateResponse =
await client.webhooks.update(WEBHOOK_ID, updateParams);
console.log('update:', updatedWebhook);
```
Returns: `WebhookUpdateResponse`
**`client.webhooks.list()`**
List all registered webhooks.
```typescript theme={null}
const webhooks: Bila.WebhookListResponse = await client.webhooks.list();
console.log('list:', webhooks);
```
Returns: `WebhookListResponse`
**`client.webhooks.deactivate(id)`**
Deactivate a webhook.
```typescript theme={null}
const deactivated: Bila.BilaResponse = await client.webhooks.deactivate(WEBHOOK_ID);
console.log('deactivate:', deactivated);
```
Returns: `BilaResponse`
**`client.webhooks.getDeliveries(id, params?)`**
Get delivery history for a specific webhook.
```typescript theme={null}
const deliveriesParams: Bila.WebhookGetDeliveriesParams = {
startDate: '2026-04-01T00:00:00.000Z',
endDate: '2026-04-30T23:59:59.999Z',
eventType: 'payment.completed',
page: 1,
perPage: 20,
status: 'DELIVERED',
};
const deliveries: Bila.WebhookGetDeliveriesResponse =
await client.webhooks.getDeliveries(WEBHOOK_ID, deliveriesParams);
console.log('getDeliveries:', deliveries);
```
Returns: `WebhookGetDeliveriesResponse`
**`client.webhooks.listEvents()`**
List all supported webhook events.
```typescript theme={null}
const events: Bila.WebhookListEventsResponse = await client.webhooks.listEvents();
console.log('listEvents:', events);
```
Returns: `WebhookListEventsResponse`
**`client.webhooks.rotateSecret(id)`**
Rotate the signing secret for a webhook.
```typescript theme={null}
const rotated: Bila.WebhookRotateSecretResponse = await client.webhooks.rotateSecret(WEBHOOK_ID);
console.log('rotateSecret:', rotated);
```
Returns: `WebhookRotateSecretResponse`
## Banks
Utilities for listing supported financial institutions.
Types: `BankListResponse`
### Methods
**`client.banks.list(params?)`**
List supported banks for a specific country.
```typescript theme={null}
const banks: Bila.BankListResponse = await client.banks.list({ country: 'zm' });
console.log('list:', banks);
```
Returns: `BankListResponse`
## Resolve
Utilities for verifying account details.
Types: `ResolveBankAccountResponse`, `ResolveMobileMoneyResponse`
### Methods
**`client.resolve.bankAccount(params)`**
Verify the owner of a bank account.
```typescript theme={null}
const resolution: Bila.ResolveBankAccountResponse = await client.resolve.bankAccount({
accountNumber: '1234567890',
bankId: 'bank-001',
});
console.log('bankAccount:', resolution);
```
Returns: `ResolveBankAccountResponse`
**`client.resolve.mobileMoney(params)`**
Verify mobile money details.
```typescript theme={null}
const resolution: Bila.ResolveMobileMoneyResponse = await client.resolve.mobileMoney({
phone: '0977433571',
operator: 'airtel',
country: 'zm',
});
console.log('mobileMoney:', resolution);
```
Returns: `ResolveMobileMoneyResponse`
## Error Handling
When the library is unable to connect to the API, or if the API returns a non-success status code (4xx or 5xx), a subclass of `APIError` is thrown.
```typescript theme={null}
import Bila from '@usebila/sdk';
const client = new Bila({
apiKey: process.env.BILA_API_KEY,
environment: 'sandbox',
});
try {
const account = await client.accounts.retrieve('account-id');
console.log(account);
} catch (err) {
if (err instanceof Bila.APIError) {
console.error(
JSON.stringify(
{
status: err.status,
name: err.name,
message: err.message,
},
null,
2,
),
);
} else {
throw err;
}
}
```
To handle a specific error, check the status code or use `instanceof`:
```typescript theme={null}
} catch (err) {
if (err instanceof Bila.AuthenticationError) {
// 401 — invalid API key
} else if (err instanceof Bila.NotFoundError) {
// 404 — resource not found
} else if (err instanceof Bila.APIError) {
// other API errors
} else {
throw err;
}
}
```
| Status Code | Error Type |
| ----------- | -------------------------- |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| >=500 | `InternalServerError` |
| N/A | `APIConnectionError` |
## Type Definitions
Every API method has typed request params and responses. Types are available on the `Bila` namespace — only one import is needed:
```typescript theme={null}
import Bila from '@usebila/sdk';
// Response type — what the API returns
const accounts: Bila.AccountListResponse = await client.accounts.list();
// Request type — what you send to the API
const params: Bila.CollectionListParams = {
accountId: 'your-wallet-id',
page: 1,
perPage: 50,
};
const collections = await client.collections.list(params);
```
Type names follow a simple pattern:
| Kind | Pattern | Example |
| -------------- | ---------------------------- | ------------------------------- |
| Response | `{Resource}{Action}Response` | `Bila.TransferRetrieveResponse` |
| Request params | `{Resource}{Action}Params` | `Bila.WebhookCreateParams` |
## Best Practices
Always use environment variables or a secrets manager for API credentials. Never commit credentials to version control.
Always verify webhook signatures to ensure events are legitimately from Bila and haven't been tampered with.
Implement proper error handling with retry logic for transient failures (5xx errors, rate limits).
## Next Steps
Complete integration guide with examples
Learn about initiating transfers
Set up webhook notifications
Complete REST API documentation