Create dedicated account

Create permanent collection accounts for your customers, invoices, subscriptions, or any other recurring payment. Each dedicated account remains the same, allowing customers to make payments to a dedicated account number whenever they need to. When a payment is received, Pasteaza automatically processes it and notifies your application through webhooks if configured. For creating virtual accounts that expire after a certain period, see the Virtual Accounts section.

Endpoint

POST /v1/collections/dedicated-accounts

Headers

Authorization: Bearer sk_test_xxx
Content-Type: application/json

Request body

Field	Type	Required	Description
`externalReference`	string	Yes	Your unique reference for the customer, invoice, subscription, or internal record.
`metadata`	object	No	Additional merchant data for your records.

externalReference must be unique for your merchant account in the selected environment.

Example request

curl https://api.oyapasteaza.com/v1/collections/dedicated-accounts \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "CUS_001",
    "metadata": {
      "customerId": "123",
      "plan": "premium"
    }
  }'

Successful response

{
  "status": true,
  "message": "Dedicated account created successfully",
  "data": {
    "externalReference": "CUS_001",
    "accountReference": "PZ_DCA_abc123",
    "accountNumber": "8023456789",
    "accountName": "LUCKY TECHNOLOGIES LTD",
    "bankName": "PASTEAZA TEST BANK",
    "status": "ACTIVE",
    "metadata": {
      "customerId": "123",
      "plan": "premium"
    },
    "createdAt": "2026-06-27T10:00:00.000Z"
  }
}

Errors

Code	Meaning
`authentication_failed`	The API key is missing or invalid.
`validation_failed`	`externalReference` is missing, or `metadata` is not a plain object.
`dedicated_account_creation_failed`	The account could not be created. The message explains the reason.

Common creation failures include duplicate externalReference, missing live KYC approval, or no primary active merchant bank account in live mode.

Getting Started

Collections

Disbursements

Create dedicated account

Endpoint

Headers

Request body

Example request

Successful response

Errors

Next step

List dedicated accounts

Webhooks

​Endpoint

​Headers

​Request body

​Example request

​Successful response

​Errors

​Next step

List dedicated accounts

Webhooks

Endpoint

Headers

Request body

Example request

Successful response

Errors

Next step