> ## 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.
# Go SDK
> Complete reference for the Bila Go SDK with all available methods and examples
## Overview
The Bila Go library provides convenient access to the Bila REST API from applications written in Go.
Functional options pattern and context-aware methods throughout.
Typed request params and response structs for every endpoint.
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}
go get -u 'github.com/bilasdk/go@v0.1.0'
```
This library requires Go 1.22+.
## Quick Start
```go theme={null}
package main
import (
"context"
"fmt"
"github.com/bilasdk/go"
"github.com/bilasdk/go/option"
)
func main() {
client := bila.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("BILA_API_KEY")
option.WithEnvironmentSandbox(), // defaults to option.WithEnvironmentProduction()
)
accounts, err := client.Accounts.List(context.TODO(), bila.AccountListParams{})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", accounts.Message)
}
```
## 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.Get(ctx, id)`**
Retrieve details for a specific account.
```go theme={null}
accountID := "68f11209-451f-4a15-bfcd-d916eb8b09f4"
account, err := client.Accounts.Get(context.TODO(), accountID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", account)
```
Returns: `*bila.AccountRetrieveResponse`
**`client.Accounts.List(ctx, params)`**
List all accounts associated with your profile.
```go theme={null}
listParams := bila.AccountListParams{
Page: bila.Float(1),
PerPage: bila.Float(50),
}
accounts, err := client.Accounts.List(context.TODO(), listParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", accounts)
```
Returns: `*bila.AccountListResponse`
**`client.Accounts.GetBalance(ctx, id)`**
Check the real-time balance of an account.
```go theme={null}
balance, err := client.Accounts.GetBalance(context.TODO(), accountID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", balance)
```
Returns: `*bila.AccountGetBalanceResponse`
## TransferRecipients
Manage payout recipients for bank and mobile money transfers.
### Methods
**`client.TransferRecipients.Get(ctx, id)`**
Retrieve details for a specific transfer recipient.
```go theme={null}
transferRecipientID := "68f11209-451f-4a15-bfcd-d916eb8b09f4"
recipient, err := client.TransferRecipients.Get(context.TODO(), transferRecipientID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", recipient)
```
Returns: `*bila.TransferRecipientRetrieveResponse`
**`client.TransferRecipients.List(ctx, params)`**
List all transfer recipients.
```go theme={null}
listParams := bila.TransferRecipientListParams{
Page: bila.Float(1),
PerPage: bila.Float(50),
}
recipients, err := client.TransferRecipients.List(context.TODO(), listParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", recipients)
```
Returns: `*bila.TransferRecipientListResponse`
**`client.TransferRecipients.NewBankAccount(ctx, params)`**
Create a new bank account transfer recipient.
```go theme={null}
bankParams := bila.TransferRecipientCreateBankAccountParams{
AccountNumber: bila.String("1234567890"),
BankID: bila.String("bank-001"),
Country: bila.String("zm"),
Name: bila.String("John Doe"),
}
bankRecipient, err := client.TransferRecipients.NewBankAccount(context.TODO(), bankParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", bankRecipient)
```
Returns: `*bila.TransferRecipientCreateBankAccountResponse`
**`client.TransferRecipients.NewMobileMoney(ctx, params)`**
Create a new mobile money transfer recipient.
```go theme={null}
mobileParams := bila.TransferRecipientCreateMobileMoneyParams{
Phone: bila.String("0977433571"),
Operator: bila.String("airtel"),
Country: bila.String("zm"),
Name: bila.String("Jane Doe"),
}
mobileRecipient, err := client.TransferRecipients.NewMobileMoney(context.TODO(), mobileParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", mobileRecipient)
```
Returns: `*bila.TransferRecipientCreateMobileMoneyResponse`
## Transfers
Send funds to bank accounts or mobile money wallets.
### Methods
**`client.Transfers.Get(ctx, id)`**
Retrieve details for a specific transfer.
```go theme={null}
transferID := "68f11209-451f-4a15-bfcd-d916eb8b09f4"
transfer, err := client.Transfers.Get(context.TODO(), transferID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", transfer)
```
Returns: `*bila.TransferRetrieveResponse`
**`client.Transfers.List(ctx, params)`**
List all transfers.
```go theme={null}
listParams := bila.TransferListParams{
AccountID: bila.String("68f11209-451f-4a15-bfcd-d916eb8b09f4"),
StartDate: bila.String("2024-01-01T00:00:00Z"),
EndDate: bila.String("2024-12-31T23:59:59Z"),
Page: bila.Float(1),
PerPage: bila.Float(50),
Status: bila.TransferListParamsStatusPending,
Type: bila.TransferListParamsTypeBankAccount,
}
transfers, err := client.Transfers.List(context.TODO(), listParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", transfers)
```
Returns: `*bila.TransferListResponse`
**`client.Transfers.GetStatusByReference(ctx, reference)`**
Get the status of a transfer by its reference.
```go theme={null}
bankReference := "transfer-001"
status, err := client.Transfers.GetStatusByReference(context.TODO(), bankReference)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", status)
```
Returns: `*bila.TransferGetStatusByReferenceResponse`
**`client.Transfers.NewBankTransfer(ctx, params)`**
Initiate a bank transfer.
```go theme={null}
bankParams := bila.TransferInitiateBankTransferParams{
AccountID: bila.String("68f11209-451f-4a15-bfcd-d916eb8b09f4"),
Amount: bila.Float(1000),
Reference: bila.String("transfer-001"),
AccountNumber: bila.String("1234567890"),
BankID: bila.String("bank-001"),
Country: bila.String("zm"),
Narration: bila.String("Payment for services"),
RecipientName: bila.String("Jane Doe"),
TransferRecipientID: bila.String("68f11209-451f-4a15-bfcd-d916eb8b09f4"),
WalletID: bila.String("68f11209-451f-4a15-bfcd-d916eb8b09f4"),
}
bankTransfer, err := client.Transfers.NewBankTransfer(context.TODO(), bankParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", bankTransfer)
```
Returns: `*bila.TransferInitiateBankTransferResponse`
**`client.Transfers.NewMobileMoneyTransfer(ctx, params)`**
Initiate a mobile money transfer.
```go theme={null}
mobileParams := bila.TransferInitiateMobileMoneyTransferParams{
Amount: bila.Float(250),
Country: bila.String("zm"),
Operator: bila.String("airtel"),
Phone: bila.String("0977433571"),
Reference: bila.String("mobile-transfer-001"),
Narration: bila.String("Mobile money payout"),
RecipientName: bila.String("Jane Doe"),
WalletID: bila.String("68f11209-451f-4a15-bfcd-d916eb8b09f4"),
}
mobileTransfer, err := client.Transfers.NewMobileMoneyTransfer(context.TODO(), mobileParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", mobileTransfer)
```
Returns: `*bila.TransferInitiateMobileMoneyTransferResponse`
## Collections
Accept mobile money payments from customers.
### Methods
**`client.Collections.Get(ctx, id)`**
Retrieve details for a specific collection.
```go theme={null}
collectionID := "68f11209-451f-4a15-bfcd-d916eb8b09f4"
collection, err := client.Collections.Get(context.TODO(), collectionID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", collection)
```
Returns: `*bila.CollectionRetrieveResponse`
**`client.Collections.List(ctx, params)`**
List all collections.
```go theme={null}
listParams := bila.CollectionListParams{
AccountID: bila.String("68f11209-451f-4a15-bfcd-d916eb8b09f4"),
StartDate: bila.String("2024-01-01T00:00:00Z"),
EndDate: bila.String("2024-12-31T23:59:59Z"),
Page: bila.Float(1),
PerPage: bila.Float(50),
Status: bila.CollectionListParamsStatusPending,
}
collections, err := client.Collections.List(context.TODO(), listParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", collections)
```
Returns: `*bila.CollectionListResponse`
**`client.Collections.GetStatusByReference(ctx, reference)`**
Get the status of a collection by its reference.
```go theme={null}
reference := "collection-001"
status, err := client.Collections.GetStatusByReference(context.TODO(), reference)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", status)
```
Returns: `*bila.CollectionGetStatusByReferenceResponse`
**`client.Collections.NewMobileMoneyCollection(ctx, params)`**
Initiate a mobile money collection.
```go theme={null}
initiateParams := bila.CollectionInitiateMobileMoneyCollectionParams{
Amount: bila.Float(100.5),
Country: bila.String("zm"),
Operator: bila.String("airtel"),
Phone: bila.String("0977433571"),
Reference: bila.String("collection-001"),
WalletID: bila.String("68f11209-451f-4a15-bfcd-d916eb8b09f4"),
Bearer: bila.CollectionInitiateMobileMoneyCollectionParamsBearerCustomer,
CustomerName: bila.String("John Doe"),
Narration: bila.String("Payment for subscription"),
}
initiated, err := client.Collections.NewMobileMoneyCollection(context.TODO(), initiateParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", initiated)
```
Returns: `*bila.CollectionInitiateMobileMoneyCollectionResponse`
## Transactions
View and manage transaction history.
### Methods
**`client.Transactions.Get(ctx, id)`**
Retrieve details for a specific transaction.
```go theme={null}
transactionID := "68f11209-451f-4a15-bfcd-d916eb8b09f4"
transaction, err := client.Transactions.Get(context.TODO(), transactionID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", transaction)
```
Returns: `*bila.TransactionRetrieveResponse`
**`client.Transactions.List(ctx, params)`**
List all transactions.
```go theme={null}
listParams := bila.TransactionListParams{
Page: bila.Float(1),
PerPage: bila.Float(50),
}
transactions, err := client.Transactions.List(context.TODO(), listParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", transactions)
```
Returns: `*bila.TransactionListResponse`
## Webhooks
Configure endpoints to receive real-time event notifications.
### Methods
**`client.Webhooks.New(ctx, params)`**
Register a new webhook endpoint.
```go theme={null}
createParams := bila.WebhookCreateParams{
Events: []string{"payment.completed", "withdrawal.completed", "transfer.completed"},
URL: bila.String("https://example.com/webhooks"),
}
webhook, err := client.Webhooks.New(context.TODO(), createParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", webhook)
```
Returns: `*bila.WebhookCreateResponse`
**`client.Webhooks.Update(ctx, id, params)`**
Update an existing webhook.
```go theme={null}
webhookID := "68f11209-451f-4a15-bfcd-d916eb8b09f4"
updateParams := bila.WebhookUpdateParams{
Events: []string{"payment.completed", "collection.completed", "transfer.failed"},
URL: bila.String("https://example.com/webhooks/v2"),
IsActive: bila.Bool(true),
}
updatedWebhook, err := client.Webhooks.Update(context.TODO(), webhookID, updateParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", updatedWebhook)
```
Returns: `*bila.WebhookUpdateResponse`
**`client.Webhooks.List(ctx)`**
List all registered webhooks.
```go theme={null}
webhooks, err := client.Webhooks.List(context.TODO())
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", webhooks)
```
Returns: `*bila.WebhookListResponse`
**`client.Webhooks.Deactivate(ctx, id)`**
Deactivate a webhook.
```go theme={null}
deactivated, err := client.Webhooks.Deactivate(context.TODO(), webhookID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", deactivated)
```
Returns: `*bila.BilaResponse`
**`client.Webhooks.GetDeliveries(ctx, id, params)`**
Get delivery history for a specific webhook.
```go theme={null}
deliveriesParams := bila.WebhookGetDeliveriesParams{
StartDate: bila.String("2026-04-01T00:00:00.000Z"),
EndDate: bila.String("2026-04-30T23:59:59.999Z"),
EventType: bila.String("payment.completed"),
Page: bila.Float(1),
PerPage: bila.Float(20),
Status: bila.WebhookGetDeliveriesParamsStatusDelivered,
}
deliveries, err := client.Webhooks.GetDeliveries(context.TODO(), webhookID, deliveriesParams)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", deliveries)
```
Returns: `*bila.WebhookGetDeliveriesResponse`
**`client.Webhooks.ListEvents(ctx)`**
List all supported webhook events.
```go theme={null}
events, err := client.Webhooks.ListEvents(context.TODO())
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", events)
```
Returns: `*bila.WebhookListEventsResponse`
**`client.Webhooks.RotateSecret(ctx, id)`**
Rotate the signing secret for a webhook.
```go theme={null}
rotated, err := client.Webhooks.RotateSecret(context.TODO(), webhookID)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", rotated)
```
Returns: `*bila.WebhookRotateSecretResponse`
## Banks
Utilities for listing supported financial institutions.
### Methods
**`client.Banks.List(ctx, params)`**
List supported banks for a specific country.
```go theme={null}
banks, err := client.Banks.List(context.TODO(), bila.BankListParams{
Country: bila.String("zm"),
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", banks)
```
Returns: `*bila.BankListResponse`
## Resolve
Utilities for verifying account details.
### Methods
**`client.Resolve.BankAccount(ctx, params)`**
Verify the owner of a bank account.
```go theme={null}
resolution, err := client.Resolve.BankAccount(context.TODO(), bila.ResolveBankAccountParams{
AccountNumber: bila.String("1234567890"),
BankID: bila.String("bank-001"),
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", resolution)
```
Returns: `*bila.ResolveBankAccountResponse`
**`client.Resolve.MobileMoney(ctx, params)`**
Verify mobile money details.
```go theme={null}
resolution, err := client.Resolve.MobileMoney(context.TODO(), bila.ResolveMobileMoneyParams{
Phone: bila.String("0977433571"),
Operator: bila.String("airtel"),
Country: bila.String("zm"),
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", resolution)
```
Returns: `*bila.ResolveMobileMoneyResponse`
## Error Handling
When the API returns a non-success status code, the SDK returns an error of type `*bila.Error`. This contains `StatusCode`, `*http.Request`, and `*http.Response` values, as well as the JSON of the error body.
```go theme={null}
import (
"errors"
)
_, err := client.Accounts.List(context.TODO(), bila.AccountListParams{})
if err != nil {
var apierr *bila.Error
if errors.As(err, &apierr) {
println(string(apierr.DumpRequest(true)))
println(string(apierr.DumpResponse(true)))
}
panic(err.Error()) // GET "/api/v1/bila/accounts": 400 Bad Request { ... }
}
```
## Type Definitions
Request fields use `omitzero` semantics. Required primitive fields are tagged `api:"required"` and always serialized. Optional fields are wrapped in `param.Opt[T]` and set with constructors like `bila.String(string)`, `bila.Float(float64)`, and `bila.Bool(bool)`.
```go theme={null}
p := bila.ExampleParams{
ID: "id_xxx", // required property
Name: bila.String("..."), // optional property
}
```
Response structs use ordinary value types and include a `JSON` field with metadata about each property, including a `.Valid()` method to check if a field is present and non-null.
## Best Practices
Configure your API key via the `BILA_API_KEY` environment variable rather than hardcoding it. `option.WithAPIKey` will use this by default if no key is passed explicitly.
Use `context.Context` to control timeouts and cancellation on every request, especially for long-running batch operations.
Use the `errors.As` pattern to unwrap `*bila.Error` and inspect the status code and response body for failed requests.
Create a single `bila.NewClient()` instance and reuse it across requests rather than creating a new client per call.
## Next Steps
Complete integration guide with examples
Learn about initiating transfers
Set up webhook notifications
Complete REST API documentation