TypeScript SDK - Bila API Documentation

Overview

The Bila TypeScript SDK provides a complete, type-safe client library for integrating Bila’s fintech services 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 integration.

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

npm install @usebila/sdk

Quick Start

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	Retrieve accounts, list accounts, and check balances
TransferRecipients	Manage payout recipients for bank and mobile money transfers
Transfers	Send payouts via bank transfer and mobile money
Collections	Collect payments via mobile money
Transactions	Retrieve and list transaction history
Webhooks	Configure webhooks and manage delivery history
Banks	List supported banks and financial institutions
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

const webhooks: Bila.WebhookListResponse = await client.webhooks.list();
console.log('list:', webhooks);

Returns: WebhookListResponse client.webhooks.deactivate(id) Deactivate a webhook.

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.

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.

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.

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.

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.

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.

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.

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:

} 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:

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

Secure Your Credentials

Always use environment variables or a secrets manager for API credentials. Never commit credentials to version control.

Implement Webhook Signature Verification

Always verify webhook signatures to ensure events are legitimately from Bila and haven’t been tampered with.

Handle Errors Gracefully

Implement proper error handling with retry logic for transient failures (5xx errors, rate limits).

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

​Overview

Type-Safe

Promise-Based

Comprehensive

Stainless Generated

​Installation

​Quick Start

​API Classes

​Accounts

​Methods

​TransferRecipients

​Methods

​Transfers

​Methods

​Collections

​Methods

​Transactions

​Methods

​Webhooks

​Methods

​Banks

​Methods

​Resolve

​Methods

​Error Handling

​Type Definitions

​Best Practices

​Next Steps

SDK Quickstart

Transfers

Webhooks

API Reference

Overview

Installation

Quick Start

API Classes

Accounts

Methods

TransferRecipients

Methods

Transfers

Methods

Collections

Methods

Transactions

Methods

Webhooks

Methods

Banks

Methods

Resolve

Methods

Error Handling

Type Definitions

Best Practices

Next Steps