> ## 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 virtual account

> Create a temporary virtual account for collecting a bank transfer payment.

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.

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

## Endpoint

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

## Headers

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

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

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

<Steps>
  <Step title="Create the virtual account">
    Send the create request from your backend with the amount and customer details.
  </Step>

  <Step title="Show the account details">
    Display the returned `accountNumber`, `accountName`, `bankName`, `bankCode`, and `amount` to your customer.
  </Step>

  <Step title="Wait for payment">
    Ask the customer to transfer the exact amount before the account expires.
  </Step>

  <Step title="Confirm the status">
    Verify the payment status through the API or process the webhook notification from Pasteaza.
  </Step>
</Steps>

## 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.

## Next step

<CardGroup cols={2}>
  <Card title="Verify virtual account status" icon="circle-check" href="/collections/virtual-accounts/verify-virtual-account-status">
    Check whether a customer has completed the transfer.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/getting-started/webhooks">
    Receive real-time payment notifications from Pasteaza.
  </Card>
</CardGroup>