# 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](https://docs.tryduplo.com/atlas/guides/webhooks).

## [Creating a virtual account](https://docs.tryduplo.com/en/atlas/guides/customers#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](https://docs.tryduplo.com/atlas/customers/createNewCustomer) with the customer's `email`, `phone`, `type`, and `has_wallet` set to `true`. For individual customers, also include `first_name` and `last_name.

```bash
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](https://docs.tryduplo.com/atlas/guides/encryption) before sending it to the Atlas API.

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

```json
{
  "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](https://docs.tryduplo.com/en/atlas/guides/customers#retrieving-customer-information)

You can retrieve information about a specific customer using the [Get Customer by Reference](https://docs.tryduplo.com/atlas/customers/findCustomerByReference) endpoint:

```bash
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](https://docs.tryduplo.com/atlas/customers/getCustomerList) endpoint. This endpoint supports pagination and filtering:

```bash
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](https://docs.tryduplo.com/en/atlas/guides/customers#updating-customer-information)

You can update outdated or inaccurate customer information using the [Update Customer by Reference](https://docs.tryduplo.com/atlas/customers/updateCustomerByReference) endpoint. To call this endpoint, you need the customer's reference ID, available from the customer creation response or the [Get Customer List](https://docs.tryduplo.com/atlas/customers/getCustomerList) endpoint.

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

```bash
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](https://docs.tryduplo.com/en/atlas/guides/customers#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](https://docs.tryduplo.com/atlas/customers/blacklistCustomerByReference) with the customer's reference ID:

```bash
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:

```json
{
  "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](https://docs.tryduplo.com/atlas/customers/activateCustomerByReference) with the customer's reference ID:

```bash
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](https://docs.tryduplo.com/en/atlas/guides/customers#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](https://docs.tryduplo.com/atlas/guides/webhooks#verifying-the-origin-of-an-atlas-webhook) to ensure it came from Atlas.