Skip to main content

​
Overview

The Bila Java SDK provides convenient access to the Bila REST API from applications written in Java.

Builder Pattern

Fluent builders for every request param and client configuration option.

Sync & Async

Synchronous client by default, with an async variant for non-blocking calls.

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

implementation("com.usebila.sdk:bila-java:0.1.0")

​
Quick Start

import com.usebila.sdk.client.BilaClient;
import com.usebila.sdk.client.okhttp.BilaOkHttpClient;
import com.usebila.sdk.models.accounts.AccountListPage;
import com.usebila.sdk.models.accounts.AccountListParams;
 
BilaClient client = BilaOkHttpClient.builder()
    .apiKey("My API Key") // defaults to System.getenv("BILA_API_KEY")
    .environment(BilaClient.Environment.SANDBOX) // defaults to PRODUCTION
    .build();
 
AccountListPage accounts = client.accounts().list(AccountListParams.builder().build());

​
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. 
String accountId = "68f11209-451f-4a15-bfcd-d916eb8b09f4";
 
AccountRetrieveResponse account = client.accounts().retrieve(accountId);
System.out.println(account);
Returns: AccountRetrieveResponse client.accounts().list(params) List all accounts associated with your profile. 
AccountListParams params = AccountListParams.builder()
    .page(1)
    .perPage(50)
    .build();
 
