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

# Virtual Accounts

> Give each customer a dedicated bank account number to receive payments

A virtual account is a dedicated NUBAN account number tied to one customer. Any transfer into it is credited to your wallet and triggers a [webhook](/api-reference/webhooks).

<Info>
  **Supported bank:** PalmPay. Pass `"bank": "palmpay"` on every request — the `bank` parameter is required even though only one option currently exists.
</Info>

## Create Virtual Account

**POST** `/api/v1/virtual-account/create`

Creates a dedicated virtual bank account for your customer. Set `customer_type` to tell us whether this account is for an individual or a registered business — each uses different identification, and the identity behind the account can't be changed later.

### Body Parameters

<ParamField body="customer_type" default="individual" type="string">
  `individual` or `business`. Controls which fields below are required.
</ParamField>

<ParamField body="email" type="string" required>
  Customer's email address.
</ParamField>

<ParamField body="reference" type="string" required>
  A unique value **you** choose (your order ID or customer ID). See [reference vs. transaction ID](/authentication#reference-vs-transaction-id).
</ParamField>

<ParamField body="bank" type="string" required>
  Bank to use: `palmpay`.
</ParamField>

<Expandable title="Fields when customer_type is individual (default)">
  <ParamField body="first_name" type="string" required>
    Customer's first name.
  </ParamField>

  <ParamField body="last_name" type="string" required>
    Customer's last name.
  </ParamField>

  <ParamField body="bvn" type="string">
    Customer's BVN (11 digits). If omitted, your own KYC BVN is used.
  </ParamField>

  <ParamField body="nin" type="string">
    Customer's NIN (11 digits). If omitted, your own KYC NIN is used.
  </ParamField>
</Expandable>

<Expandable title="Fields when customer_type is business">
  <ParamField body="business_name" type="string" required>
    The business's registered name, as on its CAC certificate.
  </ParamField>

  <ParamField body="cac_number" type="string" required>
    The business's own CAC registration number, starting with `RC` or `BN`. Your own BVN is never used for a business customer — only their `cac_number`.
  </ParamField>
</Expandable>

<Note>
  **Identification used, by `customer_type`:**

  * **individual** (default): `bvn` if provided, else `nin` if provided, else your own KYC BVN, else your own KYC NIN.
  * **business**: always the `cac_number` you send for that business.
</Note>

<CodeGroup>
  ```bash Individual theme={null}
  curl -X POST "https://www.abcmpay.com/api/v1/virtual-account/create" \
    -H "X-Api-Key: your-public-key" \
    -H "X-Api-Secret: your-secret-key" \
    -H "Content-Type: application/json" \
    -d '{
      "customer_type": "individual",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "reference": "ORDER_20260215120000",
      "bank": "palmpay"
  }'
  ```

  ```bash Business theme={null}
  curl -X POST "https://www.abcmpay.com/api/v1/virtual-account/create" \
    -H "X-Api-Key: your-public-key" \
    -H "X-Api-Secret: your-secret-key" \
    -H "Content-Type: application/json" \
    -d '{
      "customer_type": "business",
      "business_name": "Acme Traders Ltd",
      "cac_number": "RC1234567",
      "email": "accounts@acmetraders.com",
      "reference": "ORDER_20260215120000",
      "bank": "palmpay"
  }'
  ```
</CodeGroup>

### Response

```json theme={null}
{
    "success": true,
    "message": "Virtual account created successfully",
    "data": {
        "account_number": "0123456789",
        "account_name": "Your Business - John Doe",
        "bank_name": "PalmPay",
        "customer_name": "John Doe",
        "customer_email": "john@example.com",
        "reference": "ORDER_20260215120000",
        "status": "Enabled",
        "created_at": "2026-02-15T12:00:00Z"
    }
}
```

***

## Get Virtual Account Details

**GET** `/api/v1/virtual-account/{account_number}`

Retrieve details of a specific virtual account.

```bash theme={null}
curl -X GET "https://www.abcmpay.com/api/v1/virtual-account/0123456789" \
  -H "X-Api-Key: your-public-key" \
  -H "X-Api-Secret: your-secret-key"
```

```json Response theme={null}
{
    "success": true,
    "data": {
        "account_number": "0123456789",
        "account_name": "Your Business - John Doe",
        "bank_name": "PalmPay",
        "customer_name": "John Doe",
        "customer_email": "john@example.com",
        "reference": "ORDER_20260215120000",
        "status": "Enabled",
        "created_at": "2026-02-15T12:00:00Z"
    }
}
```

***

## List All Virtual Accounts

**GET** `/api/v1/virtual-accounts`

Get a list of all virtual accounts created by your business.

```json Response theme={null}
{
    "success": true,
    "data": [
        {
            "account_number": "0123456789",
            "account_name": "Your Business - John Doe",
            "bank_name": "PalmPay",
            "customer_name": "John Doe",
            "customer_email": "john@example.com",
            "reference": "ORDER_20260215120000",
            "status": "Enabled",
            "created_at": "2026-02-15T12:00:00Z"
        }
    ]
}
```

***

## Check Transaction Status

**GET** `/api/v1/transaction/status?reference={reference}`

Check the status of a transaction using the `reference` you sent when it happened.

```bash theme={null}
curl -X GET "https://www.abcmpay.com/api/v1/transaction/status?reference=ORDER_20260215120000" \
  -H "X-Api-Key: your-public-key" \
  -H "X-Api-Secret: your-secret-key"
```

```json Response theme={null}
{
    "success": true,
    "data": {
        "reference": "ORDER_20260215120000",
        "amount": 10000,
        "currency": "NGN",
        "status": "success",
        "payer_name": "Customer Name",
        "payer_bank": "ACCESS BANK",
        "virtual_account": "0123456789",
        "created_at": "2026-02-15T14:30:00Z"
    }
}
```

| Status       | Meaning                            |
| ------------ | ---------------------------------- |
| `pending`    | Transaction is pending processing  |
| `processing` | Transaction is being processed     |
| `success`    | Transaction completed successfully |
| `failed`     | Transaction failed                 |