Payment methods

Use these operations to find out which payment methods a customer can use, and to manage the methods a customer has saved.

A saved payment method is stored by VNSwitch. Your systems only ever see a reference to it (payment_method_id, or a short-lived payment_token) and masked details such as the last four card digits. Full card numbers and CVCs never pass through your server when you pay with a saved method, which keeps most of your systems out of card-data scope.

See Saved payment methods and recurring payments for how methods get saved and how to charge them.

List available payment methods

Returns the payment methods enabled on your account, filtered by amount, currency, country and other criteria. Call it before showing a checkout so you only offer methods that will work.

GET /account/payment_methods

Authentication: secret API key, or publishable key together with the payment’s client_secret (see Authentication).

There are two ways to call it:

From your server with the secret API key. Do not send client_secret; the request is rejected if you do. The result covers your account, narrowed by the filters you pass.
From the browser or app with <YOUR_PUBLISHABLE_KEY> in the api-key header and the payment’s client_secret as a query parameter (it is required in this mode). The result is tailored to that payment’s amount, currency and customer.

Query parameters

Parameter	Type	Required	Description
`client_secret`	string	With publishable key	The `client_secret` of a payment. Required with the publishable key, not allowed with the secret key.
`amount`	integer	No	Amount in minor units. For VND, `150000` means 150,000 VND.
`accepted_currencies`	array of strings	No	ISO 4217 currency codes, for example `VND`.
`accepted_countries`	array of strings	No	ISO 3166-1 alpha-2 country codes, for example `VN`.
`recurring_enabled`	boolean	No	`true` to return only methods that can be used for recurring payments.
`installment_payment_enabled`	boolean	No	`true` to return only methods that support instalments.
`card_networks`	array of strings	No	Card networks to include, for example `Visa`, `Mastercard`, `JCB`.
`limit`	integer	No	Maximum number of recently used methods to consider.

Example request

curl -X GET "https://sandbox.api.vnswitch.nivc.ai/account/payment_methods?amount=150000&accepted_currencies=VND&accepted_countries=VN" \
  -H "api-key: <YOUR_API_KEY>"

