Subsidiary Accounts

The subsidiary account is a real, ledger‑backed account that holds actual funds on behalf of the merchant’s customer. It is not a virtual account; it is a fully functional account in the Paga system with its own balance, transaction history, and unique NUBAN. The merchant remains the legal owner of the account and all funds within it.

Prerequisites

Before you begin integrating the Subsidiary Account API, ensure the following are in place:

1. Paga Business Account
   You must have a registered Paga business account. If you do not yet have one, create an account at pagaengine.com.

2. API Credentials
   Once your business account is active, log in to the Paga portal and navigate to Developer tools → API keys.
   Here you will find:

   • Public Key – used as the username for HTTP Basic Authentication.
   • Secret Key – used as the password for HTTP Basic Authentication.
   • hashKey – a pre‑shared secret used to compute the SHA‑512 hash header and to verify webhook callbacks.

   Keep these credentials secure. If you cannot access the API keys section, contact Paga support.

3. Funded Merchant Balance
   To top up a subsidiary account (move funds from your main balance into the customer’s account), your Paga business account must hold sufficient funds.

4. Bank Identifiers (optional)
   If you intend to use the auto‑sweep feature with a bank destination, you will need the recipient bank’s bankPublicId. Use the Get Banks endpoint to retrieve this value.

Base URLs

All endpoints are relative to the base URL. Requests and responses use JSON with Content-Type: application/json.

Authentication

Every request must include two authentication mechanisms.

1. HTTP Basic Authentication

Use your Public Key as the username and your Secret Key as the password.
These are obtained from your Paga dashboard under Developer tools → API keys.
The standard Authorization header is required:

Authorization: Basic base64(PublicKey:SecretKey)

2. SHA‑512 Hash Header

A hash header is required for all POST, PUT, and some GET requests.
The hash is computed as:

SHA‑512( concatenated_parameters + hashKey )

The exact concatenation depends on the endpoint (documented in each operation).
For any optional parameter not included in the request, use an empty string "" in the concatenation.
The hashKey is the secret displayed alongside your keys in the API keys page.

Example (Create Account):
Concatenate: referenceNumber + accountReference + iifiNumber + autoSweep.bankPublicId + autoSweep.destination + autoSweep.accountNumber + callbackUrl + hashKey
If you are not providing iifiNumber, its placeholder becomes "".

Terminology

• Subsidiary Account – A real, ledger‑backed account owned by the merchant and operated on behalf of an end customer. It holds actual funds, has a unique NUBAN, and supports the full range of transaction operations.
• accountNumber – The system‑generated NUBAN (10‑digit account number). Returned after creation.
• accountReference – A merchant‑defined unique identifier for the account (12–30 characters). You supply this at creation; it cannot be changed later.
• accountIdentifier – When a path parameter or field requires an identifier, you may use either the accountNumber (NUBAN) or the accountReference.
• Currency – Only NGN is supported at this time.
• BVN – Bank Verification Number. In request bodies this is named iifiNumber; in callback payloads it appears as financialIdentificationNumber.

API Reference

1. Create a Subsidiary Account

POST /subsidiary-accounts

Creates a new, real subsidiary account for a customer. The account is immediately able to receive funds.

Idempotency: The referenceNumber uniquely identifies the request. Submitting the same referenceNumber again will return the existing account rather than creating a duplicate.

Request Headers

• Authorization: Basic ...
• hash: <SHA‑512 hash>

Request Body

* At least one of phoneNumber or email is required.

Hash Computation

Concatenate the following values in order, using an empty string "" for any missing optional field:

referenceNumber + accountReference + iifiNumber + autoSweep.bankPublicId + autoSweep.destination + autoSweep.accountNumber + callbackUrl + hashKey

Example Requests

Scenario 1: No auto‑sweep – funds stay in subsidiary account

POST /subsidiary-accounts HTTP/1.1
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
hash: ...

{
  "referenceNumber": "REF-100005550002",
  "accountReference": "PAGA-255026-NO-AUTOSWEEP",
  "accountName": "Test Subsidiary Account",
  "phoneNumber": "08012345678",
  "firstName": "Test",
  "lastName": "Customer",
  "email": "[email protected]",
  "iifiNumber": "22222132329",
  "fundingTransactionLimit": 500000.00,
  "fundingDailyLimit": 2000000.00,
  "status": "ACTIVE"
}

