Create Virtual Accounts with Atlas

This guide walks you through creating a virtual account for your business on Atlas. Once created, the virtual account can be used to receive transfers and track payments.

Prerequisites

To follow this guide, you need the following:

• A verified Atlas account. If you don't have one, you can sign up for free and follow this guide to verify your Atlas account.
• An Atlas API Key. You can fetch your API Key from your Atlas dashboard .
• Configured and setup webhooks on Atlas. See our guide on Configuring and Verifying Atlas webhooks.

Creating a virtual account

To create a virtual account, make a POST request to the Create Virtual Account endpoint with the following fields.

• account_type (required): either single_use or multi_use. A single_use account is time bound and requires expires_at. A multi_use account is permanent and must not carry an expiry.
• account_name (required): the name shown to payers on transfer, between 3 and 250 characters.
• source_reference (required): your own unique reference for the source of this virtual account, between 3 and 250 characters.
• amount (optional): a fixed amount expected on the account. Omit it to accept any amount.
• expires_at (required for single_use, omit for multi_use): formatted as ISO 8601 (YYYY-MM-DD HH:MM:SS), for example 2026-07-20 18:30:00. Must be in the future and within 24 hours.

The request payload differs depending on the account_type:

{
  "account_type": "single_use",
  "account_name": "Acme Store",
  "source_reference": "src_1234567890",
  "amount": 5000,
  "expires_at": "2026-07-20 18:30:00"
}

We recommend encrypting the payload before sending it.

curl -X POST "https://atlas.tryduplo.com/api/v1/virtual-account" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "account_type": "single_use",
    "account_name": "Acme Store",
    "source_reference": "src_1234567890",
    "amount": 5000,
    "expires_at": "2026-07-20 18:30:00"
  }'

You should get a response similar to the one below (the virtual account is extracted from data in the actual response):

{
  "id": "019a1639-ce25-70b7-ab20-16fcb2bac023",
  "businessId": "019a1639-ce25-70b7-ab20-16fcb2bac024",
  "businessState": "TEST",
  "amount": {
    "value": 5000,
    "currency": "NGN",
    "formatted": "NGN5000"
  },
  "reference": "VA_A1B2C3D4E5F6",
  "walletId": "019a1639-ce25-70b7-ab20-16fcb2bac025",
  "sourceReference": "src_1234567890",
  "accountNumber": "1234567890",
  "accountName": "Acme Store",
  "providerName": "globus",
  "accountType": "single_use",
  "status": "active",
  "currency": "NGN",
  "expiresAt": "2026-07-20 18:30:00",
  "createdAt": "2026-07-20 09:15:00"
}

Related guides

• Virtual Accounts
• Customer Management