TypeScript SDK - Bila API Documentation

The Bila TypeScript SDK provides a fully typed client library for integrating Bila’s payment infrastructure into your server-side applications.

Type-safe — Full TypeScript support with comprehensive request and response types
Promise-based — Modern async/await API for clean, readable code
Comprehensive — Covers Accounts, Transfers, Collections, Webhooks, and more
Always up-to-date — Consistently structured and aligned with the latest API

Installation

npm install @usebila/sdk

Initialisation

import Bila from '@usebila/sdk';

const client = new Bila({
  apiKey: process.env.BILA_API_KEY,
  environment: 'sandbox', // or 'production'
});

Important: Never hardcode your API key. Always use environment variables or a secure secrets manager.

Accounts

Manage your Bila wallets and check balances. Types: BilaResponse · AccountRetrieveResponse · AccountListResponse · AccountGetBalanceResponse

Retrieve an account

const account: Bila.AccountRetrieveResponse = await client.accounts.retrieve('ACCOUNT_ID');

List all accounts

const accounts: Bila.AccountListResponse = await client.accounts.list({
  page: 1,
  perPage: 50,
});

Get account balance

const balance: Bila.AccountGetBalanceResponse = await client.accounts.getBalance('ACCOUNT_ID');

Transfer recipients

Manage payout recipients for bank and mobile money transfers. Types: TransferRecipientRetrieveResponse · TransferRecipientListResponse · TransferRecipientCreateBankAccountResponse · TransferRecipientCreateMobileMoneyResponse

Retrieve a recipient

const recipient: Bila.TransferRecipientRetrieveResponse = await client.transferRecipients.retrieve('RECIPIENT_ID');

List all recipients

const recipients: Bila.TransferRecipientListResponse = await client.transferRecipients.list({
  page: 1,
  perPage: 50,
});

Create a bank account recipient

const recipient: Bila.TransferRecipientCreateBankAccountResponse = await client.transferRecipients.createBankAccount({
  accountNumber: '1234567890',
  bankId: 'bank-001',
  country: 'zm',
  name: 'John Doe',
});

Create a mobile money recipient

const recipient: Bila.TransferRecipientCreateMobileMoneyResponse = await client.transferRecipients.createMobileMoney({
  phone: '0977433571',
  operator: 'airtel',
  country: 'zm',
  name: 'Jane Doe',
});

Transfers (Payouts)

Send funds to bank accounts or mobile money wallets. Types: TransferRetrieveResponse · TransferListResponse · TransferGetStatusByReferenceResponse · TransferInitiateBankTransferResponse · TransferInitiateMobileMoneyTransferResponse

Retrieve a transfer

const transfer: Bila.TransferRetrieveResponse = await client.transfers.retrieve('TRANSFER_ID');

List all transfers

const transfers: Bila.TransferListResponse = await client.transfers.list({
  accountId: 'ACCOUNT_ID',
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-12-31T23:59:59Z',
  status: 'pending',
  type: 'bank-account',
  page: 1,
  perPage: 50,
});

Get transfer status by reference

const status: Bila.TransferGetStatusByReferenceResponse = await client.transfers.getStatusByReference('transfer-001');

Initiate a bank transfer

const transfer: Bila.TransferInitiateBankTransferResponse = await client.transfers.initiateBankTransfer({
  accountId: 'ACCOUNT_ID',
  amount: 1000,
  reference: 'transfer-001',
  accountNumber: '1234567890',
  bankId: 'bank-001',
  country: 'zm',
  narration: 'Payment for services',
  recipientName: 'Jane Doe',
  transferRecipientId: 'RECIPIENT_ID',
  walletId: 'WALLET_ID',
});

Initiate a mobile money transfer

const transfer: Bila.TransferInitiateMobileMoneyTransferResponse = await client.transfers.initiateMobileMoneyTransfer({
  amount: 250,
  country: 'zm',
  operator: 'airtel',
  phone: '0977433571',
  reference: 'mobile-transfer-001',
  narration: 'Mobile money payout',
  recipientName: 'Jane Doe',
  walletId: 'WALLET_ID',
});

Collections

Accept mobile money payments from customers. Types: CollectionRetrieveResponse · CollectionListResponse · CollectionGetStatusByReferenceResponse · CollectionInitiateMobileMoneyCollectionResponse

Retrieve a collection

const collection: Bila.CollectionRetrieveResponse = await client.collections.retrieve('COLLECTION_ID');

List all collections

const collections: Bila.CollectionListResponse = await client.collections.list({
  accountId: 'ACCOUNT_ID',
  startDate: '2024-01-01T00:00:00Z',
  endDate: '2024-12-31T23:59:59Z',
  status: 'pending',
  page: 1,
  perPage: 50,
});

Get collection status by reference

const status: Bila.CollectionGetStatusByReferenceResponse = await client.collections.getStatusByReference('collection-001');

Initiate a mobile money collection

