Quick start

This guide takes you from a sandbox key to a successful payment, a refund and a verified webhook. It takes about 15 minutes. Run the steps in order in one language; each step uses the ID returned by the one before.

You need:

A VNSwitch sandbox account and its secret API key (dashboard → API keys).
A webhook URL set on your business profile and its payment response hash key (dashboard → Webhooks). For local testing, use any HTTPS tunnel to your machine.
cURL, Node.js 18+, Python 3 with requests, or Java 17+.

export VNSWITCH_API_KEY="<YOUR_API_KEY>"

// export VNSWITCH_API_KEY="<YOUR_API_KEY>" before running
const BASE_URL = "https://sandbox.api.vnswitch.nivc.ai";
const headers = {
  "Content-Type": "application/json",
  "api-key": process.env.VNSWITCH_API_KEY,
};

import os
import requests

BASE_URL = "https://sandbox.api.vnswitch.nivc.ai"
HEADERS = {
    "Content-Type": "application/json",
    "api-key": os.environ["VNSWITCH_API_KEY"],
}

// export VNSWITCH_API_KEY="<YOUR_API_KEY>" before running
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

static final String BASE_URL = "https://sandbox.api.vnswitch.nivc.ai";
static final HttpClient CLIENT = HttpClient.newHttpClient();

static String send(String method, String path, String json) throws Exception {
    HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(BASE_URL + path))
        .header("Content-Type", "application/json")
        .header("api-key", System.getenv("VNSWITCH_API_KEY"));
    b = json == null ? b.method(method, HttpRequest.BodyPublishers.noBody())
                     : b.method(method, HttpRequest.BodyPublishers.ofString(json));
    return CLIENT.send(b.build(), HttpResponse.BodyHandlers.ofString()).body();
}

Step 1: Create a payment

POST /payments

Create a payment for 150,000 VND. VND has no minor unit, so amount is 150000 ( Amounts and currencies). With confirm: false the payment waits for a payment method. Keep the returned payment_id: you use it in every later step.

If customer_id does not exist yet, VNSwitch creates the customer for you.

curl -X POST https://sandbox.api.vnswitch.nivc.ai/payments \
  -H "Content-Type: application/json" \
  -H "api-key: $VNSWITCH_API_KEY" \
  -d '{
    "amount": 150000,
    "currency": "VND",
    "confirm": false,
    "capture_method": "automatic",
    "customer_id": "cus_demo_001",
    "description": "Order #1001",
    "return_url": "https://merchant.example.vn/checkout/return"
  }'

const res = await fetch(`${BASE_URL}/payments`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    amount: 150000,
    currency: "VND",
    confirm: false,
    capture_method: "automatic",
    customer_id: "cus_demo_001",
    description: "Order #1001",
    return_url: "https://merchant.example.vn/checkout/return",
  }),
});
const payment = await res.json();
console.log(payment.payment_id, payment.status);

resp = requests.post(f"{BASE_URL}/payments", headers=HEADERS, json={
    "amount": 150000,
    "currency": "VND",
    "confirm": False,
    "capture_method": "automatic",
    "customer_id": "cus_demo_001",
    "description": "Order #1001",
    "return_url": "https://merchant.example.vn/checkout/return",
})
payment = resp.json()
print(payment["payment_id"], payment["status"])

String payment = send("POST", "/payments", """
    {
      "amount": 150000,
      "currency": "VND",
      "confirm": false,
      "capture_method": "automatic",
      "customer_id": "cus_demo_001",
        "description": "Order #1001",
      "return_url": "https://merchant.example.vn/checkout/return"
    }
    """);
System.out.println(payment);

Response

{
  "payment_id": "pay_8f2c1d9e0a",
  "status": "requires_payment_method",
  "amount": 150000,
  "currency": "VND",
  "customer_id": "cus_demo_001",
  "client_secret": "pay_8f2c1d9e0a_secret_Xk2pQ9rTz4",
  "description": "Order #1001",
  "created": "2026-11-01T08:30:00.000Z"
}

Step 2: Confirm with a test card

POST /payments/{payment_id}/confirm

Attach the test card and authorise the payment. With capture_method: "automatic" the money is captured straight away, so the status becomes succeeded.

