Skip to main content
Balance accounts on Busha are designed to hold specific currencies, making them a crucial component for managing your multi-currency transactions. This guide will walk you through the process of programmatically creating new balance accounts and retrieving existing ones via the Busha API.
What You’ll Achieve:
  1. Learn how to create a new balance account for a specific currency
  2. Understand how to retrieve a list of all your existing balance accounts
  3. Confirm successful API interactions for managing currency balances

​
Prerequisites

Before you begin, ensure you have:

​
Managing Your Balance Accounts

1

Identify Supported Currencies

Before creating a balance account, you must know which currencies Busha currently supports. This ensures your requests are valid.To find supported currencies:
  • Refer to the Supported Currencies Reference for the most up-to-date list of available currency codes.
  • When presenting a currency options to your customers, ensure you only display those returned by Busha’s API or listed in our documentation to prevent invalid requests.
2

Retrieve All Your Balance Accounts

To view a comprehensive list of all existing balance accounts associated with your business, use a GET request. This is useful for displaying current balances or iterating through available currencies.To retrieve balance accounts:
  1. Open your terminal or command prompt
  2. Use the GET request below, replacing the placeholders:
    • YOUR_BASE_URL: Use your chosen environment’s base URL.
    • {YOUR_SECRET_API_KEY}: Your actual Secret API Key.
$ curl --request GET \
  --url YOUR_BASE_URL/v1/balances \
  --header 'Authorization: Bearer {YOUR_SECRET_API_KEY}' \
  --header 'Content-Type: application/json'
Expected ResponseA successful response will return a JSON object containing an array of all your balance accounts.
{
  "status": "success",
  "message": "Fetched balances successfully",
  "data": [
    {
      "id": "96da4899-ff99-4821-88df-5182b8d37300",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "GHS",
      "name": "Cedi",
      "type": "fiat",
      "available": {
        "amount": "0",
        "currency": "GHS"
      },
      "pending": {
        "amount": "0",
        "currency": "GHS"
      },
      "total": {
        "amount": "0",
        "currency": "GHS"
      }
    },
    {
      "id": "05320e5e-a8ff-48e4-ac0b-23f7b1aa14d7",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "KES",
      "name": "Shilling",
      "type": "fiat",
      "available": {
        "amount": "0",
        "currency": "KES"
      },
      "pending": {
        "amount": "0",
        "currency": "KES"
      },
      "total": {
        "amount": "0",
        "currency": "KES"
      }
    },
    {
      "id": "960ab09d-cd55-4118-8b6e-c12b340efec3",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "NGN",
      "name": "Naira",
      "type": "fiat",
      "available": {
        "amount": "0",
        "currency": "NGN"
      },
      "pending": {
        "amount": "0",
        "currency": "NGN"
      },
      "total": {
        "amount": "0",
        "currency": "NGN"
      }
    },
    {
      "id": "1ebeabb4-6e4f-449f-8c0f-18a9c9d9187a",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "USD",
      "name": "US Dollar",
      "type": "fiat",
      "available": {
        "amount": "0",
        "currency": "USD"
      },
      "pending": {
        "amount": "0",
        "currency": "USD"
      },
      "total": {
        "amount": "0",
        "currency": "USD"
      }
    },
    {
      "id": "bc1dfeae-055e-4d4e-a583-0c8030e5a1cd",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "BTC",
      "name": "Bitcoin",
      "type": "crypto",
      "available": {
        "amount": "0",
        "currency": "BTC"
      },
      "pending": {
        "amount": "0",
        "currency": "BTC"
      },
      "total": {
        "amount": "0",
        "currency": "BTC"
      }
    },
    {
      "id": "b8dbf5e4-4d1f-4489-81fe-2a5e1e9816e1",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "ETH",
      "name": "Ethereum",
      "type": "crypto",
      "available": {
        "amount": "0",
        "currency": "ETH"
      },
      "pending": {
        "amount": "0",
        "currency": "ETH"
      },
      "total": {
        "amount": "0",
        "currency": "ETH"
      }
    },
    {
      "id": "ec5744b6-ab06-4180-b354-e672b9a5f30a",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "USDC",
      "name": "USD Coin",
      "type": "crypto",
      "available": {
        "amount": "0",
        "currency": "USDC"
      },
      "pending": {
        "amount": "0",
        "currency": "USDC"
      },
      "total": {
        "amount": "0",
        "currency": "USDC"
      }
    },
    {
      "id": "fb891621-0b15-45f5-9b81-ea3995cbf891",
      "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "user_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
      "currency": "USDT",
      "name": "USD Token",
      "type": "crypto",
      "available": {
        "amount": "0",
        "currency": "USDT"
      },
      "pending": {
        "amount": "0",
        "currency": "USDT"
      },
      "total": {
        "amount": "0",
        "currency": "USDT"
      }
    }
  ],
  "pagination": {
    "current_entries_size": 8
  }
}

​
Troubleshooting

  • 401 Unauthorized Request: Double-check your API key.

​
What’s Next?

Now that you know how to retrieve balance accounts, you can: