Skip to main content
GET
/
v1
/
payout-api
/
payouts
/
wallets
Get wallet balances
curl --request GET \
  --url https://gateway.useyala.com/v1/payout-api/payouts/wallets \
  --header 'x-api-key: <api-key>'
{
  "data": [
    {
      "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "currency": "NGN",
      "balance": 123,
      "availableBalance": 123
    }
  ]
}

​
Overview

Returns all business wallet balances for your account. Use this endpoint to:
  • Display available balances per currency before initiating payouts
  • See which source currencies you can pay out from (e.g. NGN, USD)
  • Check balance sufficiency before calling POST /quote or POST /initiate
Only business wallets are returned (one per currency your business holds).

​
Request

GET /v1/payout-api/payouts/wallets HTTP/1.1
Host: gateway.staging.useyala.com
x-api-key: <YOUR_API_KEY>

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key

​
Response

{
  "data": [
    {
      "walletId": "550e8400-e29b-41d4-a716-446655440000",
      "currency": "NGN",
      "balance": 100000.5,
      "availableBalance": 100000.5
    },
    {
      "walletId": "660e8400-e29b-41d4-a716-446655440001",
      "currency": "USD",
      "balance": 5000.0,
      "availableBalance": 5000.0
    }
  ]
}

​
Response Fields

FieldTypeDescription
dataarrayList of wallet balance objects
data[].walletIdstring (UUID)Wallet identifier
data[].currencystringCurrency code (e.g. NGN, USD)
data[].balancenumberCurrent balance in that currency
data[].availableBalancenumberAvailable balance (same as balance for business wallets)

​
Error Responses

​
401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}
Solution: Verify your API key is correct.

​
Usage Example

const response = await fetch('https://gateway.staging.useyala.com/v1/payout-api/payouts/wallets', {
  method: 'GET',
  headers: {
    'x-api-key': 'your-api-key'
  }
});

const { data: wallets } = await response.json();
// Show balances per currency before user selects source currency for payout
wallets.forEach(w => {
  console.log(`${w.currency}: ${w.balance} (available: ${w.availableBalance})`);
});

​
Notes

  • Returns only business wallets (one per currency). Collection and suspense wallets are not included.
  • Use the returned currency and balance to validate sufficient funds before initiating a payout; debit always comes from the sourceCurrency wallet.
  • If you have no wallets, data is an empty array [].

Authorizations

​
x-api-key
string
header
required

Response

Wallet balances retrieved successfully

​
data
object[]

List of wallet balances for the tenant