Transfers - Payaza Documentation

Overview

Payaza Transfers lets you send money to any bank account or mobile wallet in Nigeria, Ghana, Kenya, and other supported countries. This guide walks through the full flow — from confirming the recipient’s account name to initiating the payout and verifying the outcome. The transfer flow has four steps:

Verify account name

Confirm the recipient’s account name before sending (Nigeria and Ghana only).

Get your account reference

Fetch the payazaAccountReference for the currency you want to send from.

Initiate the transfer

Send the funds using the recipient details, amount, and your transaction PIN.

Confirm the outcome

Query the transaction status or listen for a webhook to confirm success or failure.

Before you begin

You need the following before making your first transfer:

A funded Payaza account for the currency you want to send from
Your public API key encoded in Base64 — see the Authentication guide
A webhook URL saved on the dashboard — see the Webhooks guide
Your transaction PIN set up on the dashboard — required to authorise every payout
Your server IP address whitelisted on the dashboard — required before live payouts are processed

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 from test to live when you are ready to process real payouts.

Step 1 — Verify account name

This step applies to Nigeria (NGN) and Ghana (GHS) only. Skip to Step 2 if you are sending to other countries.

Resolve and display the recipient’s account name before proceeding. This prevents sending funds to the wrong account and is required as a confirmation step before initiating a transfer.

cURL

curl --request POST \
  --url https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/provider/enquiry \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --header 'X-TenantID: test' \
  --data '{
    "service_payload": {
      "currency": "NGN",
      "bank_code": "090123",
      "account_number": "0103937899"
    }
  }'

Response

{
  "response_code": 200,
  "response_message": "Approved or completely successful",
  "response_content": {
    "account_number": "0938573814",
    "bank_code": "090123",
    "account_name": "JOHN DOE",
    "account_status": "ACTIVE",
    "transaction_reference": 9
  },
  "response_content_class": "com.fin78.app.payload.response.enquiry.account.AccountNameEnquiryInfoResponse"
}

Always display the resolved account_name to the user and require their confirmation before proceeding. Never auto-submit.

Step 2 — Get your account reference

Retrieve the payazaAccountReference for the currency you want to send from. You will pass this as account_reference in your transfer request.

cURL

curl --request GET \
  --url https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/enquiry/main \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'X-TenantID: test'

Response

{
  "message": "Account enquiry response",
  "status": true,
  "data": [
    {
      "id": 1,
      "accountName": "Test Merchant",
      "payazaAccountReference": "1010000000",
      "status": "ACTIVE",
      "accountBalance": 990.13,
      "businessId": 92,
      "currency": "NGN",
      "country": "NGA",
      "organizationName": "PAYAZA",
      "productCode": "PAYOUT-MAIN-NGN",
      "productNumber": "101",
      "postNoCredit": false,
      "postNoDebit": false,
      "originatorName": null,
      "pauseTransactions": null,
      "hasVirtualAccounts": true,
      "holdTransactionAtLowBalance": false,
      "virtualAccounts": [
        {
          "accountNumber": "99926838326",
          "accountName": "PAYAZA(Test Merchant)",
          "bankCode": "000023",
          "bankId": 306
        }
      ]
    }
  ]
}

The response contains one object per currency. Use the payazaAccountReference from the object whose currency matches your intended payout.

Step 3 — Initiate the transfer

One-time live setup

Two steps are required before your first live payout. They only need to be done once.

1. Whitelist your server IP address

Live transfers are blocked until your server IP is whitelisted.

Go to Settings → Developers → IP Whitelisting

Add your server IP address(es) and save

IP whitelisting is only required for live transfers. Test environment transfers are not IP-restricted.

2. Set your transaction PIN

A 6-digit PIN is required to authorise every transfer. Set it once on the dashboard.

Go to Settings → Profile → Security

Click "Edit Details" then "Update Transaction PIN"

Your PIN must not include:

Repeated digits — e.g. 111111
Sequential digits — e.g. 123456 or 654321
Repeating patterns — e.g. 121212 or 123123

