Customers

A customer object stores the contact details of one of your end users. Attach a customer to a payment with customer_id to save payment methods for that person, set up mandates and see their history in one place.

You choose the customer_id. Use the ID from your own system (for example your user ID) so you never need a lookup table. If you leave it out, VNSwitch generates one.

Send request bodies as UTF-8 JSON. Vietnamese names and addresses keep their diacritics (for example Nguyễn Văn An) and are returned exactly as sent.

Create a customer

Creates a customer. Create the customer before their first payment, or pass the same customer_id on the payment.

POST /customers

Authentication: secret API key (api-key header).

Body parameters

All parameters are optional.

Parameter	Type	Required	Description
`customer_id`	string	No	Your ID for the customer, 1 to 64 characters. Generated by VNSwitch if omitted.
`name`	string	No	Full name, up to 255 characters.
`email`	string	No	Email address.
`phone`	string	No	Phone number without the country code, for example `912345678`.
`phone_country_code`	string	No	Country calling code, for example `+84`.
`description`	string	No	Free text for your own use.
`address`	object	No	Address with `line1`, `line2`, `line3`, `city`, `state`, `zip`, `country` (ISO 3166-1 alpha-2, for example `VN`), `first_name`, `last_name`.
`metadata`	object	No	Up to 50 key-value pairs for your own data. Keys up to 40 characters, values up to 500 characters.
`tax_registration_id`	string	No	The customer’s tax code (mã số thuế), if you need it on invoices.

Example request

curl -X POST https://sandbox.api.vnswitch.nivc.ai/customers \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "api-key: <YOUR_API_KEY>" \
  -d '{
    "customer_id": "cus_demo_001",
    "name": "Nguyễn Văn An",
    "email": "an.nguyen@example.vn",
    "phone": "912345678",
    "phone_country_code": "+84",
    "description": "Khách hàng thân thiết",
    "address": {
      "line1": "12 Lý Thái Tổ",
      "city": "Hà Nội",
      "country": "VN"
    },
    "metadata": { "crm_id": "A-1001" }
  }'

const res = await fetch("https://sandbox.api.vnswitch.nivc.ai/customers", {
  method: "POST",
  headers: {
    "Content-Type": "application/json; charset=utf-8",
    "api-key": process.env.VNSWITCH_API_KEY,
  },
  body: JSON.stringify({
    customer_id: "cus_demo_001",
    name: "Nguyễn Văn An",
    email: "an.nguyen@example.vn",
    phone: "912345678",
    phone_country_code: "+84",
    description: "Khách hàng thân thiết",
    address: { line1: "12 Lý Thái Tổ", city: "Hà Nội", country: "VN" },
    metadata: { crm_id: "A-1001" },
  }),
});
console.log(await res.json());

import os
import requests

