> ## 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.
# Java SDK
> Complete reference for the Bila Java SDK with all available methods and examples
## Overview
The Bila Java SDK provides convenient access to the Bila REST API from applications written in Java.
Fluent builders for every request param and client configuration option.
Synchronous client by default, with an async variant for non-blocking calls.
Access to all Bila API features: Accounts, Transfers, Collections, and more.
Consistently structured and always up-to-date with the latest API changes.
## Installation
```gradle theme={null}
implementation("com.usebila.sdk:bila-java:0.1.0")
```
```xml theme={null}
com.usebila.sdk
bila-java
0.1.0
```
## Quick Start
```java theme={null}
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:
| 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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
String bankReference = "transfer-001";
TransferGetStatusByReferenceResponse status =
client.transfers().getStatusByReference(bankReference);
System.out.println(status);
```
Returns: `TransferGetStatusByReferenceResponse`
**`client.transfers().initiateBankTransfer(params)`**
Initiate a bank transfer.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
WebhookListResponse webhooks = client.webhooks().list();
System.out.println(webhooks);
```
Returns: `WebhookListResponse`
**`client.webhooks().deactivate(id)`**
Deactivate a webhook.
```java theme={null}
BilaResponse deactivated = client.webhooks().deactivate(webhookId);
System.out.println(deactivated);
```
Returns: `BilaResponse`
**`client.webhooks().getDeliveries(id, params)`**
Get delivery history for a specific webhook.
```java theme={null}
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.
```java theme={null}
WebhookListEventsResponse events = client.webhooks().listEvents();
System.out.println(events);
```
Returns: `WebhookListEventsResponse`
**`client.webhooks().rotateSecret(id)`**
Rotate the signing secret for a webhook.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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.
```java theme={null}
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`.
```java theme={null}
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
Configure your API key via the `BILA_API_KEY` environment variable rather than hardcoding it in your builder calls.
Create a single `BilaClient` instance per application and reuse it across requests; the underlying HTTP client manages connection pooling.
Catch `BilaServiceException` separately from generic exceptions to distinguish API errors from network or serialization failures.
## Next Steps
Complete integration guide with examples
Learn about initiating transfers
Set up webhook notifications
Complete REST API documentation