Customers & Virtual Accounts

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 or business 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.

Creating a virtual account

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

• Individual (type: "individual") - An individual account is for a single person. It requires first_name and last_name in addition to email and phone. The resolved account name uses the customer's name.
• Business (type: "business") - A business account is for a company or organization. It requires business_name in addition to email and phone. The first_name and last_name are auto-generated, and the resolved account name displays the business name.

To create a virtual account for a customer, make a request to the create new customer endpoint. Only email and phone are required. Set has_wallet to true to create the virtual account, and use type to indicate whether the customer is an individual or a business. Individual customers also need first_name and last_name; business customers need business_name instead.

The request payload depends on the customer type:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+2347012345678",
  "type": "individual",
  "has_wallet": true
}

The examples below show how to send this request for an individual customer:

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 '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+2347012345678",
    "type": "individual",
    "has_wallet": true
  }'

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

{
  "requestId": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
  "requestTimestamp": "2025-07-16 09:15:00",
  "message": "Customer created successfully",
  "statusCode": 201,
  "data": {
    "id": "019a1639-ce25-70b7-ab20-16fcb2bac023",
    "firstName": "John",
    "lastName": "Doe",
    "type": "individual",
    "businessName": null,
    "email": "john.doe@example.com",
    "phoneNumber": "+2347012345678",
    "reference": "dp_cust_iovciv7ovnw1qcx",
    "businessState": "TEST",
    "isBlacklisted": false,
    "hasWallet": true,
    "wallet": {
      "id": "469e02df-43ae-46e7-8ebc-0b0ab5e19303",
      "walletId": "469e02df-43ae-46e7-8ebc-0b0ab5e19304",
      "businessId": "469e02df-43ae-46e7-8ebc-0b0ab5e19305",
      "currency": "NGN",
      "category": "customer",
      "type": "multi_use",
      "status": "active",
      "accountNumber": "6754358291",
      "accountName": "dp_pay/john doe/john doe",
      "provider": "Zenith Bank"
    },
    "status": "ACTIVE",
    "source": "API",
    "createdAt": "2025-10-24 12:37:58"
  }
}

The details for the customer's virtual account are contained under the wallet property, where accountNumber refers to the customer's virtual account number, accountName 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/find-by-reference/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. It supports pagination (page, limit) and filtering by search, status, reference, sort, startDate, and endDate:

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 PUT "https://atlas.tryduplo.com/api/v1/customer/update-by-reference/dp_cust_iovciv7ovnw1qcx" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+2347098765432"
  }'

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 '{
    "reference": "dp_cust_iovciv7ovnw1qcx"
  }'

You'll receive a response confirming the blacklist status:

{
  "requestId": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
  "requestTimestamp": "2025-07-16 09:15:00",
  "message": "Customer has been blacklisted.",
  "statusCode": 200,
  "data": {
    "id": "019a1639-ce25-70b7-ab20-16fcb2bac023",
    "firstName": "John",
    "lastName": "Doe",
    "type": "individual",
    "businessName": null,
    "email": "john.doe@example.com",
    "phoneNumber": "+2347012345678",
    "reference": "dp_cust_iovciv7ovnw1qcx",
    "businessState": "TEST",
    "isBlacklisted": true,
    "hasWallet": true,
    "wallet": {
      "id": "469e02df-43ae-46e7-8ebc-0b0ab5e19303",
      "walletId": "469e02df-43ae-46e7-8ebc-0b0ab5e19304",
      "businessId": "469e02df-43ae-46e7-8ebc-0b0ab5e19305",
      "currency": "NGN",
      "category": "customer",
      "type": "multi_use",
      "status": "active",
      "accountNumber": "6754358291",
      "accountName": "dp_pay/john doe/john doe",
      "provider": "Zenith Bank"
    },
    "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 '{
    "reference": "dp_cust_iovciv7ovnw1qcx"
  }'

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

Handling virtual account deposits

When a customer deposits money into their virtual account, the amount is settled into your business' wallet and Atlas sends an IN_FLOW_SUCCESS_EVENT webhook to your configured endpoint.

If you need to map deposits to customers, the webhook payload includes transaction details that let you identify which customer made the deposit. The recipient object on the IN_FLOW_SUCCESS_EVENT payload's data identifies the account that received the inflow, which tells you whether the deposit landed in your business wallet or in a customer's dedicated virtual account:

{
  "accountName": "Jane Doe",
  "accountNumber": "3769210226"
}

Check recipient.accountNumber against the dedicated virtual accounts (DVAs) you assigned to your customers:

• If it matches a customer's DVA, credit that customer's account on your system.
• If it does not match any customer's DVA, the funds were paid into your business virtual account, so record it as a deposit into your business wallet.

Always verify the webhook to ensure it came from Atlas.