Create virtual account

Create a temporary virtual account that your customer can transfer funds into. When payment is received, Pasteaza sends a webhook notification and you can verify the transaction status with the verify virtual account status endpoint.

Create virtual accounts from your backend only. Use your secret key and store the returned reference so you can verify payment status later.

Endpoint

POST /v1/collections/virtual-accounts

Headers

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Request body

Field	Type	Required	Description
`merchantReference`	string	Yes	Your internal transaction or order reference.
`amount`	integer	Yes	Amount to collect in kobo.
`expiresAt`	string	No	ISO date string for when the virtual account should expire. In live mode, expiry must not exceed SafeHaven’s current 24-hour limit.
`metadata`	object	No	Additional merchant data for your records.

Example request

curl https://api.oyapasteaza.com/v1/collections/virtual-accounts \
  -X POST \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "ORDER_12345",
    "amount": 500000,
    "expiresAt": "2026-06-11T14:30:00Z",
    "metadata": {
      "customerId": "cust_001"
    }
  }'

Successful response

{
  "status": true,
  "message": "Virtual account created successfully.",
  "data": {
    "reference": "pstv_01JABCXYZ",
    "accountNumber": "6020009141",
    "accountName": "John Doe",
    "bankCode": "999240",
    "bankName": "SafeHaven MFB",
    "amount": 500000,
    "currency": "NGN",
    "status": "ACTIVE",
    "expiresAt": "2026-06-11T14:30:00.000Z"
  }
}

Integration flow

Create the virtual account

Send the create request from your backend with the amount and customer details.

Show the account details

Display the returned accountNumber, accountName, bankName, bankCode, and amount to your customer.

Wait for payment

Ask the customer to transfer the exact amount before the account expires.

Confirm the status

Verify the payment status through the API or process the webhook notification from Pasteaza.

Notes

Every virtual account is unique to a collection request.
merchantReference is required.
expiresAt is optional. In live mode, it must not exceed SafeHaven’s current 24-hour limit.
The customer should transfer the exact amount generated.
Payments are confirmed automatically through webhooks.
Store the returned reference so you can verify the payment later.

Getting Started

Collections

Disbursements

Endpoint

Headers

Request body

Example request

Successful response

Integration flow

Notes

Next step

Verify virtual account status

Webhooks

​Endpoint

​Headers

​Request body

​Example request

​Successful response

​Integration flow

​Notes

​Next step

Verify virtual account status

Webhooks

Endpoint

Headers

Request body

Example request

Successful response

Integration flow

Notes

Next step