Sub Accounts

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

Method	Endpoint	Description
`POST`	`/payaza-account/api/v1/subaccounts/merchant`	Create a new sub-account
`GET`	`/payaza-account/api/v1/subaccounts/merchant/enquiry/{payazaSubAccountReference}`	Retrieve sub-account details by reference

How it works

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.

Use the sub-account for transactions

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

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

Parameter	Type	Required	Description
`mainAccountPayazaReference`	`string`	Yes	The account reference of the main Payaza account
`name`	`string`	Yes	The name of this subaccount
`currency`	`string`	Yes	The currency code
`country`	`string`	Yes	The 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'

Parameter	Type	Required	Description
`payazaSubAccountReference`	`string`	Yes	The 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

Get started

Developer tools

Accept payments

Send money

Disputes & refunds

Account management

Split Settlements

Overview

Key Requirements

Endpoints

How it works

Create a sub-account

Retrieve sub-account details

Compliance requirements

Best practices

What’s next

Transfers

Payaza Account

​Overview

​Key Requirements

​Endpoints

​How it works

​Create a sub-account

​Retrieve sub-account details

​Compliance requirements

​Best practices

​What’s next

Transfers

Payaza Account

Overview

Key Requirements

Endpoints

How it works

Create a sub-account

Retrieve sub-account details

Compliance requirements

Best practices

What’s next