> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oyapasteaza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create dedicated account

> Create permanent collection accounts for recurring payments.

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](/collections/virtual-accounts/create-virtual-account) section.

## Endpoint

```http theme={null}
POST /v1/collections/dedicated-accounts
```

## Headers

```http theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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.

## Next step

<CardGroup cols={2}>
  <Card title="List dedicated accounts" icon="list" href="/collections/dedicated-accounts/list-dedicated-accounts">
    Retrieve active dedicated accounts for your merchant account.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/getting-started/webhooks">
    Handle payment notifications for dedicated account credits.
  </Card>
</CardGroup>