After setting your PIN, email support@payaza.africa from your Super Admin email to request the PND (Post No Debit) restriction be lifted on your account.

Sample email

Good day Payaza Team,

This is to confirm that I have set up my Transaction PIN on my Payaza account.
Kindly remove the PND restriction on my account so that I can make payouts.

My Payaza business name is: {{Your Payaza Business Name}}

Thank you.

Request

cURL

curl --request POST \
  --url https://api.payaza.africa/live/payout-receptor/payout \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --header 'X-TenantID: live' \
  --data '{
    "transaction_type": "nuban",
    "service_payload": {
      "payout_amount": 100,
      "transaction_pin": 419374,
      "account_reference": "1010000009",
      "currency": "NGN",
      "country": "NGA",
      "payout_beneficiaries": [
        {
          "credit_amount": 100,
          "account_number": "9207067319",
          "account_name": "John Doe",
          "bank_code": "000013",
          "narration": "Test",
          "transaction_reference": "TD93001234",
          "sender": {
            "sender_name": "Jane Doe",
            "sender_id": "",
            "sender_phone_number": "01234595",
            "sender_address": "123, Ace Street"
          }
        }
      ]
    }
  }'

Request parameters

Parameter	Type	Required	Description
`transaction_type`	`string`	Yes	Payment rail — use `"nuban"` for Nigerian bank accounts
`service_payload.payout_amount`	`double`	Yes	Total amount to send. Must equal the sum of all `credit_amount` values
`service_payload.transaction_pin`	`integer`	Yes	Your 6-digit transaction PIN
`service_payload.account_reference`	`string`	Yes	Your Payaza account reference from Step 2
`service_payload.currency`	`string`	Yes	ISO currency code — e.g. `"NGN"`, `"GHS"`
`service_payload.country`	`string`	Yes	ISO country code — e.g. `"NGA"`, `"GHA"`
`payout_beneficiaries[].credit_amount`	`double`	Yes	Amount to send to this recipient
`payout_beneficiaries[].account_number`	`string`	Yes	Recipient’s bank account number
`payout_beneficiaries[].account_name`	`string`	Yes	Recipient’s account name (from Step 1)
`payout_beneficiaries[].bank_code`	`string`	Yes	Recipient’s bank code
`payout_beneficiaries[].transaction_reference`	`string`	Yes	Your unique reference for this transfer
`payout_beneficiaries[].narration`	`string`	Yes	Transfer description shown on the recipient’s statement
`payout_beneficiaries[].sender`	`object`	No	Sender information block
`payout_beneficiaries[].sender.sender_name`	`string`	Yes	Full name of the sender
`payout_beneficiaries[].sender.sender_id`	`string`	No	Sender’s identification number (optional)
`payout_beneficiaries[].sender.sender_phone_number`	`string`	Yes	Sender’s phone number
`payout_beneficiaries[].sender.sender_address`	`string`	Yes	Sender’s physical address

`transaction_type` values

The transaction_type field controls which payment rail is used for the payout. Pass the value that matches the recipient’s currency and intended transfer method.

Currency	`transaction_type`	Description
NGN	`nuban`	Nigerian bank account (NUBAN standard)
GHS	`mobile_money`	Ghana mobile money wallet
GHS	`ghipps`	Ghana bank transfer
UGX	`mobile_money`	Uganda mobile money wallet
TZS	`mobile_money`	Tanzania mobile money wallet
TZS	`tiss`	Tanzania bank transfer
KES	`mobile_money`	Kenya mobile money wallet
KES	`kepss`	Kenya bank transfer
XOF	`mobile_money`	XOF mobile money wallet
XOF	`wave`	XOF Wave payouts
XAF	`mobile_money`	Cameroon mobile money wallet
SLE	`mobile_money`	Sierra Leone mobile money wallet
ZAR	`RTC`	South Africa Real-Time Clearing

Response

{
  "response_code": 200,
  "response_message": "Request successfully submitted",
  "response_content": {
    "transaction_status": "09",
    "narration": "Payout",
    "transaction_time": "2023-10-19T14:37:35.517809",
    "amount": 100,
    "response_status": "TRANSACTION_INITIATED",
    "response_description": "Transaction has been successfully submitted for processing"
  },
  "resp_code": "09"
}