Scenario 2: Auto‑sweep to merchant’s business account (VIRTUAL_ACCOUNT)

POST /subsidiary-accounts HTTP/1.1
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
hash: ...

{
  "referenceNumber": "REF-100005550003",
  "accountReference": "PAGA-255026-VIRTUAL-SWEEP",
  "accountName": "Test Virtual Sweep",
  "phoneNumber": "08012345679",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "status": "ACTIVE",
  "autoSweep": {
    "destination": "VIRTUAL_ACCOUNT"
  }
}

Scenario 3: Auto‑sweep to a bank account (BANK)

POST /subsidiary-accounts HTTP/1.1
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
hash: ...

{
  "referenceNumber": "REF-100005550004",
  "accountReference": "PAGA-255026-BANK-SWEEP",
  "accountName": "Test Bank Sweep",
  "phoneNumber": "08012345670",
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "[email protected]",
  "status": "ACTIVE",
  "autoSweep": {
    "destination": "BANK",
    "bankPublicId": "7131F94B-C0AC-43FB-BF6A-3407D27F1806",
    "accountNumber": "0073141524"
  }
}

Response 200 OK

{
    "referenceNumber": "REF-100005550002",
    "statusCode": "0",
    "statusMessage": "success",
    "accountNumber": "0750529406",
    "accountReference": "PAGA-255026-NO-AUTOSWEEP",
    "status": "ACTIVE",
    "balance": 0.0,
    "currency": "NGN"
}

2. Retrieve a Subsidiary Account

GET /subsidiary-accounts/{accountIdentifier}?referenceNumber={referenceNumber}

Fetches all properties of an existing subsidiary account.

Path Parameters

• accountIdentifier (string, required) – The NUBAN or accountReference of the account.

Query Parameters

• referenceNumber (string, required) – Unique reference for this request.

Hash Computation

referenceNumber + accountIdentifier + hashKey

Example Request

GET /subsidiary-accounts/0750529406?referenceNumber=REF-GET-001 HTTP/1.1
Authorization: Basic ...
hash: ...

Response 200 OK

{
    "referenceNumber": "REF-GET-001",
    "statusCode": "0",
    "statusMessage": "success",
    "accountNumber": "0750529406",
    "accountReference": "PAGA-255026-NO-AUTOSWEEP",
    "status": "ACTIVE",
    "balance": 194900.0,
    "currency": "NGN",
    "accountName": "Test Subsidiary Account",
    "phoneNumber": "08012345678",
    "firstName": "Test",
    "lastName": "Customer",
    "email": "[email protected]",
    "iifiNumber": "22222132329",
    "fundingDailyLimit": 2000000.0,
    "fundingTransactionLimit": 500000.0,
    "callbackUrl": "https://example.com/webhook"
}

3. Update a Subsidiary Account

PUT /subsidiary-accounts/{accountIdentifier}

Modifies properties of an existing subsidiary account.
Immutable fields: accountNumber (NUBAN) and accountReference cannot be changed.
Only the fields you supply are updated; omitted fields keep their current values.

Path Parameters

• accountIdentifier (string, required) – NUBAN or accountReference.

Request Body

The same fields as Create are available, except accountReference and accountNumber. The autoSweep object can be added, modified, or removed entirely (by setting it to null) to change the sweep behaviour.

Hash Computation

referenceNumber + accountIdentifier + iifiNumber + autoSweep.destination + autoSweep.bankPublicId + autoSweep.accountNumber + callbackUrl + hashKey

(use "" for any omitted optional field)

Example Request

PUT /subsidiary-accounts/0750529406 HTTP/1.1
Authorization: Basic ...
hash: ...

{
  "referenceNumber": "REF-UPDATE-001",
  "accountName": "St Jones School",
  "status": "DISABLED"
}

Response 200 OK

Returns the full updated account object, identical to the Retrieve response.

4. Charge a Subsidiary Account (Withdraw)

POST /subsidiary-accounts/{accountIdentifier}/charge

Moves funds from the subsidiary account to the merchant’s main Paga balance.