Raw card numbers in server requests are fine in the sandbox. In production, sending card data through your servers puts them in PCI DSS scope. Talk to us about hosted card entry before you go live.

If the status is requires_customer_action, the card needs 3-D Secure: send the customer to the URL in next_action ( Redirects and customer actions).

curl -X POST https://sandbox.api.vnswitch.nivc.ai/payments/pay_8f2c1d9e0a/confirm \
  -H "Content-Type: application/json" \
  -H "api-key: $VNSWITCH_API_KEY" \
  -d '{
    "payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
      "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "12",
        "card_exp_year": "2030",
        "card_holder_name": "NGUYEN VAN AN",
        "card_cvc": "123"
      }
    }
  }'

const confirmRes = await fetch(`${BASE_URL}/payments/${payment.payment_id}/confirm`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    payment_method: "card",
    payment_method_type: "credit",
    payment_method_data: {
      card: {
        card_number: "4242424242424242",
        card_exp_month: "12",
        card_exp_year: "2030",
        card_holder_name: "NGUYEN VAN AN",
        card_cvc: "123",
      },
    },
  }),
});
console.log((await confirmRes.json()).status);

resp = requests.post(f"{BASE_URL}/payments/{payment['payment_id']}/confirm",
                     headers=HEADERS, json={
    "payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "12",
            "card_exp_year": "2030",
            "card_holder_name": "NGUYEN VAN AN",
            "card_cvc": "123",
        }
    },
})
print(resp.json()["status"])

String confirmed = send("POST", "/payments/pay_8f2c1d9e0a/confirm", """
    {
      "payment_method": "card",
      "payment_method_type": "credit",
      "payment_method_data": {
        "card": {
          "card_number": "4242424242424242",
          "card_exp_month": "12",
          "card_exp_year": "2030",
          "card_holder_name": "NGUYEN VAN AN",
          "card_cvc": "123"
        }
      }
    }
    """);
System.out.println(confirmed);

Response

{
  "payment_id": "pay_8f2c1d9e0a",
  "status": "succeeded",
  "amount": 150000,
  "amount_received": 150000,
  "currency": "VND",
  "payment_method": "card",
  "payment_method_type": "credit",
  "next_action": null
}

Step 3: Check the payment status

GET /payments/{payment_id}

Your server decides whether an order is paid from this call or from a webhook, never from what the browser says. See Payment lifecycle for every status.

curl https://sandbox.api.vnswitch.nivc.ai/payments/pay_8f2c1d9e0a \
  -H "api-key: $VNSWITCH_API_KEY"

const check = await fetch(`${BASE_URL}/payments/${payment.payment_id}`, { headers });
console.log((await check.json()).status); // "succeeded"

resp = requests.get(f"{BASE_URL}/payments/{payment['payment_id']}", headers=HEADERS)
print(resp.json()["status"])  # "succeeded"

System.out.println(send("GET", "/payments/pay_8f2c1d9e0a", null));

Response

{
  "payment_id": "pay_8f2c1d9e0a",
  "status": "succeeded",
  "amount": 150000,
  "amount_received": 150000,
  "currency": "VND"
}

Step 4: Refund part of the payment

POST /refunds

Refund 50,000 VND of the 150,000 VND payment. If you leave out amount, VNSwitch refunds the full captured amount, so always send it for partial refunds. Refunds can finish later: the status starts as pending and you get a refund_succeeded or refund_failed webhook. See Refunds.

curl -X POST https://sandbox.api.vnswitch.nivc.ai/refunds \
  -H "Content-Type: application/json" \
  -H "api-key: $VNSWITCH_API_KEY" \
  -d '{
    "payment_id": "pay_8f2c1d9e0a",
    "amount": 50000,
    "reason": "Customer returned one item"
  }'

const refundRes = await fetch(`${BASE_URL}/refunds`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    payment_id: payment.payment_id,
    amount: 50000,
    reason: "Customer returned one item",
  }),
});
console.log(await refundRes.json());

resp = requests.post(f"{BASE_URL}/refunds", headers=HEADERS, json={
    "payment_id": payment["payment_id"],
    "amount": 50000,
    "reason": "Customer returned one item",
})
print(resp.json())

