Skip to main content

​
Overview

The Payaza Account API gives you access to the core details of your merchant account: your payazaAccountReference (required for initiating transfers), current balance per currency, and any virtual account numbers assigned to your account. This is typically called once at startup, or refreshed before any significant money movement to confirm your available balance.

​
Key Requirements

Use your public API key encoded in Base64. See the Authentication guide for setup instructions.
Set these headers on the request: 
{
  "Authorization": "Payaza <base64-encoded-public-key>",
  "X-TenantID": "test"
}

​
Endpoint

MethodEndpointDescription
GET/payaza-account/api/v1/mainaccounts/merchant/enquiry/mainRetrieve all main accounts for your merchant

​
Key response fields

FieldDescription
payazaAccountReferenceThe account reference used in Transfer requests. Use the one that matches the currency you want to send from.
accountBalanceCurrent available balance for this currency account
currencyThe currency of this account (e.g. "NGN", "GHS")
statusAccount status — should be "ACTIVE" before initiating transfers
virtualAccountsAny virtual account numbers assigned to this account
postNoDebitIf true, outbound transactions (payouts) are blocked — check this before initiating a transfer
The response returns one object per currency. Each currency your account supports (NGN, GHS, etc.) will appear as a separate item in the data array. Use the payazaAccountReference from the item whose currency matches your intended payout.

​
How to use it

1

Fetch account details

Call the Main Accounts endpoint to retrieve your full account summary across all currencies.
2

Select the correct account reference

Find the account in the response whose currency matches the currency you want to send from. Copy its payazaAccountReference.
3

Use the reference in transfer requests

Pass the payazaAccountReference as account_reference in your Initiate A Transfer request body.

​
Best practices

  • Cache the payazaAccountReference per currency — it does not change and you do not need to re-fetch it on every transfer
  • Always check postNoDebit and accountBalance before initiating a large transfer to surface issues early
  • If postNoDebit is true, contact support@payaza.africa to have the restriction reviewed

​
What’s next

Transfers

Use your account reference to initiate payouts to bank accounts and mobile wallets.

Sub Accounts

Create segmented accounts for separate business units or verticals.