Idempotency: The referenceNumber is the idempotency key. Retrying with the same reference number will not result in a duplicate charge; the original result will be returned.

Path Parameters

• accountIdentifier (string, required) – NUBAN or accountReference.

Request Body

Hash Computation

referenceNumber + amount + currency + narration + hashKey

Example Request

POST /subsidiary-accounts/0750529406/charge HTTP/1.1
Authorization: Basic ...
hash: ...

{
  "referenceNumber": "REF-CHARGE-001",
  "amount": 1000.00,
  "currency": "NGN",
  "narration": "Service fee"
}

Response 200 OK

{
    "referenceNumber": "REF-CHARGE-001",
    "statusCode": "0",
    "statusMessage": "success",
    "transactionId": "MPVAT-P_20260610214236118_4577638_JX438_qznml",
    "newBalance": 98000.0
}

5. Top Up a Subsidiary Account

POST /subsidiary-accounts/{accountIdentifier}/topup

Moves funds from the merchant’s main Paga balance into the subsidiary account.

Idempotency: The referenceNumber serves as the idempotency key. Retries with the same reference number are safe and will return the original result.

Path Parameters

• accountIdentifier (string, required) – NUBAN or accountReference.

Request Body

Hash Computation

referenceNumber + amount + currency + narration + hashKey

Example Request

POST /subsidiary-accounts/0750529406/topup HTTP/1.1
Authorization: Basic ...
hash: ...

{
  "referenceNumber": "REF-TOPUP-001",
  "amount": 500.00,
  "currency": "NGN",
  "narration": "Bonus credit"
}

Response 200 OK

Same structure as Charge:

{
    "referenceNumber": "REF-TOPUP-001",
    "statusCode": "0",
    "statusMessage": "success",
    "transactionId": "MPVAT-P_20260610220000000_4577650_SMQDM_qznml",
    "newBalance": 50500.0
}

6. Transfer Between Subsidiary Accounts

POST /subsidiary-accounts/transfer

Transfers funds from one subsidiary account to another, both owned by the same merchant.

Idempotency: The referenceNumber uniquely identifies the transfer. Duplicate submissions with the same reference will return the original transaction details.

Request Body

Hash Computation

referenceNumber + sourceAccountIdentifier + destinationAccountIdentifier + amount + currency + narration + hashKey

Example Request

POST /subsidiary-accounts/transfer HTTP/1.1
Authorization: Basic ...
hash: ...

{
  "referenceNumber": "REF-TRANSFER-001",
  "sourceAccountIdentifier": "0750529406",
  "destinationAccountIdentifier": "3859568112",
  "amount": 1500.00,
  "currency": "NGN",
  "narration": "Payment for goods"
}

Response 200 OK

{
    "referenceNumber": "REF-TRANSFER-001",
    "statusCode": "0",
    "statusMessage": "success",
    "transactionId": "MPVAT-P_20260610230032541_4577650_SMQDM_qznml",
    "source": {
        "accountIdentifier": "0750529406",
        "amount": 1500.0,
        "newBalance": 96500.0
    },
    "destination": {
        "accountIdentifier": "3859568112",
        "amount": 1500.0,
        "newBalance": 3000.0
    }
}

7. Get Subsidiary Account Balance

GET /subsidiary-accounts/{accountIdentifier}/balance?referenceNumber={referenceNumber}

Returns the current balance of a subsidiary account.

Path Parameters

• accountIdentifier – NUBAN or accountReference.

Query Parameters

• referenceNumber (string, required) – Request reference.

Hash Computation

referenceNumber + accountIdentifier + hashKey

Response 200 OK

{
    "referenceNumber": "REF-BAL-001",
    "statusCode": "0",
    "statusMessage": "success",
    "accountNumber": "0750529406",
    "accountReference": "PAGA-255026-NO-AUTOSWEEP",
    "balance": 98000.0,
    "currency": "NGN",
    "timeStamp": "2026-06-10T22:50:16"
}

8. Get Subsidiary Account History

GET /subsidiary-accounts/{accountIdentifier}/history?startDateTimeUTC={start}&endDateTimeUTC={end}&pageSize={size}&pageNumber={page}

