Skip to main content

​
Overview

The Bila Go library provides convenient access to the Bila REST API from applications written in Go.

Idiomatic Go

Functional options pattern and context-aware methods throughout.

Strongly Typed

Typed request params and response structs for every endpoint.

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

go get -u 'github.com/bilasdk/go@v0.1.0'
This library requires Go 1.22+.

​
Quick Start

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:
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.Get(ctx, id) Retrieve details for a specific account. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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. 
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). 
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

1

Use Environment Variables

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.
2

Always Pass a Context

Use context.Context to control timeouts and cancellation on every request, especially for long-running batch operations.
3

Handle Errors with errors.As

Use the errors.As pattern to unwrap *bila.Error and inspect the status code and response body for failed requests.
4

Reuse the Client

Create a single bila.NewClient() instance and reuse it across requests rather than creating a new client per call.

​
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