resp = requests.post(
    "https://sandbox.api.vnswitch.nivc.ai/customers",
    headers={"api-key": os.environ["VNSWITCH_API_KEY"]},
    json={
        "customer_id": "cus_demo_001",
        "name": "Nguyễn Văn An",
        "email": "an.nguyen@example.vn",
        "phone": "912345678",
        "phone_country_code": "+84",
        "description": "Khách hàng thân thiết",
        "address": {"line1": "12 Lý Thái Tổ", "city": "Hà Nội", "country": "VN"},
        "metadata": {"crm_id": "A-1001"},
    },
)
print(resp.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

String body = """
    {
      "customer_id": "cus_demo_001",
      "name": "Nguyễn Văn An",
      "email": "an.nguyen@example.vn",
      "phone": "912345678",
      "phone_country_code": "+84",
      "description": "Khách hàng thân thiết",
      "address": { "line1": "12 Lý Thái Tổ", "city": "Hà Nội", "country": "VN" },
      "metadata": { "crm_id": "A-1001" }
    }
    """;
HttpRequest request = HttpRequest.newBuilder(
        URI.create("https://sandbox.api.vnswitch.nivc.ai/customers"))
    .header("Content-Type", "application/json; charset=utf-8")
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
System.out.println(response.body());

Response

{
  "customer_id": "cus_demo_001",
  "name": "Nguyễn Văn An",
  "email": "an.nguyen@example.vn",
  "phone": "912345678",
  "phone_country_code": "+84",
  "description": "Khách hàng thân thiết",
  "address": {
    "line1": "12 Lý Thái Tổ",
    "line2": null,
    "line3": null,
    "city": "Hà Nội",
    "state": null,
    "zip": null,
    "country": "VN",
    "first_name": null,
    "last_name": null,
    "origin_zip": null
  },
  "created_at": "2026-11-01T08:15:30.000Z",
  "metadata": { "crm_id": "A-1001" },
  "default_payment_method_id": null,
  "tax_registration_id": null,
  "document_details": null
}

Response

The customer object. customer_id and created_at are always present. default_payment_method_id is set once the customer has a default saved payment method.

Retrieve a customer

Returns one customer by ID.

GET /customers/{customer_id}

Authentication: secret API key (api-key header).

Path parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	The customer’s ID.

Example request

curl -X GET https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001 \
  -H "api-key: <YOUR_API_KEY>"

const res = await fetch(
  "https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001",
  { headers: { "api-key": process.env.VNSWITCH_API_KEY } },
);
console.log(await res.json());

import os
import requests

resp = requests.get(
    "https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001",
    headers={"api-key": os.environ["VNSWITCH_API_KEY"]},
)
print(resp.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

HttpRequest request = HttpRequest.newBuilder(
        URI.create("https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001"))
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
System.out.println(response.body());

Response

{
  "customer_id": "cus_demo_001",
  "name": "Nguyễn Văn An",
  "email": "an.nguyen@example.vn",
  "phone": "912345678",
  "phone_country_code": "+84",
  "description": "Khách hàng thân thiết",
  "address": {
    "line1": "12 Lý Thái Tổ",
    "city": "Hà Nội",
    "country": "VN"
  },
  "created_at": "2026-11-01T08:15:30.000Z",
  "metadata": { "crm_id": "A-1001" },
  "default_payment_method_id": "pm_5d1c9a7e3b",
  "tax_registration_id": null,
  "document_details": null
}

Response

The customer object, as in Create a customer. An unknown ID returns HTTP 404 (see Errors).

Update a customer

Changes the details of an existing customer. Send only the fields you want to change; fields you leave out keep their current value. The customer_id cannot be changed.

POST /customers/{customer_id}

Authentication: secret API key (api-key header).

Path parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	The customer’s ID.

Body parameters

Same fields as Create a customer, except customer_id: name, email, phone, phone_country_code, description, address, metadata, tax_registration_id.

Example request

curl -X POST https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001 \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "api-key: <YOUR_API_KEY>" \
  -d '{
    "email": "an.nguyen.work@example.vn",
    "address": {
      "line1": "45 Nguyễn Huệ",
      "city": "Thành phố Hồ Chí Minh",
      "country": "VN"
    }
  }'

const res = await fetch(
  "https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json; charset=utf-8",
      "api-key": process.env.VNSWITCH_API_KEY,
    },
    body: JSON.stringify({
      email: "an.nguyen.work@example.vn",
      address: {
        line1: "45 Nguyễn Huệ",
        city: "Thành phố Hồ Chí Minh",
        country: "VN",
      },
    }),
  },
);
console.log(await res.json());

import os
import requests