const collection: Bila.CollectionInitiateMobileMoneyCollectionResponse = await client.collections.initiateMobileMoneyCollection({
  amount: 100.5,
  country: 'zm',
  operator: 'airtel',
  phone: '0977433571',
  reference: 'collection-001',
  walletId: 'WALLET_ID',
  bearer: 'customer',
  customerName: 'John Doe',
  narration: 'Payment for subscription',
});

Transactions

View and manage transaction history. Types: TransactionRetrieveResponse · TransactionListResponse

Retrieve a transaction

const transaction: Bila.TransactionRetrieveResponse = await client.transactions.retrieve('TRANSACTION_ID');

List all transactions

const transactions: Bila.TransactionListResponse = await client.transactions.list({
  page: 1,
  perPage: 50,
});

Webhooks

Configure endpoints to receive real-time event notifications. Types: WebhookCreateResponse · WebhookUpdateResponse · WebhookListResponse · WebhookGetDeliveriesResponse · WebhookListEventsResponse · WebhookRotateSecretResponse

Register a webhook

const webhook: Bila.WebhookCreateResponse = await client.webhooks.create({
  events: ['payment.completed', 'withdrawal.completed', 'transfer.completed'],
  url: 'https://example.com/webhooks',
});

Update a webhook

const webhook: Bila.WebhookUpdateResponse = await client.webhooks.update('WEBHOOK_ID', {
  events: ['payment.completed', 'transfer.failed'],
  url: 'https://example.com/webhooks/v2',
  isActive: true,
});

List all webhooks

const webhooks: Bila.WebhookListResponse = await client.webhooks.list();

Deactivate a webhook

await client.webhooks.deactivate('WEBHOOK_ID');

Get webhook delivery history

const deliveries: Bila.WebhookGetDeliveriesResponse = await client.webhooks.getDeliveries('WEBHOOK_ID', {
  startDate: '2026-04-01T00:00:00.000Z',
  endDate: '2026-04-30T23:59:59.999Z',
  eventType: 'payment.completed',
  status: 'DELIVERED',
  page: 1,
  perPage: 20,
});

List supported webhook events

const events: Bila.WebhookListEventsResponse = await client.webhooks.listEvents();

Rotate webhook secret

const rotated: Bila.WebhookRotateSecretResponse = await client.webhooks.rotateSecret('WEBHOOK_ID');

Banks

List supported financial institutions. Types: BankListResponse

List banks by country

const banks: Bila.BankListResponse = await client.banks.list({ country: 'zm' });

Resolve

Verify account details before initiating transfers. Types: ResolveBankAccountResponse · ResolveMobileMoneyResponse

Verify a bank account

const resolution: Bila.ResolveBankAccountResponse = await client.resolve.bankAccount({
  accountNumber: '1234567890',
  bankId: 'bank-001',
});

Verify mobile money details

const resolution: Bila.ResolveMobileMoneyResponse = await client.resolve.mobileMoney({
  phone: '0977433571',
  operator: 'airtel',
  country: 'zm',
});

Type definitions

All request and response types are available via the Bila namespace.

import Bila from '@usebila/sdk';

const params: Bila.TransferInitiateBankTransferParams = {
  accountId: 'ACCOUNT_ID',
  amount: 1000,
  reference: 'transfer-001',
  accountNumber: '1234567890',
  bankId: 'bank-001',
  country: 'zm',
  narration: 'Payment for services',
  recipientName: 'Jane Doe',
  transferRecipientId: 'RECIPIENT_ID',
  walletId: 'WALLET_ID',
};

const response: Bila.TransferInitiateBankTransferResponse = await client.transfers.initiateBankTransfer(params);

Error handling

All SDK methods return a promise. Use try/catch to handle errors.

Property	Description
`status`	HTTP status code e.g. 400, 401, 422, 500
`message`	Human-readable error message
`type`	The specific error type from the API

try {
  await client.accounts.list();
} catch (error) {
  if (error instanceof Bila.BilaError) {
    console.error(`Status: ${error.status}`);
    console.error(`Message: ${error.message}`);
  } else {
    console.error('An unexpected error occurred:', error);
  }
}

​Installation

​Initialisation

​Accounts

​Retrieve an account

​List all accounts

​Get account balance

​Transfer recipients

​Retrieve a recipient

​List all recipients

​Create a bank account recipient

​Create a mobile money recipient

​Transfers (Payouts)

​Retrieve a transfer

​List all transfers

​Get transfer status by reference

​Initiate a bank transfer

​Initiate a mobile money transfer

​Collections

​Retrieve a collection

​List all collections

​Get collection status by reference

​Initiate a mobile money collection

​Transactions

​Retrieve a transaction

​List all transactions

​Webhooks

​Register a webhook

​Update a webhook

​List all webhooks

​Deactivate a webhook

​Get webhook delivery history

​List supported webhook events

​Rotate webhook secret

​Banks

​List banks by country

​Resolve

​Verify a bank account

​Verify mobile money details

​Type definitions

​Error handling