Create transfer

Create bank transfer

curl --request POST \
  --url https://api.oyapasteaza.com/v1/disbursements/bank-transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "recipientCode": "rcp_7hK2j9xLmQ4",
  "amount": 500000
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({recipientCode: 'rcp_7hK2j9xLmQ4', amount: 500000})
};

fetch('https://api.oyapasteaza.com/v1/disbursements/bank-transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.oyapasteaza.com/v1/disbursements/bank-transfer"

payload = {
    "recipientCode": "rcp_7hK2j9xLmQ4",
    "amount": 500000
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "status": true,
  "message": "<string>",
  "data": {}
}

{
  "status": false,
  "message": "<string>",
  "code": "<string>"
}

POST

disbursements

bank-transfer

Create bank transfer

curl --request POST \
  --url https://api.oyapasteaza.com/v1/disbursements/bank-transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "recipientCode": "rcp_7hK2j9xLmQ4",
  "amount": 500000
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({recipientCode: 'rcp_7hK2j9xLmQ4', amount: 500000})
};

fetch('https://api.oyapasteaza.com/v1/disbursements/bank-transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.oyapasteaza.com/v1/disbursements/bank-transfer"

payload = {
    "recipientCode": "rcp_7hK2j9xLmQ4",
    "amount": 500000
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "status": true,
  "message": "<string>",
  "data": {}
}

{
  "status": false,
  "message": "<string>",
  "code": "<string>"
}

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 account balance that funds the transfer. It is not the recipient’s bank 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.

Authorizations

Authorization

string

header

required

Use an sk_test_... key in the playground. Never enter a live key in shared environments.

Headers

Idempotency-Key

string

required

A unique key for safely retrying this request.

Example:

"2d3d82e4-70b8-4a1e-a78a-69415a601980"

Body

application/json

recipientCode

string

required

Example:

"rcp_7hK2j9xLmQ4"

amount

integer

required

Amount in kobo.

Required range: x >= 100

Example:

500000

sourceAccountNumber

string

narration

string

Example:

"Vendor payment"

merchantReference

string

Example:

"PAYOUT-1001"

metadata

object

Example:

{ "orderId": "ORD-1042" }

Response

Bank transfer created.

status

boolean

required

message

string

required

data

object

required

Getting Started

Collections

Disbursements

Endpoint

Headers

Request body

Example request

Successful response

Transfer flow

Notes

Resolve account

Verify transfer status

Authorizations

Headers

Body

Response

​Endpoint

​Headers

​Request body

​Example request

​Successful response

​Transfer flow

​Notes

​Related guides

Resolve account

Verify transfer status

Authorizations

Headers

Body

Response

Endpoint

Headers

Request body

Example request

Successful response

Transfer flow

Notes

Related guides