Skip to main content

​
How authentication works

Every Payaza API request requires an Authorization header. The format is: 
Authorization: Payaza <base64-encoded-api-key>
Two things are different from most APIs:
  1. The prefix is Payaza — not Bearer
  2. Your API key must be Base64-encoded before use

​
Step 1 — Retrieve your API key

1

Log in to the Payaza dashboard

Go to business.payaza.africa and log in to your account.
2

Open Settings → Developers

Click Settings in the left sidebar, then select Developers from the dropdown.
3

Generate your keys

Click the Generate Keys button to create your API keys. Toggle between Test Mode and Live Mode to retrieve the key for each environment.
Never expose your API key in client-side code, browser JavaScript, or a public repository. If a key is ever compromised, regenerate it immediately from the dashboard.

​
Step 2 — Encode your key in Base64

Your API key must be Base64-encoded before placing it in the Authorization header. 
echo -n "your-api-key-here" | base64

​
Step 3 — Make an authenticated request

These are the possible headers that can be added to a Payaza API request:
HeaderRequiredValue
AuthorizationYesPayaza <base64-encoded-key>
X-TenantIDDepends on APItest or live
Content-TypeYes (POST/PUT)application/json
curl --request GET \
  --url https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts \
  --header 'Authorization: Payaza UFo4748S0xJVkUtSJDS5RThDQzEtQjAzMS00RUNBLTgwOTctRUVCMjA5NzJENTY0' \
  --header 'X-TenantID: test'
X-TenantID is required for some APIs but not all. For APIs that require it, use test during development and live in production. See the Required headers by API table below for a full breakdown.

​
Required headers by API

Different Payaza APIs require different combinations of headers. Use this table as a quick reference before making requests.
APIAuthorizationX-TenantIDX-ProductIDContent-Type
Card CollectionsPayaza <base64-key>Not requiredNot requiredapplication/json
Momo / XOF / ZAR / SLE CollectionsPayaza <base64-key>test or liveappapplication/json
Apple Pay / Google PayPayaza <base64-key>Not requiredNot requiredapplication/json
Transfers (Payouts)Payaza <base64-key>test or liveNot requiredapplication/json
Virtual AccountsPayaza <base64-key>Not requiredNot requiredapplication/json
Sub-accountsPayaza <base64-key>test or liveNot requiredapplication/json
Refunds & ChargebacksPayaza <base64-key>Not requiredNot requiredapplication/json
Account EnquiryPayaza <base64-key>test or liveNot requiredapplication/json
X-ProductID: app is only required for the Momo, XOF, ZAR, and SLE collections API (/subsidiary/collections/v1/...). All other APIs do not require it.
X-TenantID is not required for Apple Pay, Google Pay, Virtual Accounts, Refunds, and Chargebacks. All other listed APIs require X-TenantID set to test (development) or live (production).

​
Test vs Live environments

Payaza uses a single API base URL (https://api.payaza.africa/live/) for both environments. The /live/ segment in the URL is a fixed path prefix — it does not change between environments. Only the X-TenantID header and the API key distinguish test from live.
TestLive
X-TenantIDtestlive
API keyGenerated in Test Mode on dashboardGenerated in Live Mode on dashboard
TransactionsNot processed or settledReal transactions processed and settled
KYB requiredNoYes — must be approved before going live
You can begin testing immediately after creating your Payaza account. KYB (Know Your Business) verification is only required to access the live environment.

​
Authentication errors

A failed authentication returns this response: 
{
  "message": "Authentication failed",
  "status": false,
  "retry_count": 0
}
CauseFix
Missing Authorization headerAdd the header to your request
Raw (non-encoded) API key usedBase64-encode your key before use
Wrong prefix — e.g. Bearer instead of PayazaChange the prefix to Payaza
Test key used with X-TenantID: liveMatch the key to the correct environment
Key was regenerated on the dashboardCopy the new key, encode it, and update your integration

​
What’s next

Getting Started

Walk through account setup and make your first API call end-to-end.

Webhooks

Receive real-time payment notifications when events happen on your account.

Transfers

Start sending payouts to bank accounts and mobile wallets.

Errors

A reference for all API error responses and how to resolve them.