Customers & Virtual Accounts

Create customer records with dedicated virtual accounts via the Atlas API, update customer details, handle virtual account deposits via webhooks, and manage customer blacklisting.

You can create virtual accounts for your customers on Atlas. These virtual accounts work like bank accounts, each customer you create one for will receive a unique account number and account name (matching their name). When a customer deposits money into their virtual account, your Atlas account receives the funds and Atlas sends you a webhook to notify your backend of the transaction. Using the data from the webhook, you can update your customer records accordingly.

Learn how webhooks work on Atlas on our webhook guide.

Creating a virtual account

There are two types of customer virtual accounts, controlled by the type field:

Individual (type: "individual") - Requires first_name and last_name in addition to email and phone. The resolved account name uses the customer's name.
Business (type: "business") - Only requires email and phone. The resolved account name displays your business name.

To create a virtual account for a customer, make a request to the create new customer endpoint with the customer's email, phone, type, and has_wallet set to true. For individual customers, also include first_name and `last_name.

curl -X POST "https://atlas.tryduplo.com/api/v1/customer" \
  -H "Authorization: Bearer your_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{\n    "first_name": "John",\n    "last_name": "Doe",\n    "email": "john.doe@example.com",\n    "phone": "+2347012345678",\n    "type": "individual",\n    "has_wallet": true\n  }'

Tip

For added security, consider encrypting this request before sending it to the Atlas API.

On a successful request, you'll get a response similar to the one below:

{
  "requestId": "abcd1234-5678-90ef-ghij-1234567890kl",
  "requestTimestamp": "2025-07-16 09:15:00",
  "message": "Customer created successfully",
  "statusCode": 201,
  "data": {
    "id": "019a1639-ce25-70b7-ab20-16fcb2bac023",
    "firstName": "Laurianne",
    "lastName": "MacGyver",
    "email": "Bianka_Cole@yahoo.com",
    "phoneNumber": "+2347009069130",
    "reference": "dp_cust_iovciv7ovnw1qcx",
    "businessState": "TEST",
    "isBlacklisted": false,
    "hasWallet": true,
    "wallet": {
      "wallet_id": "469e02df-43ae-46e7-8ebc-0b0ab5e19303",
      "currency": "NGN",
      "wallet_type": "customer",
      "account_number": "6754358291",
      "account_name": "dp_pay/wilkinson, sawayn and sch/wilkinson, sawayn and schroeder ltd",
      "provider": "Zenith Bank"
    },
    "status": "ACTIVE",
    "source": "DASHBOARD",
    "createdAt": "2025-10-24 12:37:58"
  }
}

Info

The has_wallet field is a boolean that defaults to false. To create a virtual account along with the customer, you need to set this field to true in your payload.

The details for the customer's virtual account are contained under the wallet property, where account_number refers to the customer's virtual account number, account_name is the name associated with the virtual account, and provider is the bank associated with the virtual account.

Retrieving customer information

You can retrieve information about a specific customer using the Get Customer by Reference endpoint:

curl -X GET "https://atlas.tryduplo.com/api/v1/customer/dp_cust_iovciv7ovnw1qcx" \
  -H "Authorization: Bearer your_api_key" \
  -H "Accept: application/json"

To retrieve a list of all your customers, use the Get Customer List endpoint. This endpoint supports pagination and filtering:

curl -X GET "https://atlas.tryduplo.com/api/v1/customer?limit=10&page=1" \
  -H "Authorization: Bearer your_api_key" \
  -H "Accept: application/json"

Updating customer information

You can update outdated or inaccurate customer information using the Update Customer by Reference endpoint. To call this endpoint, you need the customer's reference ID, available from the customer creation response or the Get Customer List endpoint.

For example, to update a customer's name and phone number:

curl -X POST "https://atlas.tryduplo.com/api/v1/customer/dp_cust_iovciv7ovnw1qcx" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{\n    "first_name": "Jane",\n    "last_name": "Smith",\n    "phone": "+2347098765432"\n  }'

You can only update a customer's first_name, last_name, and phone.

Blacklisting a customer

Blacklisting prevents a customer from performing transactions through their virtual account. This is useful for handling fraudulent activity or enforcing compliance requirements. When a customer is blacklisted, any deposits to their virtual account will be automatically reversed.

To blacklist a customer, use the Blacklist Customer endpoint with the customer's reference ID:

curl -X POST "https://atlas.tryduplo.com/api/v1/customer/blacklist" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{\n    "reference": "dp_cust_iovciv7ovnw1qcx"\n  }'

You'll receive a response confirming the blacklist status:

{
  "requestId": "abcd1234-5678-90ef-ghij-1234567890kl",
  "requestTimestamp": "2025-07-16 09:15:00",
  "message": "Customer has been blacklisted.",
  "statusCode": 200,
  "data": {
    "id": "019a1639-ce25-70b7-ab20-16fcb2bac023",
    "firstName": "Laurianne",
    "lastName": "MacGyver",
    "email": "Bianka_Cole@yahoo.com",
    "phoneNumber": "+2347009069130",
    "reference": "dp_cust_iovciv7ovnw1qcx",
    "businessState": "TEST",
    "isBlacklisted": true,
    "hasWallet": true,
    "wallet": {
      "wallet_id": "469e02df-43ae-46e7-8ebc-0b0ab5e19303",
      "currency": "NGN",
      "wallet_type": "customer",
      "account_number": "6754358291",
      "account_name": "dp_pay/wilkinson, sawayn and sch/wilkinson, sawayn and schroeder ltd",
      "provider": "duplo"
    },
    "status": "ACTIVE",
    "source": "API",
    "createdAt": "2025-10-24 12:37:58"
  }
}

To remove a customer from the blacklist, use the Activate Customer endpoint with the customer's reference ID:

curl -X POST "https://atlas.tryduplo.com/api/v1/customer/activate" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{\n    "reference": "dp_cust_iovciv7ovnw1qcx"\n  }'

On success, the response returns the updated customer object with isBlacklisted set to false.

Note

Blacklisting a customer only prevents them from making transactions using the blacklisted customer account. Atlas has no control over malicious customers who create new customer accounts using different details.

Handling virtual account deposits

When a customer deposits money into their virtual account, Atlas sends a webhook to your configured endpoint. The webhook payload includes transaction details that allow you to credit the customer's account on your system:

Use the customer_reference to identify which customer made the deposit, and the amount to update their balance in your system. Always verify the webhook to ensure it came from Atlas.