GuideReference

Manage Balance Accounts

Guide on how to create and manage balance accounts

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

PrerequisitesCopied!

Before you begin, ensure you have:

  • A Busha Business Account and Secret API Key (from the Quick Start Tutorial)

  • An understanding of the API Environments (Sandbox vs. Production) and their respective base URLs (from the Make Your First Request Guide).

Step 1: Identify Supported CurrenciesCopied!

Before creating a balance account, you must know which currencies Busha currently supports. This ensures your requests are valid.

To find supported currencies:

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.

Step 2: Retrieve All Your Balance AccountsCopied!

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:

    1. YOUR_BASE_URL: Use your chosen environment’s base URL.

    2. {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 Response:

A 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?Copied!

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