> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate A Transfer
> Send funds from your Payaza account to a bank account or mobile wallet. Supports single and bulk payouts. See the full [Transfers guide](/guides/transfers) for a step-by-step walkthrough.
**Before you call this endpoint:**
- Your server IP address must be whitelisted on the Payaza Dashboard under **Settings → Developers → IP Whitelisting** (live environment only).
- Your transaction PIN must be set up on the dashboard under **Settings → Profile → Security**.
- The `account_reference` is retrieved from the [View Payaza Account Details](/api-reference/payaza-account/view-payaza-account-details) endpoint.
- Bank codes for each supported country are available here
- Cross-border payouts outside Nigeria are not enabled by default — email [support@payaza.africa](mailto:support@payaza.africa) to activate this on your account.
## OpenAPI
````yaml /openapi.json post /payout-receptor/payout
openapi: 3.0.1
info:
title: Payaza Documentation
version: 2.0.0
description: >-
API reference for processing payments using Card, Bank Transfer, USSD, and
QR Code methods.
servers:
- url: https://api.payaza.africa/live
security:
- ApiKeyAuth: []
- TenantID: []
- ProductID: []
tags:
- name: Transfers
description: >-
Transfers are transactions made from your Payaza account to beneficiaries.
Merchants can instantly transfer funds from their available balance. For
every transfer, you need to specify the amount and the beneficiary’s
details. You become eligible to make transfers after you have been
verified. (you sign up, finish account activation and KYC verification).
- name: Payaza Account
description: >-
This is our internal account that can be used to make payouts to other
bank accounts, in single or in bulk. The Payaza account can also be used
to receive settlements. It can also be used to track the transfer status
of your transactions and check your balance instantly
- name: Sub Accounts
description: >-
This enables you to establish Sub Payaza accounts for your customers. Each
sub-account comes with an assigned static virtual account, facilitating
direct funding for individual accounts. Furthermore, the Main Payaza
account can directly initiate funding for each sub-account. These
sub-accounts serve the purpose of managing unique account positions or
balances and facilitating disbursements from these positions to specified
beneficiaries.
- name: EUR Accounts
description: >-
This endpoints enable you to create EUR subaccounts which can be used to
make transfers as required .
- name: Apple Pay and Google Pay
description: >-
Apple Pay and Google Pay give your customers a fast, familiar, and secure
way to complete payments. Our APIs provide a gateway to provide these
services to your users for a smooth payment experience.
- name: Virtual Accounts
description: >-
Virtual Accounts are bank accounts that are created for a specific purpose
and last for specified durations. Virtual accounts are issued by Payaza’s
partner banks. Our virtual account APIs can be used to create virtual
accounts and perform other tasks relevant to virtual accounts. Virtual
accounts are created to foster easy payment collections for your business
and platform.
Static/Reserved Account: This virtual account is created by the merchant
and remains valid indefinitely. It can be used multiple times and does not
expire.
Dynamic Account: This virtual account is generated for a specific
transaction or purpose. Please note that dynamic virtual account remains
valid for a temporary period of time or until a payment of the specified
amount is received. Upon expiry, a merchant can generate another one for a
different purpose.
- name: Card Collection
description: >-
The Card Collection APIs can be used to make card transactions, refund
transactions that have been performed, check the status of a transaction
and so much more.
- name: Card Tokenisation
description: >-
The Card Tokenisation APIs are used to create card tokens, charge cards
using tokens, retrieve all tokens created by a merchant account and
deleting any card token as desired.
- name: Refunds And Chargebacks
description: >-
The Refunds and Chargeback APIs are used to initiate refunds, view your
refund and chargeback history and so much more.
- name: Branches
description: >-
The Refunds and Chargeback APIs are used to initiate refunds, view your
refund and chargeback history and so much more.
- name: Auth-Capture-Void
description: >-
The Auth-Capture-Void APIs provide a two-phase payment process where
transactions are first authorized, then captured or voided. This allows
merchants to hold funds and complete the transaction in the future.
- name: Momo and ZAR Collections
description: APIs for MoMo, ZAR and XOF collections.
- name: Check Transaction Status(Merchant Reference)
description: >-
This endpoint is used to check the transaction status of a transaction
using the Merchant Reference..
paths:
/payout-receptor/payout:
post:
tags:
- Transfers
summary: Initiate A Transfer
description: >-
Send funds from your Payaza account to a bank account or mobile wallet.
Supports single and bulk payouts. See the full [Transfers
guide](/guides/transfers) for a step-by-step walkthrough.
**Before you call this endpoint:**
- Your server IP address must be whitelisted on the Payaza Dashboard
under **Settings → Developers → IP Whitelisting** (live environment
only).
- Your transaction PIN must be set up on the dashboard under **Settings
→ Profile → Security**.
- The `account_reference` is retrieved from the [View Payaza Account
Details](/api-reference/payaza-account/view-payaza-account-details)
endpoint.
- Bank codes for each supported country are available here
- Cross-border payouts outside Nigeria are not enabled by default —
email [support@payaza.africa](mailto:support@payaza.africa) to activate
this on your account.
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/initiateATransferRequest'
- $ref: '#/components/schemas/initiateAEurTransferRequest'
examples:
transfer:
summary: Initiate A Transfer
value:
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
xafTransfer:
summary: Initiate A Transfer(XAF)
value:
transaction_type: mobile_money
service_payload:
payout_amount: 300
transaction_pin: 301938
account_reference: '9010000009'
currency: XAF
country: CMR
payout_beneficiaries:
- credit_amount: 100
account_number: '237920706731'
account_name: John Doe
bank_code: MTNCMR
narration: Test
transaction_reference: TD930012x4
sender:
sender_name: Jane Doe
sender_id: ''
sender_phone_number: '01234595'
sender_address: 123, Ace Street
dial_code: '237'
eurTransfer:
summary: Initiate A Transfer(EUR)
value:
transaction_type: sepa
service_payload:
payout_amount: 300
transaction_pin: 1987
account_reference: '88980086362'
country: NGA
currency: EUR
payout_beneficiaries:
- destination_country: NGA
bank_name: Prune
credit_amount: 300
account_number: '8185003687'
account_name: John Doe
bank_code: ARPYGB21XXX
narration: Test
transaction_reference: TDd9frfk
sender:
sender_name: Jane Doe
sender_id: '32'
sender_phone_number: '0124595'
sender_address: 123, Ace Street
responses:
'200':
description: Transfer initiated successfully
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/InitiateATransferResponse'
- $ref: '#/components/schemas/InitiateBulkTransferResponse'
examples:
Single Transfer:
summary: Single Transfer
value:
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'
Bulk Transfer:
summary: Bulk Transfer
value:
response_code: 0
response_content:
message: Processing Transaction
batch_reference: 9M728C1QW5694OP2B098652C33623878
response_code: '09'
'400':
description: Invalid request
security:
- ApiKeyAuth: []
TenantID: []
components:
schemas:
initiateATransferRequest:
title: Initiate A Transfer
type: object
required:
- transaction_type
- service_payload
properties:
transaction_type:
type: string
description: |-
The type of account being transferred to.(Default is NGN).
NGN == “nuban”,
GHS == “mobile_money” or “ghipps”,
UGX == “mobile_money” ,
TZS == “mobile_money” or “tiss”,
KES == “mobile_money” or “kepss”,
XOF == “mobile_money” or “wave”,
XAF == “mobile_money”,
LRD == “mobile_money”,
ZAR == “RTC”
example: nuban
service_payload:
type: object
description: It contains the details of the service payload.
required:
- payout_amount
- transaction_pin
- account_reference
- currency
- payout_beneficiaries
properties:
payout_amount:
type: number
format: double
description: The amount of the transaction.
example: 100
transaction_pin:
type: integer
description: >-
This is the 6 digit transaction PIN that would be created on the
dashboard. This is required to authorise the transfer
example: 490736
account_reference:
type: string
description: >-
The reference of the Payaza account. Please be advised that your
Payaza Account possesses unique account references corresponding
to each currency utilized.(This is available in the **“View
Payaza Account Details”** API response body).
example: '1010000009'
currency:
type: string
description: >-
The transfer currency code.e.g. NGN, GHS, TZS, UGX, KES, XAF,
LRD, ZAR.
example: NGN
country:
type: string
description: >-
The ISO 3166-1 alpha-3 country code e.g. BEN,CIV,CMR. This is
required for XOF payouts
example: NGA
payout_beneficiaries:
type: array
description: It contains the details of the payout beneficiaries
items:
type: object
required:
- credit_amount
- account_number
- account_name
- bank_code
- narration
- transaction_reference
- sender
properties:
credit_amount:
type: number
format: double
description: The amount to be credited to this particular beneficiary.
example: 100
account_number:
type: string
description: >-
This is the account number of the beneficiary.
For “nuban” transfer == 10 digits
For “kepss” transfer == 10 digits
For “mobile_money” == 12 digits for GHA, TZA, UGA, KEN,
CMR and 13 digits for CIV, BEN (starting with the 3-digit
country code)
e,g.Ghana = 233xxxxxxxxx,
Kenya = 254xxxxxxxxx,
Uganda = 256xxxxxxxxx,
Tanzania = 255xxxxxxxxx,
Cameroon = 237xxxxxxxxx,
Benin = 229(01)xxxxxxxx,
Côte d'Ivoire = 225xxxxxxxxxx,
Liberia = 231xxxxxxxxx etc..
example: '9207067319'
account_name:
type: string
description: This is the name of the beneficiary for the transfer.
example: John Doe
bank_code:
type: string
description: This is the beneficiary's bank code.
example: '000013'
narration:
type: string
description: >-
Narration for the payout (This must be 25 characters or
less with no special characters).
example: Test Payment
transaction_reference:
type: string
description: >-
This is the unique identifier generated for each
transaction by the merchant. This must have a minimum
length of 10 characters
example: TD93001234
sender:
type: object
description: It contains the details of the sender.
required:
- sender_name
- sender_phone_number
- sender_address
properties:
sender_name:
type: string
description: Name of the sender.
example: Jane Doe
sender_id:
type: string
description: Unique ID of sender.
example: ''
sender_phone_number:
type: string
description: Phone number of the sender.
example: '01234595'
sender_address:
type: string
description: Address of the sender.
example: 123, Ace Street
dial_code:
type: string
description: >-
The country code for Cameroon. This is required for
XAF Payouts.
example: '237'
initiateAEurTransferRequest:
title: Initiate A EUR Transfer
type: object
required:
- transaction_type
- service_payload
properties:
transaction_type:
type: string
description: The type of account being transferred to. **EUR** == “sepa”.
example: sepa
service_payload:
type: object
description: It contains the details of the service payload.
required:
- payout_amount
- transaction_pin
- account_reference
- currency
- payout_beneficiaries
properties:
payout_amount:
type: number
description: The amount of the transaction.
example: 300
transaction_pin:
type: integer
description: This is the merchant's unique transaction pin.
example: 198731
account_reference:
type: string
description: >-
The reference of the Payaza account. Please be advised that your
Payaza Account possesses unique account references corresponding
to each currency utilized.(This is available in the **“View
Payaza Account Details”** API response body).
example: '88980086362'
country:
type: string
description: The country code..
example: NGA
currency:
type: string
description: The currency code.
example: EUR
payout_beneficiaries:
type: array
description: It contains the details of the payout beneficiaries.
items:
type: object
required:
- destination_country
- bank_name
- credit_amount
- account_number
- account_name
- bank_code
- narration
- transaction_reference
- sender
properties:
destination_country:
type: string
description: The beneficiary's country code.
example: NGA
bank_name:
type: string
description: The name of the beneficiary's bank.
example: Prune
credit_amount:
type: number
description: The amount to be credited to this particular beneficiary.
example: 300
account_number:
type: string
description: This is the account number of the beneficiary.
example: '8185003687'
account_name:
type: string
description: This is the name of the beneficiary for the transfer.
example: John Doe
bank_code:
type: string
description: >-
This is the beneficiary's bank code. It would be in the
format of a SWIFT/BIC number. It would be in the format
AAAABBCC123 i.e.
AAAA = **4 Letters representing the bank**,
BB = **2 Letters representing the country code the bank is
in**,
CC= **2 characters showing the location code**,
123= **3 Digits specifying a particular branch, 'XXX'
represents the Bank's Head Office**.
example: ARPYGB21XXX
narration:
type: string
description: >-
Narration for the payout (This must be 25 characters or
less with no special characters).
example: Test
transaction_reference:
type: string
description: >-
This is the unique identifier generated for each
transaction by the merchant. This must have a minimum
length of 10 characters
example: TDd9frfk
sender:
type: object
description: Details of the sender.
required:
- sender_name
- sender_phone_number
- sender_address
properties:
sender_name:
type: string
description: The name of the sender
example: Jane Doe
sender_id:
type: string
description: The unique identifier of the sender
example: '32'
sender_phone_number:
type: string
description: The phone number of the sender
example: '0124595'
sender_address:
type: string
description: The sender's address
example: 123, Ace Street
InitiateATransferResponse:
title: Transfer Response
type: object
properties:
response_code:
type: integer
response_message:
type: string
response_content:
type: object
properties:
transaction_status:
type: string
amount:
type: number
response_status:
type: string
InitiateBulkTransferResponse:
title: Bulk Transfer Response
type: object
properties:
response_code:
type: integer
response_content:
type: object
properties:
message:
type: string
batch_reference:
type: string
response_code:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: Payaza {{Public API Key in Base 64}}
TenantID:
type: apiKey
in: header
name: X-TenantID
description: live or test
ProductID:
type: apiKey
in: header
name: X-ProductID
description: 'default value is ‟app” '
````