Wallets - API Documentation

Overview

The Wallets API allows you to manage and view your merchant account balances across different currencies. Each currency has its own wallet with available and locked balances.

ℹ️ Note: Wallets are automatically created when you receive your first transaction in a specific currency. You don't need to manually create wallets.

💡 Balance Types:

Balance: Total amount in your wallet
Locked Balance: Funds temporarily locked for pending transactions
Available Balance: Funds available for withdrawal or payouts (Balance - Locked Balance)

GET List All Wallets

https://genesyspay.com/api/v2/wallets

Retrieve all wallet accounts for your business across all currencies.

Example Request

curl -X GET https://genesyspay.com/api/v2/wallets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"

Success Response

{
  "status": "success",
  "data": [
    {
      "currency": "XOF",
      "balance": "150000.00",
      "locked_balance": "5000.00",
      "available_balance": "145000.00",   
      "created_at": "2026-01-15T10:30:00+00:00"
    },
    {
      "currency": "ZMW",
      "balance": "8500.50",
      "locked_balance": "0.00",
      "available_balance": "8500.50",
      "created_at": "2026-02-01T14:20:00+00:00"
    },
    {
      "currency": "GHS",
      "balance": "2300.00",
      "locked_balance": "300.00",
      "available_balance": "2000.00",
      "created_at": "2026-02-10T09:15:00+00:00"
    }
  ]
}

Response Fields

Field	Type	Description
`currency`	string	3-letter currency code (XOF, ZMW, GHS, etc.)
`balance`	string	Total balance in the wallet
`locked_balance`	string	Amount locked for pending transactions
`available_balance`	string	Available balance for payouts (balance - locked_balance)
`created_at`	string	ISO 8601 timestamp of wallet creation

GET Get Wallet by Currency

https://genesyspay.com/api/v2/wallets/{currency}

Retrieve the balance and details for a specific currency wallet.

Path Parameters

Parameter	Type	Required	Description
`currency`	string	Required	3-letter currency code (e.g., XOF, ZMW, GHS)

Example Request

curl -X GET https://genesyspay.com/api/v2/wallets/XOF \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"

Success Response

{
  "status": "success",
  "data": {
    "currency": "XOF",
    "balance": "150000.00",
    "locked_balance": "5000.00",
    "available_balance": "145000.00",
    "created_at": "2026-01-15T10:30:00+00:00"
  }
}

Error Responses

HTTP Status	Error Message	Description
422	Invalid currency code	The currency code provided is not valid or not supported
404	Account not found for this currency	No wallet exists for the specified currency
401	Unauthorized	Invalid or missing API key

Error Response Example

{
  "status": "error",
  "message": "Invalid currency code"
}

Not Found Response Example

{
  "status": "error",
  "message": "Account not found for this currency"
}

Common Use Cases

1. Check Available Balance Before PayOut

Before initiating a payout, verify you have sufficient available balance:

# Check ZMW wallet balance
curl -X GET https://genesyspay.com/api/v2/wallets/ZMW \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"

# If available_balance >= payout_amount + fees, proceed with payout
curl -X POST https://genesyspay.com/api/v2/payouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -d '{"amount": 100, "currency": "ZMW", ...}'

2. Monitor All Wallet Balances

Regularly check all your wallet balances for accounting and reconciliation:

curl -X GET https://genesyspay.com/api/v2/wallets \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"

3. Display Balance in Dashboard

Fetch specific currency balance to display in your merchant dashboard:

# Get XOF balance for Côte d'Ivoire operations
curl -X GET https://genesyspay.com/api/v2/wallets/XOF \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY"

Best Practices

Cache Wisely: Balance information can be cached for a few minutes to reduce API calls, but avoid stale data for payout decisions
Check Before Payout: Always verify available balance before initiating payouts to avoid insufficient funds errors
Monitor Locked Balance: High locked balance indicates many pending transactions - monitor this for cash flow management
Reconcile Regularly: Compare your wallet balances with your internal records regularly
Multi-Currency Support: If operating in multiple countries, list all wallets to get a complete financial picture