String refund = send("POST", "/refunds", """
    {
      "payment_id": "pay_8f2c1d9e0a",
      "amount": 50000,
      "reason": "Customer returned one item"
    }
    """);
System.out.println(refund);

Response

{
  "refund_id": "ref_3b7e5a1c4d",
  "payment_id": "pay_8f2c1d9e0a",
  "amount": 50000,
  "currency": "VND",
  "status": "pending",
  "reason": "Customer returned one item"
}

Step 5: Receive and verify a webhook

When the payment succeeded in Step 2, VNSwitch sent a payment_succeeded event to your webhook URL. Each webhook carries an X-Webhook-Signature-512 header: the lowercase hex HMAC-SHA512 of the raw body, keyed with your payment response hash key.

Read the raw body before parsing it.
Compute the HMAC and compare it in constant time. Reject the request if it does not match.
Reply with a 2xx status quickly, then process the event. Use event_id to ignore duplicates.

Done. You created, confirmed, checked and refunded a payment, and verified a webhook. Next, read Payment lifecycle and Webhooks, then the Go-live checklist.

openssl dgst -sha512 -hmac "<YOUR_PAYMENT_RESPONSE_HASH_KEY>" -hex < body.json

// npm install express
import crypto from "node:crypto";
import express from "express";

const app = express();
const HASH_KEY = process.env.VNSWITCH_PAYMENT_RESPONSE_HASH_KEY;

// Keep the raw body: the signature covers the exact bytes received.
app.post("/webhooks/vnswitch", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha512", HASH_KEY).update(req.body).digest("hex");
  const received = req.get("X-Webhook-Signature-512") || "";
  const ok = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body);
  console.log(event.event_type, event.content.object.payment_id);
  res.status(200).end(); // answer fast, process afterwards
});
app.listen(3000);

import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
HASH_KEY = os.environ["VNSWITCH_PAYMENT_RESPONSE_HASH_KEY"].encode()

@app.post("/webhooks/vnswitch")
def vnswitch_webhook():
    raw = request.get_data()  # exact bytes received
    expected = hmac.new(HASH_KEY, raw, hashlib.sha512).hexdigest()
    received = request.headers.get("X-Webhook-Signature-512", "")
    if not hmac.compare_digest(expected.encode(), received.encode()):
        abort(401)
    event = json.loads(raw)
    print(event["event_type"], event["content"]["object"].get("payment_id"))
    return "", 200

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

// Call this with the raw request body bytes and the X-Webhook-Signature-512 header.
static boolean isValidSignature(byte[] rawBody, String received) throws Exception {
    String key = System.getenv("VNSWITCH_PAYMENT_RESPONSE_HASH_KEY");
    Mac mac = Mac.getInstance("HmacSHA512");
    mac.init(new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA512"));
    StringBuilder expected = new StringBuilder();
    for (byte b : mac.doFinal(rawBody)) {
        expected.append(String.format("%02x", b)); // lowercase hex
    }
    return received != null && MessageDigest.isEqual(
        expected.toString().getBytes(StandardCharsets.UTF_8),
        received.getBytes(StandardCharsets.UTF_8));
}

Webhook body (example)

{
  "merchant_id": "merchant_vn_001",
  "event_id": "evt_01JBX7Q8M2",
  "event_type": "payment_succeeded",
  "content": {
    "type": "payment_details",
    "object": {
      "payment_id": "pay_8f2c1d9e0a",
      "status": "succeeded",
      "amount": 150000,
      "currency": "VND"
    }
  },
  "timestamp": "2026-11-01T08:30:02.000Z"
}

Payment methods

Authentication

Docs

VNSwitch Docs

Title here

Quick start

Step 1: Create a payment

Step 2: Confirm with a test card

Step 3: Check the payment status

Step 4: Refund part of the payment

Step 5: Receive and verify a webhook

Quick start

Step 1: Create a payment#

Step 2: Confirm with a test card#

Step 3: Check the payment status#

Step 4: Refund part of the payment#

Step 5: Receive and verify a webhook#

Step 1: Create a payment

Step 2: Confirm with a test card

Step 3: Check the payment status

Step 4: Refund part of the payment

Step 5: Receive and verify a webhook