VNSwitch Docs Quick start

Amounts and currencies

Every amount you send to VNSwitch, and every amount VNSwitch returns, is an integer in the currency’s minor unit (the smallest unit of that currency). This applies to payment amounts, capture amounts, refunds and payouts alike. Dispute objects are the one exception in format, not in meaning: their amount is a string holding the minor-unit integer (for example "150000"), so parse it as an integer.

curl -X POST https://sandbox.api.vnswitch.nivc.ai/payments \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -d '{ "amount": 150000, "currency": "VND", "confirm": false }'

curl -X POST https://sandbox.api.vnswitch.nivc.ai/payments \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -d '{ "amount": 1050, "currency": "USD", "confirm": false }'
// Decimal places per currency (add the currencies you accept).
const MINOR_DIGITS = { VND: 0, JPY: 0, KRW: 0, USD: 2, EUR: 2, SGD: 2, KWD: 3, BHD: 3 };

// "10.50" + "USD" -> 1050. Works on the decimal string, never on a float.
function toMinorUnits(value, currency) {
  const digits = MINOR_DIGITS[currency];
  if (digits === undefined) throw new Error(`Unsupported currency: ${currency}`);
  const match = /^(\d+)(?:\.(\d+))?$/.exec(value);
  if (!match) throw new Error(`Not a decimal amount: ${value}`);
  const fraction = match[2] ?? "";
  if (fraction.length > digits) {
    throw new Error(`${currency} allows ${digits} decimal place(s): ${value}`);
  }
  const amount = Number(match[1] + fraction.padEnd(digits, "0"));
  if (!Number.isSafeInteger(amount)) throw new Error(`Amount too large: ${value}`);
  return amount;
}

// 1050 + "USD" -> "10.50"
function formatMinorUnits(amount, currency) {
  const digits = MINOR_DIGITS[currency];
  if (digits === 0) return String(amount);
  const text = String(amount).padStart(digits + 1, "0");
  return `${text.slice(0, -digits)}.${text.slice(-digits)}`;
}

console.log(toMinorUnits("150000", "VND")); // 150000
console.log(toMinorUnits("10.50", "USD")); // 1050
console.log(formatMinorUnits(1050, "USD")); // 10.50
console.log(new Intl.NumberFormat("vi-VN", { style: "currency", currency: "VND" })
  .format(150000)); // 150.000 ₫ (display only)

from decimal import Decimal

MINOR_DIGITS = {"VND": 0, "JPY": 0, "KRW": 0, "USD": 2, "EUR": 2, "SGD": 2, "KWD": 3, "BHD": 3}

def to_minor_units(value: str, currency: str) -> int:
    """"10.50" + "USD" -> 1050. Uses Decimal, never float."""
    digits = MINOR_DIGITS[currency]
    scaled = Decimal(value).scaleb(digits)
    if scaled != scaled.to_integral_value():
        raise ValueError(f"{currency} allows {digits} decimal place(s): {value}")
    return int(scaled)

def format_minor_units(amount: int, currency: str) -> str:
    """1050 + "USD" -> "10.50"."""
    digits = MINOR_DIGITS[currency]
    return f"{Decimal(amount).scaleb(-digits):.{digits}f}"

print(to_minor_units("150000", "VND"))  # 150000
print(to_minor_units("10.50", "USD"))  # 1050
print(format_minor_units(1050, "USD"))  # 10.50
import java.math.BigDecimal;
import java.util.Map;

public class Amounts {
    // Decimal places per currency (add the currencies you accept).
    static final Map<String, Integer> MINOR_DIGITS = Map.of(
        "VND", 0, "JPY", 0, "KRW", 0, "USD", 2, "EUR", 2, "SGD", 2, "KWD", 3, "BHD", 3);

    // "10.50" + "USD" -> 1050. Throws if the value has too many decimal places.
    static long toMinorUnits(String value, String currency) {
        int digits = MINOR_DIGITS.get(currency);
        return new BigDecimal(value).movePointRight(digits).longValueExact();
    }

    // 1050 + "USD" -> "10.50"
    static String formatMinorUnits(long amount, String currency) {
        return BigDecimal.valueOf(amount, MINOR_DIGITS.get(currency)).toPlainString();
    }

    public static void main(String[] args) {
        System.out.println(toMinorUnits("150000", "VND")); // 150000
        System.out.println(toMinorUnits("10.50", "USD")); // 1050
        System.out.println(formatMinorUnits(1050, "USD")); // 10.50
    }
}

Minor units and VND

The number of minor units in one major unit depends on the currency:

CurrencyDecimal placesamount you sendMeans
VND0150000150,000 VND
USD2105010.50 USD
KWD315001.500 KWD

VND has no minor unit. The amount is the number of dong: amount: 150000 with currency: "VND" is 150,000 VND. Do not multiply VND amounts by 100.

A common bug is to treat every currency as having two decimal places. For VND that charges the customer 100 times too much: 15000000 is 15,000,000 VND, not 150,000 VND. Always look up the decimal places of the currency before you convert.

The amount field is an integer. A value with a fractional part, such as 150000.5, is not a valid amount and the request is rejected (see Errors).

Currency codes

The currency field takes a three-letter ISO 4217 code in uppercase, for example "VND" or "USD". Which currencies you can actually charge depends on the payment providers enabled for your account.

VNSwitch uses these decimal places:

Decimal placesCurrencies
0BIF, CLP, DJF, GNF, IRR, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF
3BHD, IQD, JOD, KWD, LYD, OMR, TND
4CLF
2All other supported currencies (for example USD, EUR, SGD, THB)

Convert amounts safely

The examples in the code column convert between a decimal string (what a person types or what your order system stores, for example "10.50") and the integer that VNSwitch expects, and back again for display.

  • Never use floating-point numbers for money. 10.50 * 100 in binary floating point can give 1049.9999999999998. Work with integers, a decimal string, or an exact decimal type (Decimal in Python, BigDecimal in Java).
  • Reject values with too many decimal places instead of rounding them silently. "10.505" is not a valid USD amount, and "150000.5" is not a valid VND amount.
  • Store the integer and the currency together. An amount without its currency is ambiguous: 150000 is 150,000 VND but 1,500.00 USD.
  • Keep amounts in minor units end to end. Convert only at the edges: when a person enters an amount and when you show one.
Next
Introduction