Skip to main content

​
Overview

Sub-accounts allow you to create isolated Payaza accounts under your main merchant account for internal business units — for example, your Finance department, Admin team, or separate cost centers. Each sub-account operates independently for collections and payouts while remaining fully visible and controllable from your main account.
Sub-accounts are designed strictly for internal organizational use. They are not intended for onboarding external customers, clients, or third-party merchants. Using sub-accounts for external merchant onboarding violates Payaza’s compliance requirements and may result in account suspension.
Approved use cases:
  • Finance department — separate ledger for finance team operations and disbursements
  • Admin unit — isolated account for operational expenses and vendor payments
  • Cost centers — segment revenue and spend by internal division or project

​
Key Requirements

Use your public API key encoded in Base64. See the Authentication guide for setup instructions.
Set these headers on every request: 
{
  "Authorization": "Payaza <Your public API key encoded in base 64>",
  "X-TenantID": "test",
  "Content-Type": "application/json"
}
Switch X-TenantID to live when operating in the production environment.

​
Endpoints

MethodEndpointDescription
POST/payaza-account/api/v1/subaccounts/merchantCreate a new sub-account
GET/payaza-account/api/v1/subaccounts/merchant/enquiry/{payazaSubAccountReference}Retrieve sub-account details by reference

​
How it works

1

Create the sub-account

Call the Create endpoint with the sub-account name and the required business details. On success, you receive a payazaSubAccountReference — store this immediately against the relevant internal unit in your system.
2

Use the sub-account for transactions

Pass the payazaSubAccountReference in your transfer and collection requests to route transactions to the correct internal unit.
3

Retrieve sub-account details

Use the Enquiry endpoint with the sub-account reference to fetch the current balance, account status, and account details at any time.

​
Create a sub-account

cURL
curl --request POST \
  --url https://api.payaza.africa/live/payaza-account/api/v1/subaccounts/merchant \
  --header 'authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'content-type: application/json' \
  --header 'x-tenantid: test' \
  --data '{
  "mainAccountPayazaReference": "100000000",
  "name": "Test Sub Account",
  "currency": "NGN",
  "country": "NGA"
}'
Request parameters
ParameterTypeRequiredDescription
mainAccountPayazaReferencestringYesThe account reference of the main Payaza account
namestringYesThe name of this subaccount
currencystringYesThe currency code
countrystringYesThe country code in ISO 3166-1 alpha-3 format
Sample response 
{
  "message": "New account created",
  "status": true,
  "data": [
    {
      "id": 1110,
      "accountName": "Test Sub Account",
      "accountStatus": "ACTIVE",
      "accountBalance": 0,
      "escrowBalance": 0,
      "businessFk": 11407,
      "currency": "NGN",
      "owner": "PAYAZA",
      "country": "NGA",
      "creationReference": "DC625576B5BF426A94CB6B1D868C0",
      "actionStatus": "ACTIVE",
      "payazaAccountReference": "2010000120",
      "pnc": false,
      "pnd": false,
      "virtualAccounts": [
        {
          "accountNumber": "9977719429",
          "accountName": "MERCHANT(Test Sub Account)",
          "bankCode": "000023"
        }
      ]
    }
  ]
}

​
Retrieve sub-account details

cURL
curl --request GET \
  --url https://api.payaza.africa/live/payaza-account/api/v1/subaccounts/merchant/enquiry/{{payazaSubAccountReference}} \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'X-TenantID: test'
ParameterTypeRequiredDescription
payazaSubAccountReferencestringYesThe account reference of the Payaza sub account that has been created
Sample response 
{
  "message": "Account enquiry response",
  "status": true,
  "data": [
    {
      "id": 1110,
      "accountName": "Test Sub Account",
      "payazaAccountReference": "2010000120",
      "status": "ACTIVE",
      "accountBalance": 0,
      "businessId": 11407,
      "currency": "NGN",
      "country": "NGA",
      "organizationName": "PAYAZA",
      "productCode": "PAYOUT-SUB-NGN",
      "productNumber": "201",
      "postNoCredit": false,
      "postNoDebit": false,
      "originatorName": null,
      "pauseTransactions": null,
      "hasVirtualAccounts": true,
      "virtualAccounts": [
        {
          "accountNumber": "9977719429",
          "accountName": "MERCHANT(Test Sub Account)",
          "bankCode": "000023",
          "bankId": 2789
        }
      ],
      "createdDate": "2023-11-09T13:05:15.611669"
    }
  ],
  "pageDetail": {
    "sorted": false,
    "pageNumber": 0,
    "pageSize": 0,
    "paged": false,
    "totalPages": 0,
    "totalElements": 0,
    "last": false,
    "size": 0,
    "number": 0,
    "numberOfElements": 0,
    "offset": null
  },
  "totalCount": 0,
  "responseCode": null
}

​
Compliance requirements

Sub-accounts are subject to your organization’s KYB (Know Your Business) approval. The following rules apply:
  • Sub-accounts must map to real, identifiable internal units within your organization
  • Each sub-account must have a documented owner or responsible team
  • Transaction flows through sub-accounts are audited — ensure all activity aligns with the stated purpose of the unit
  • Do not create sub-accounts as pass-through accounts for unrelated third parties
Contact support@payaza.africa if you need clarification on what constitutes an approved sub-account use case before proceeding.

​
Best practices

  • Map each sub-account to exactly one internal unit — never share a reference across unrelated departments
  • Store payazaSubAccountReference durably in your database immediately after creation — it cannot be recovered if lost
  • Use the Enquiry endpoint to verify a sub-account’s status before routing live transactions to it
  • Scope system access so that only the authorized team can initiate transactions from each sub-account

​
What’s next

Transfers

Send payouts from your Payaza account or sub-account to a beneficiary.

Payaza Account

View balances and account references across all currencies.