Create transfer

Create a bank transfer using a previously resolved recipientCode. Transfers are debited from a Pasteaza wallet/source account.

Resolve the recipient account first. Pasteaza returns a reusable recipientCode that you can use for one or more transfers to the same recipient.

Endpoint

POST /v1/disbursements/bank-transfer

Headers

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: 8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388

Request body

Field	Type	Required	Description
`recipientCode`	string	Yes	Reusable recipient code returned by the Resolve Account endpoint.
`sourceAccountNumber`	string	No	Pasteaza wallet/source account number to debit. If omitted, Pasteaza debits your primary active NGN source account. If you do not have one yet, a default `DEFAULT_NGN_WALLET` source account is created and used.
`amount`	integer	Yes	Amount to send in kobo.
`narration`	string	No	Transfer narration shown to the recipient.
`merchantReference`	string	No	Your internal transfer reference.
`metadata`	object	No	Additional merchant data.

sourceAccountNumber identifies the Pasteaza wallet/source account balance that should fund the transfer. It is not the recipient’s bank account and it is not sent to the banking provider as the live debit account. For live transfers, Pasteaza uses its configured payout debit account with the provider while tracking the merchant-facing debit against your selected Pasteaza source account.

Example request

curl https://api.oyapasteaza.com/v1/disbursements/bank-transfer \
  -X POST \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388" \
  -d '{
    "recipientCode": "rcp_7hK2j9xLmQ4",
    "sourceAccountNumber": "DEFAULT_NGN_WALLET",
    "amount": 500000,
    "narration": "Vendor payout",
    "merchantReference": "PAYOUT_12345",
    "metadata": {}
  }'

Successful response

{
  "status": true,
  "message": "Transfer created successfully.",
  "data": {
    "reference": "pst_trf_01JABCXYZ",
    "merchantReference": "PAYOUT_12345",
    "sourceAccountNumber": "DEFAULT_NGN_WALLET",
    "amount": 500000,
    "status": "processing",
    "recipient": {
      "recipientCode": "rcp_7hK2j9xLmQ4",
      "accountNumber": "1234567890",
      "accountName": "JOHN DOE",
      "bank": {
        "code": "044",
        "name": "Access Bank Plc"
      }
    },
    "createdAt": "2026-06-11T14:30:00Z",
    "updatedAt": "2026-06-11T14:30:00Z"
  }
}

Transfer flow

Resolve the recipient account

Send the account number and bank code to the Resolve Account endpoint.

Store the recipient code

Save the returned recipientCode for future transfers to the same recipient.

Create the transfer

Send the transfer request with recipientCode, amount, an idempotency key, and optionally sourceAccountNumber when you want to debit a specific Pasteaza source account.

Verify the transfer status

Confirm the final outcome using the Verify Transfer Status endpoint.

Notes

Always resolve an account before creating a transfer.
Use recipientCode instead of sending raw bank account details during transfer creation.
A recipientCode can be reused for multiple transfers to the same recipient.
sourceAccountNumber is optional. When provided, it must belong to one of your active Pasteaza wallet/source accounts in the same environment as your API key. If it is invalid, the API returns source_account_not_found.
If sourceAccountNumber is omitted, Pasteaza uses your primary active NGN source account, or creates and uses DEFAULT_NGN_WALLET when no primary source account exists.
Use an Idempotency-Key to prevent duplicate transfers. Idempotency is supported for transfer creation.
Transfers are NGN only in V1. Do not send a currency field.
The response includes sourceAccountNumber so you can reconcile which Pasteaza source account was debited.
A created transfer may return processing first.
Check the final status with the Verify Transfer Status endpoint.

Resolve account

Resolve a bank account and generate a recipient code.

Verify transfer status

Check the final status of a transfer.

Getting Started

Collections

Disbursements

Endpoint

Headers

Request body

Example request

Successful response

Transfer flow

Notes

Resolve account

Verify transfer status

​Endpoint

​Headers

​Request body

​Example request

​Successful response

​Transfer flow

​Notes

​Related guides

Resolve account

Verify transfer status

Endpoint

Headers

Request body

Example request

Successful response

Transfer flow

Notes

Related guides