const params = new URLSearchParams({
  amount: "150000",
  accepted_currencies: "VND",
  accepted_countries: "VN",
});
const res = await fetch(
  `https://sandbox.api.vnswitch.nivc.ai/account/payment_methods?${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/account/payment_methods",
    headers={"api-key": os.environ["VNSWITCH_API_KEY"]},
    params={"amount": 150000, "accepted_currencies": "VND", "accepted_countries": "VN"},
)
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/account/payment_methods"
        + "?amount=150000&accepted_currencies=VND&accepted_countries=VN"))
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "redirect_url": "https://merchant.example.vn/checkout/return",
  "currency": "VND",
  "payment_methods": [
    {
      "payment_method": "card",
      "payment_method_types": [
        {
          "payment_method_type": "credit",
          "customer_acceptance_support": "supported"
        },
        {
          "payment_method_type": "debit",
          "customer_acceptance_support": "supported"
        }
      ]
    }
  ],
  "mandate_payment": null,
  "merchant_name": "Merchant Demo",
  "show_surcharge_breakup_screen": false,
  "payment_type": "normal",
  "request_external_three_ds_authentication": false,
  "is_tax_calculation_enabled": false,
  "sdk_next_action": { "next_action": "confirm" },
  "is_guest_customer": false
}

Response

Field	Type	Description
`currency`	string	Currency of the payment.
`payment_methods`	array	One entry per `payment_method` (for example `card`, `wallet`, `bank_transfer`), each with its `payment_method_types`.
`payment_methods[].payment_method_types[].payment_method_type`	string	The specific method, for example `credit`, `debit`, `momo` or `viet_qr`.
`payment_methods[].payment_method_types[].customer_acceptance_support`	string	Whether the method can be saved for later: `supported`, `partially_supported` or `unsupported`. Use it to decide whether to show a “save my details” option.
`payment_methods[].payment_method_types[].required_fields`	object	Fields you must collect for this method, when any.
`mandate_payment`	object	Mandate details when the payment sets up a mandate, otherwise `null`.
`payment_type`	string	`normal`, `new_mandate`, `setup_mandate`, `recurring_mandate` or `installment`.
`is_guest_customer`	boolean	`true` when the payment has no customer attached.

Vietnamese methods such as momo and viet_qr appear only when a provider for them is enabled on your account. Availability depends on the payment providers enabled for your account. Contact info@nivc.ai.

List customer payment methods

Returns the payment methods a customer has saved, most recently used first. Use it to show “pay with your saved card” options at checkout.

GET /customers/{customer_id}/payment_methods

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

Path parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	The customer’s ID, for example `cus_demo_001`.

Query parameters

The same filters as List available payment methods are accepted: amount, accepted_currencies, accepted_countries, recurring_enabled, installment_payment_enabled, card_networks and limit.

Example request

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

const res = await fetch(
  "https://sandbox.api.vnswitch.nivc.ai/customers/cus_demo_001/payment_methods",
  { 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/payment_methods",
    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/payment_methods"))
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "customer_payment_methods": [
    {
      "payment_token": "1d6e8a2c-5b3f-4c71-9e0a-7f2b4c8d9e13",
      "payment_method_id": "pm_5d1c9a7e3b",
      "customer_id": "cus_demo_001",
      "payment_method": "card",
      "payment_method_type": "credit",
      "recurring_enabled": true,
      "card": {
        "scheme": "Visa",
        "issuer_country": null,
        "last4_digits": "4242",
        "expiry_month": "12",
        "expiry_year": "2030",
        "card_holder_name": "NGUYEN VAN AN",
        "card_fingerprint": null,
        "nick_name": "Thẻ chính",
        "card_network": "Visa",
        "card_isin": "424242",
        "card_type": "CREDIT",
        "saved_to_locker": true
      },
      "created": "2026-11-01T08:20:11.000Z",
      "requires_cvv": true,
      "last_used_at": "2026-11-01T08:20:11.000Z",
      "default_payment_method_set": true
    }
  ],
  "is_guest_customer": null
}

Response

customer_payment_methods is an array. Each entry has:

Field	Type	Description
`payment_method_id`	string	Permanent ID of the saved method. Use it for merchant-initiated payments and to delete the method.
`payment_token`	string	Short-lived token for this method. Pass it as `payment_token` on a payment while the customer is at checkout. List again for a fresh token; do not store it.
`payment_method`, `payment_method_type`	string	For example `card` and `credit`.
`card`	object	Masked card details: `last4_digits`, `expiry_month`, `expiry_year`, `card_holder_name`, `card_network`, `card_isin` (first 6 digits), `card_issuer`, `nick_name`. The full number is never returned.
`bank`	object	Masked bank account details (`mask`, `account_holder_name`, `bank_name`) for saved bank methods.
`requires_cvv`	boolean	`true` if the customer must enter the CVC again to pay with this card.
`recurring_enabled`	boolean	Whether the method can be used for recurring payments.
`default_payment_method_set`	boolean	`true` for the customer’s default method.
`last_used_at`	string	When the method was last used (ISO 8601).

Retrieve a payment method

Returns one saved payment method by ID, with masked details.

GET /payment_methods/{method_id}

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

Path parameters

Parameter	Type	Required	Description
`method_id`	string	Yes	The `payment_method_id`, for example `pm_5d1c9a7e3b`.

Example request

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

const res = await fetch(
  "https://sandbox.api.vnswitch.nivc.ai/payment_methods/pm_5d1c9a7e3b",
  { 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/payment_methods/pm_5d1c9a7e3b",
    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/payment_methods/pm_5d1c9a7e3b"))
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "merchant_id": "merchant_demo",
  "customer_id": "cus_demo_001",
  "payment_method_id": "pm_5d1c9a7e3b",
  "payment_method": "card",
  "payment_method_type": "credit",
  "card": {
    "scheme": "Visa",
    "issuer_country": null,
    "last4_digits": "4242",
    "expiry_month": "12",
    "expiry_year": "2030",
    "card_holder_name": "NGUYEN VAN AN",
    "nick_name": "Thẻ chính",
    "card_network": "Visa",
    "card_isin": "424242",
    "card_type": "CREDIT",
    "saved_to_locker": true
  },
  "recurring_enabled": true,
  "installment_payment_enabled": false,
  "metadata": null,
  "created": "2026-11-01T08:20:11.000Z",
  "last_used_at": "2026-11-01T08:20:11.000Z",
  "client_secret": null
}

Response

The payment method: payment_method_id, customer_id, payment_method, payment_method_type, masked card details, recurring_enabled, metadata, created and last_used_at. An unknown ID returns HTTP 404.

Delete a payment method

Deletes a saved payment method. Offer this when a customer removes a card from their account. The method can no longer be used for new payments.

DELETE /payment_methods/{method_id}

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

If the method backs a recurring arrangement, also revoke the mandate so the customer’s provider is told the arrangement has ended.

Path parameters

Parameter	Type	Required	Description
`method_id`	string	Yes	The `payment_method_id` to delete.

Example request

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

const res = await fetch(
  "https://sandbox.api.vnswitch.nivc.ai/payment_methods/pm_5d1c9a7e3b",
  {
    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/payment_methods/pm_5d1c9a7e3b",
    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/payment_methods/pm_5d1c9a7e3b"))
    .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

{
  "payment_method_id": "pm_5d1c9a7e3b",
  "deleted": true
}

Response

Field	Type	Description
`payment_method_id`	string	The ID of the method.
`deleted`	boolean	`true` when the method was deleted.

Errors

Quick start

Docs

VNSwitch Docs

Title here

Payment methods

List available payment methods

Query parameters

Response

List customer payment methods

Path parameters

Query parameters

Response

Retrieve a payment method

Path parameters

Response

Delete a payment method

Path parameters

Response

Payment methods

List available payment methods#

Query parameters#

Response#

List customer payment methods#

Path parameters#

Query parameters#

Response#

Retrieve a payment method#

Path parameters#

Response#

Delete a payment method#

Path parameters#

Response#

List available payment methods

Query parameters

Response

List customer payment methods

Path parameters

Query parameters

Response

Retrieve a payment method

Path parameters

Response

Delete a payment method

Path parameters

Response