Returns a paginated list of transactions for a given account within a date range.
The date range must not exceed 3 months.

Path Parameters

• accountIdentifier – NUBAN or accountReference.

Query Parameters

Note: This is a GET request. No request body is required. The referenceNumber should be included as a query parameter (?referenceNumber=...).

Hash Computation

accountIdentifier + startDateTimeUTC + endDateTimeUTC + hashKey

Response 200 OK

{
    "referenceNumber": "REF-HIST-001",
    "statusCode": "0",
    "statusMessage": "success",
    "itemCount": 3,
    "totalItems": 27,
    "totalPages": 3,
    "currentPage": 0,
    "transactions": [
        {
            "transactionType": "CREDIT",
            "amount": 1500.00,
            "transactionDate": "2026-06-11T10:22:16.920",
            "status": "SUCCESSFUL"
        }
        // ...
    ]
}

Callback (Webhook) Notifications

Paga sends HTTP POST notifications to your server for important events.
You can set a global webhook URL in your Paga dashboard, or override it per account using the callbackUrl field when creating/updating an account.

Verifying Callback Authenticity

Every callback payload contains a hash field.
Compute the expected hash and compare it with the received value to ensure the notification is genuine.

General formula (varies slightly per notification type):

SHA-512( field1 + field2 + ... + hashKey )

Always use the raw values from the payload, concatenated as a single string.
For missing fields, use an empty string "".

9. Funding Notification

Sent when an external payer deposits money into a subsidiary account (e.g., via bank transfer).

Callback Payload

Hash Verification (Funding)

Concatenate:

transactionReference + fundingTransactionReference + transactionDate + amount + accountNumber + hashKey

(If transactionReference is null, use an empty string "".)

Expected Response

Return 200 OK with body:

{"status": "SUCCESS"}

10. Charge Notification

Sent when a charge (withdrawal) is completed (event: SUBSIDIARY_ACCOUNT_CHARGE_COMPLETE).

Callback Payload

Hash Verification (Charge)

Concatenate:

externalReferenceNumber + transactionDate + amount + accountNumber + hashKeyjso

(Note: there is no transactionReference in this callback.)

Expected Response

{"status": "SUCCESS"}

11. Top‑Up Notification

Sent when a top‑up is completed (event: SUBSIDIARY_ACCOUNT_TOP_UP_COMPLETE).

Callback Payload

Hash Verification (Top‑Up)

Same as charge:

externalReferenceNumber + transactionDate + amount + accountNumber + hashKey

Expected Response

{"status": "SUCCESS"}

Error Handling

Paga uses standard HTTP status codes and a consistent JSON error body.

HTTP Status Codes

Error Response Format

{
  "statusCode": "1001",
  "statusMessage": "Account not found",
  "referenceNumber": "..."
}

• statusCode is a non‑zero string (see Paga Collect Status Codes for the full list).
• referenceNumber echoes the request reference if provided.

Handling Timeouts and Server Errors

Network timeouts or 500 Internal Server Error responses can leave the state of a transaction uncertain. To avoid accidental double‑processing or incorrect rollbacks:

• Do not assume failure. If a request times out or receives a 500 error, the transaction may have already succeeded on Paga’s side.
• Do not reverse or rollback the transaction in your system until you have confirmed the final outcome.
• Wait for the webhook notification. All successful transactions (charges, top‑ups, transfers, fundings) will eventually produce a callback event with the definitive status. Use this to update your local state.
• If you must retry, use the same referenceNumber – Paga’s API is idempotent, so retrying will return the original result (success or failure) without creating a duplicate transaction.

Idempotency

Every financial operation (create account, charge, top‑up, transfer) uses the referenceNumber as an idempotency key.
Submitting the same referenceNumber more than once will not create duplicate transactions or accounts; the API will return the result of the original operation.

This allows you to safely retry a request in case of network failure without risk of double‑charging or double‑crediting. Always generate a unique referenceNumber for each new operation, and reuse the same value only for retries.

Appendix

Get Banks

To obtain the bankPublicId needed for auto‑sweep configuration, use the Get Banks endpoint.

GET /banks

It returns a list of supported banks with their IDs and names.
Refer to the full Paga Collect API reference for details.