Always generate a unique transaction_reference per transfer. Reusing a reference will return a duplicate transaction error and the transfer will be rejected.

Step 4 — Verify the transfer

Use this endpoint to confirm the outcome of a transfer. Call it after initiating, or as a fallback if a webhook is not received.

cURL

curl --request GET \
  --url 'https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/transaction/status?transaction_reference=PBF452009112709121334899870' \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'X-TenantID: test'

Response

{
  "message": "Transaction fetched",
  "status": true,
  "retry_count": 0,
  "data": {
    "transactionDateTime": "2025-11-27T09:31:21.334166",
    "transactionReference": "PBF452009112709121334899870",
    "creditAccount": "0148094596",
    "bankCode": "000013",
    "beneficiaryName": "BELLO  EMMANUEL EVESHODIAME",
    "transactionAmount": 13.0,
    "fee": 1.0,
    "transactionStatus": "NIP_SUCCESS",
    "transactionType": "DEBIT",
    "responseMessage": "Approved or Completely Successful",
    "responseCode": "00",
    "currency": "NGN",
    "balanceBefore": 177.1,
    "balanceAfter": 163.1,
    "duration": {}
  }
}

Transaction statuses

Status	Meaning
`TRANSACTION_INITIATED`	Received and queued for processing
`NIP_SUCCESS`	Transfer successful — funds delivered
`NIP_PENDING`	Still in progress
`NIP_FAILURE`	Transfer failed
`ESCROW_SUCCESS`	Amount deducted but awaiting bank processing — can be reversed

Webhook events

Payaza sends a webhook for every completed or failed transfer. Use webhooks as your primary notification mechanism and the status query endpoint only as a fallback.

Event	When it fires
Successful transfer	Transfer processed and funds delivered
Failed transfer	Transfer attempt failed

{
  "transaction_reference": "PTSA1220246261518348000",
  "transaction_type": "DEBIT",
  "transaction_status": "NIP_SUCCESS",
  "transaction_fee": 10.0,
  "amount_received": 20.0,
  "sent_to": {
    "account_name": "John Doe",
    "account_number": "1234567890",
    "bank_name": "EASTWE BANK"
  },
  "initiated_date": "2024-06-26 16:44:08.718",
  "current_status_date": "2024-06-26 16:44:08.718",
  "is_reversed": false,
  "response_message": "Approved or Completely Successful",
  "response_code": "00",
  "currency": "NGN",
  "country": "NGA",
  "session_id": "999999213419011273456123134124"
}

Always verify the webhook signature before processing the payload. See the Webhooks guide for signature verification steps.

Key reminders

Your Payaza account must be funded before initiating a transfer
Generate a unique transaction_reference for every transfer attempt
Transfers are not retried automatically — your application must handle retry logic
IP whitelisting is required for live payouts only — not enforced in test
If postNoDebit is true on your account, transfers will be blocked — contact support@payaza.africa

What’s next

Webhooks

Set up signature verification and handle transfer event payloads.

Errors

A reference for all transfer error responses and how to fix them.

Virtual accounts

Collect inbound payments via dynamic or reserved virtual account numbers.

Payaza account

View your account balance and reference across all currencies.

​Overview

​Before you begin

​Step 1 — Verify account name

​Step 2 — Get your account reference

​Step 3 — Initiate the transfer

​One-time live setup

​Request

​Request parameters

​transaction_type values

​Response

​Step 4 — Verify the transfer

​Transaction statuses

​Webhook events

​Key reminders

​What’s next

Webhooks

Errors

Virtual accounts

Payaza account

Overview

Before you begin

Step 1 — Verify account name

Step 2 — Get your account reference

Step 3 — Initiate the transfer

One-time live setup

Request

Request parameters

`transaction_type` values

Response

Step 4 — Verify the transfer

Transaction statuses

Webhook events

Key reminders

What’s next