resp = requests.post(
    "https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001",
    headers={"api-key": os.environ["VNSWITCH_API_KEY"]},
    json={
        "email": "an.nguyen.work@example.vn",
        "address": {
            "line1": "45 Nguyễn Huệ",
            "city": "Thành phố Hồ Chí Minh",
            "country": "VN",
        },
    },
)
print(resp.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

String body = """
    {
      "email": "an.nguyen.work@example.vn",
      "address": {
        "line1": "45 Nguyễn Huệ",
        "city": "Thành phố Hồ Chí Minh",
        "country": "VN"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder(
        URI.create("https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001"))
    .header("Content-Type", "application/json; charset=utf-8")
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
System.out.println(response.body());

Response

{
  "customer_id": "cus_demo_001",
  "name": "Nguyễn Văn An",
  "email": "an.nguyen.work@example.vn",
  "phone": "912345678",
  "phone_country_code": "+84",
  "description": "Khách hàng thân thiết",
  "address": {
    "line1": "45 Nguyễn Huệ",
    "city": "Thành phố Hồ Chí Minh",
    "country": "VN"
  },
  "created_at": "2026-11-01T08:15:30.000Z",
  "metadata": { "crm_id": "A-1001" },
  "default_payment_method_id": "pm_5d1c9a7e3b",
  "tax_registration_id": null,
  "document_details": null
}

Response

The updated customer object.

Delete a customer

Deletes a customer’s personal data and their saved payment methods. Use it when a customer closes their account or asks you to erase their data. Past payments stay in your records.

DELETE /customers/{customer_id}

Authentication: secret API key (api-key header).

You cannot delete a customer who has an active mandate. The request fails with HTTP 400 and error code IR_10. Revoke the mandates first, then delete the customer.

Path parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	The customer’s ID.

Example request

curl -X DELETE https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001 \
  -H "api-key: <YOUR_API_KEY>"

const res = await fetch(
  "https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001",
  {
    method: "DELETE",
    headers: { "api-key": process.env.VNSWITCH_API_KEY },
  },
);
console.log(await res.json());

import os
import requests

resp = requests.delete(
    "https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001",
    headers={"api-key": os.environ["VNSWITCH_API_KEY"]},
)
print(resp.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder(
        URI.create("https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001"))
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .DELETE()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "customer_id": "cus_demo_001",
  "customer_deleted": true,
  "address_deleted": true,
  "payment_methods_deleted": true
}

Response

Field	Type	Description
`customer_id`	string	The customer’s ID.
`customer_deleted`	boolean	`true` if the customer’s details were erased.
`address_deleted`	boolean	`true` if the customer’s address was erased.
`payment_methods_deleted`	boolean	`true` if the customer’s saved payment methods were deleted.

List customers

Returns the customers on your account, one page at a time.

GET /customers/list

Authentication: secret API key (api-key header).

Query parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of customers to return. Defaults to 10.
`offset`	integer	No	Number of customers to skip. Defaults to 0.

To read every customer, start with offset=0 and add limit to offset on each call until a page has fewer than limit customers.

Example request

curl -X GET "https://sandbox.api.vnswitch.nivc.ai/customers/list?limit=20&offset=0" \
  -H "api-key: <YOUR_API_KEY>"

const params = new URLSearchParams({ limit: "20", offset: "0" });
const res = await fetch(
  `https://sandbox.api.vnswitch.nivc.ai/customers/list?${params}`,
  { headers: { "api-key": process.env.VNSWITCH_API_KEY } },
);
console.log(await res.json());

import os
import requests

resp = requests.get(
    "https://sandbox.api.vnswitch.nivc.ai/customers/list",
    headers={"api-key": os.environ["VNSWITCH_API_KEY"]},
    params={"limit": 20, "offset": 0},
)
print(resp.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

HttpRequest request = HttpRequest.newBuilder(
        URI.create("https://sandbox.api.vnswitch.nivc.ai/customers/list?limit=20&offset=0"))
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
System.out.println(response.body());

Response

[
  {
    "customer_id": "cus_demo_001",
    "name": "Nguyễn Văn An",
    "email": "an.nguyen@example.vn",
    "phone": "912345678",
    "phone_country_code": "+84",
    "description": "Khách hàng thân thiết",
    "address": null,
    "created_at": "2026-11-01T08:15:30.000Z",
    "metadata": { "crm_id": "A-1001" },
    "default_payment_method_id": "pm_5d1c9a7e3b",
    "tax_registration_id": null,
    "document_details": null
  }
]

Response

A JSON array of customer objects (not wrapped in an object). List results do not include the address; retrieve a customer to get it.

Authentication

Payment lifecycle

Docs

VNSwitch Docs

Title here

Customers

Create a customer

Body parameters

Response

Retrieve a customer

Path parameters

Response

Update a customer

Path parameters

Body parameters

Response

Delete a customer

Path parameters

Response

List customers

Query parameters

Response

Customers

Create a customer#

Body parameters#

Response#

Retrieve a customer#

Path parameters#

Response#

Update a customer#

Path parameters#

Body parameters#

Response#

Delete a customer#

Path parameters#

Response#

List customers#

Query parameters#

Response#

Create a customer

Body parameters

Response

Retrieve a customer

Path parameters

Response

Update a customer

Path parameters

Body parameters

Response

Delete a customer

Path parameters

Response

List customers

Query parameters

Response