AccountListPage accounts = client.accounts().list(params);
System.out.println(accounts);
Returns: AccountListPage client.accounts().getBalance(id) Check the real-time balance of an account. 
AccountGetBalanceResponse balance = client.accounts().getBalance(accountId);
System.out.println(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. 
String transferRecipientId = "68f11209-451f-4a15-bfcd-d916eb8b09f4";
 
TransferRecipientRetrieveResponse recipient = client.transferRecipients().retrieve(transferRecipientId);
System.out.println(recipient);
Returns: TransferRecipientRetrieveResponse client.transferRecipients().list(params) List all transfer recipients. 
TransferRecipientListParams params = TransferRecipientListParams.builder()
    .page(1)
    .perPage(50)
    .build();
 
TransferRecipientListPage recipients = client.transferRecipients().list(params);
System.out.println(recipients);
Returns: TransferRecipientListPage client.transferRecipients().createBankAccount(params) Create a new bank account transfer recipient. 
TransferRecipientCreateBankAccountParams params = TransferRecipientCreateBankAccountParams.builder()
    .accountNumber("1234567890")
    .bankId("bank-001")
    .country("zm")
    .name("John Doe")
    .build();
 
TransferRecipientCreateBankAccountResponse bankRecipient =
    client.transferRecipients().createBankAccount(params);
System.out.println(bankRecipient);
Returns: TransferRecipientCreateBankAccountResponse client.transferRecipients().createMobileMoney(params) Create a new mobile money transfer recipient. 
TransferRecipientCreateMobileMoneyParams params = TransferRecipientCreateMobileMoneyParams.builder()
    .phone("0977433571")
    .operator_("airtel")
    .country("zm")
    .name("Jane Doe")
    .build();
 
TransferRecipientCreateMobileMoneyResponse mobileRecipient =
    client.transferRecipients().createMobileMoney(params);
System.out.println(mobileRecipient);
Returns: TransferRecipientCreateMobileMoneyResponse

​
Transfers

Send funds to bank accounts or mobile money wallets.

​
Methods

client.transfers().retrieve(id) Retrieve details for a specific transfer. 
String transferId = "68f11209-451f-4a15-bfcd-d916eb8b09f4";
 
TransferRetrieveResponse transfer = client.transfers().retrieve(transferId);
System.out.println(transfer);
Returns: TransferRetrieveResponse client.transfers().list(params) List all transfers. 
TransferListParams params = TransferListParams.builder()
    .accountId("68f11209-451f-4a15-bfcd-d916eb8b09f4")
    .startDate("2024-01-01T00:00:00Z")
    .endDate("2024-12-31T23:59:59Z")
    .page(1)
    .perPage(50)
    .status(TransferListParams.Status.PENDING)
    .type_(TransferListParams.Type.BANK_ACCOUNT)
    .build();
 
TransferListPage transfers = client.transfers().list(params);
System.out.println(transfers);
Returns: TransferListPage client.transfers().getStatusByReference(reference) Get the status of a transfer by its reference. 
String bankReference = "transfer-001";
 
TransferGetStatusByReferenceResponse status =
    client.transfers().getStatusByReference(bankReference);
System.out.println(status);
Returns: TransferGetStatusByReferenceResponse client.transfers().initiateBankTransfer(params) Initiate a bank transfer. 
TransferInitiateBankTransferParams params = TransferInitiateBankTransferParams.builder()
    .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")
    .build();
 
TransferInitiateBankTransferResponse bankTransfer =
    client.transfers().initiateBankTransfer(params);
System.out.println(bankTransfer);
Returns: TransferInitiateBankTransferResponse client.transfers().initiateMobileMoneyTransfer(params) Initiate a mobile money transfer. 
TransferInitiateMobileMoneyTransferParams params = TransferInitiateMobileMoneyTransferParams.builder()
    .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")
    .build();
 
TransferInitiateMobileMoneyTransferResponse mobileTransfer =
    client.transfers().initiateMobileMoneyTransfer(params);
System.out.println(mobileTransfer);
Returns: TransferInitiateMobileMoneyTransferResponse

​
Collections

Accept mobile money payments from customers.

​
Methods

client.collections().retrieve(id) Retrieve details for a specific collection. 
String collectionId = "68f11209-451f-4a15-bfcd-d916eb8b09f4";
 
CollectionRetrieveResponse collection = client.collections().retrieve(collectionId);
System.out.println(collection);
Returns: CollectionRetrieveResponse client.collections().list(params) List all collections. 
CollectionListParams params = CollectionListParams.builder()
    .accountId("68f11209-451f-4a15-bfcd-d916eb8b09f4")
    .startDate("2024-01-01T00:00:00Z")
    .endDate("2024-12-31T23:59:59Z")
    .page(1)
    .perPage(50)
    .status(CollectionListParams.Status.PENDING)
    .build();
 
CollectionListPage collections = client.collections().list(params);
System.out.println(collections);
Returns: CollectionListPage client.collections().getStatusByReference(reference) Get the status of a collection by its reference. 
String reference = "collection-001";
 
CollectionGetStatusByReferenceResponse status =
    client.collections().getStatusByReference(reference);
System.out.println(status);
Returns: CollectionGetStatusByReferenceResponse client.collections().initiateMobileMoneyCollection(params) Initiate a mobile money collection. 
CollectionInitiateMobileMoneyCollectionParams params =
    CollectionInitiateMobileMoneyCollectionParams.builder()
        .amount(100.5)
        .country("zm")
        .operator_("airtel")
        .phone("0977433571")
        .reference("collection-001")
        .walletId("68f11209-451f-4a15-bfcd-d916eb8b09f4")
        .bearer(CollectionInitiateMobileMoneyCollectionParams.Bearer.CUSTOMER)
        .customerName("John Doe")
        .narration("Payment for subscription")
        .build();
 
CollectionInitiateMobileMoneyCollectionResponse initiated =
    client.collections().initiateMobileMoneyCollection(params);
System.out.println(initiated);
Returns: CollectionInitiateMobileMoneyCollectionResponse

​
Transactions

View and manage transaction history.

​
Methods

client.transactions().retrieve(id) Retrieve details for a specific transaction. 
String transactionId = "68f11209-451f-4a15-bfcd-d916eb8b09f4";
 
TransactionRetrieveResponse transaction = client.transactions().retrieve(transactionId);
System.out.println(transaction);
Returns: TransactionRetrieveResponse client.transactions().list(params) List all transactions. 
TransactionListParams params = TransactionListParams.builder()
    .page(1)
    .perPage(50)
    .build();
 
TransactionListPage transactions = client.transactions().list(params);
System.out.println(transactions);
Returns: TransactionListPage

​
Webhooks

Configure endpoints to receive real-time event notifications.

​
Methods

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

​
Banks

Utilities for listing supported financial institutions.

​
Methods

client.banks().list(params) List supported banks for a specific country. 
BankListParams params = BankListParams.builder()
    .country("zm")
    .build();
 
BankListResponse banks = client.banks().list(params);
System.out.println(banks);
Returns: BankListResponse

​
Resolve

Utilities for verifying account details.

​
Methods

client.resolve().bankAccount(params) Verify the owner of a bank account. 
ResolveBankAccountParams params = ResolveBankAccountParams.builder()
    .accountNumber("1234567890")
    .bankId("bank-001")
    .build();
 
ResolveBankAccountResponse resolution = client.resolve().bankAccount(params);
System.out.println(resolution);
Returns: ResolveBankAccountResponse client.resolve().mobileMoney(params) Verify mobile money details. 
ResolveMobileMoneyParams params = ResolveMobileMoneyParams.builder()
    .phone("0977433571")
    .operator_("airtel")
    .country("zm")
    .build();
 
ResolveMobileMoneyResponse resolution = client.resolve().mobileMoney(params);
System.out.println(resolution);
Returns: ResolveMobileMoneyResponse

​
Error Handling

The SDK throws a BilaServiceException for non-success API responses and BilaIoException for network-level failures. Both extend BilaException. 
import com.usebila.sdk.errors.BilaServiceException;
 
try {
    client.accounts().retrieve("invalid-id");
} catch (BilaServiceException e) {
    System.err.println("Status: " + e.statusCode());
    System.err.println("Body: " + e.body());
} catch (Exception e) {
    System.err.println("Unexpected error: " + e.getMessage());
}

​
Best Practices

1

Use Environment Variables

Configure your API key via the BILA_API_KEY environment variable rather than hardcoding it in your builder calls.
2

Reuse the Client

Create a single BilaClient instance per application and reuse it across requests; the underlying HTTP client manages connection pooling.
3

Handle Errors Gracefully

Catch BilaServiceException separately from generic exceptions to distinguish API errors from network or serialization failures.

​
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