Mandates

A mandate is the customer’s permission for you to charge a saved payment method later, without them being present: subscriptions, instalments or top-ups. VNSwitch creates a mandate when a payment carries mandate_data, and you then charge it by passing its ID in recurring_details. The full flow is in Saved payment methods and recurring payments.

Mandate statuses

`status`	Meaning	Can you charge it?
`active`	The mandate is in force.	Yes
`pending`	The mandate is waiting for confirmation from the customer’s provider.	No, wait until it is `active`
`inactive`	The mandate exists but cannot be used at the moment.	No
`revoked`	The mandate was cancelled by you, the customer or their provider. This is final.	No

A payment that references a mandate which is not active fails with an error saying the mandate is not active. A charge also fails if it would exceed the mandate’s amount limit: for a single_use mandate the amount of each charge, for a multi_use mandate the total charged so far plus the new charge.

Retrieve a mandate

Returns one mandate, including its status and the saved payment method behind it. Check the status before you schedule a charge.

GET /mandates/{mandate_id}

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

Path parameters

Parameter	Type	Required	Description
`mandate_id`	string	Yes	The mandate ID returned as `mandate_id` on the payment that set it up.

Example request

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

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

{
  "mandate_id": "man_7a4e2c9f1d",
  "payment_id": "pay_8f2c1d9e0a",
  "status": "active",
  "payment_method_id": "pm_5d1c9a7e3b",
  "payment_method": "card",
  "payment_method_type": "credit",
  "card": {
    "last4_digits": "4242",
    "card_exp_month": "12",
    "card_exp_year": "2030",
    "card_holder_name": "NGUYEN VAN AN",
    "scheme": "Visa",
    "card_isin": "424242",
    "card_network": "Visa",
    "card_type": "CREDIT",
    "nick_name": null
  },
  "customer_acceptance": {
    "acceptance_type": "online",
    "accepted_at": "2026-11-01T08:20:00Z",
    "online": {
      "ip_address": "203.0.113.10",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
    }
  }
}

Response

Field	Type	Description
`mandate_id`	string	The mandate ID.
`status`	string	`active`, `pending`, `inactive` or `revoked` (see Mandate statuses).
`payment_id`	string	The payment that set up the mandate, when known.
`payment_method_id`	string	The saved payment method the mandate charges.
`payment_method`, `payment_method_type`	string	For example `card` and `credit`.
`card`	object	Masked card details: `last4_digits`, `card_exp_month`, `card_exp_year`, `card_holder_name`, `card_network`, `card_isin`, `card_issuer`.
`customer_acceptance`	object	How and when the customer agreed: `acceptance_type` (`online` or `offline`), `accepted_at`, and for online acceptance the customer’s `ip_address` and `user_agent`.

Revoke a mandate

Cancels a mandate so it can no longer be charged. Call it when the customer cancels a subscription or asks you to stop recurring charges. VNSwitch cancels the mandate with the payment provider first, then marks it revoked. No request body is needed.

POST /mandates/revoke/{mandate_id}

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

Path parameters

Parameter	Type	Required	Description
`mandate_id`	string	Yes	The mandate to revoke.

Example request

curl -X POST https://sandbox.api.vnswitch.nivc.ai/mandates/revoke/man_7a4e2c9f1d \
  -H "api-key: <YOUR_API_KEY>"

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

import os
import requests

resp = requests.post(
    "https://sandbox.api.vnswitch.nivc.ai/mandates/revoke/man_7a4e2c9f1d",
    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/mandates/revoke/man_7a4e2c9f1d"))
    .header("api-key", System.getenv("VNSWITCH_API_KEY"))
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "mandate_id": "man_7a4e2c9f1d",
  "status": "revoked",
  "error_code": null,
  "error_message": null
}

Response

Field	Type	Description
`mandate_id`	string	The mandate ID.
`status`	string	`revoked` on success.
`error_code`, `error_message`	string	Error details from the payment provider, if any. `null` on success.

If the payment provider refuses the cancellation, the request returns an error (see Errors) and the mandate keeps its previous status; retry later or contact info@nivc.ai. Revoking a mandate that is already revoked also fails with an error.

List customer mandates

Returns every mandate of a customer, whatever its status. Use it to show the customer their active subscriptions, or to find the mandates to revoke before you delete the customer.

GET /customers/{customer_id}/mandates

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`.

Example request

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

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

[
  {
    "mandate_id": "man_7a4e2c9f1d",
    "payment_id": "pay_8f2c1d9e0a",
    "status": "active",
    "payment_method_id": "pm_5d1c9a7e3b",
    "payment_method": "card",
    "payment_method_type": "credit",
    "card": {
      "last4_digits": "4242",
      "card_exp_month": "12",
      "card_exp_year": "2030",
      "card_holder_name": "NGUYEN VAN AN",
      "card_network": "Visa"
    },
    "customer_acceptance": {
      "acceptance_type": "online",
      "accepted_at": "2026-11-01T08:20:00Z",
      "online": {
        "ip_address": "203.0.113.10",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
      }
    }
  }
]

Response

A JSON array of mandate objects, as in Retrieve a mandate.

Environments

Redirects and customer actions

Docs

VNSwitch Docs

Title here

Mandates

Mandate statuses

Retrieve a mandate

Path parameters

Response

Revoke a mandate

Path parameters

Response

List customer mandates

Path parameters

Response

Mandates

Mandate statuses#

Retrieve a mandate#

Path parameters#

Response#

Revoke a mandate#

Path parameters#

Response#

List customer mandates#

Path parameters#

Response#

Mandate statuses

Retrieve a mandate

Path parameters

Response

Revoke a mandate

Path parameters

Response

List customer mandates

Path parameters

Response