Charging a wallet

The charge request field by field, the amount rules, and what the response tells you.

POST /v1/transactions/charge-by-token

The request

curl -u 'term_a7f3k9d2:vpt_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-84271-attempt-1' \
  -d '{"qrToken":"vqr_AXk9Lm0pQr2sTu4vWx6yZa8bCd0eFg2h.Ij4kLm6nOp8qRs0t","amountMNT":12500}' \
  https://api.vibepay.mn/v1/transactions/charge-by-token

qrToken · string · required

The scanned code, byte for byte. See The QR code.

amountMNT · integer · required

Whole tugrik. ₮12,500 is 12500.

Idempotency-Key · string

Optional but strongly recommended. Up to 255 characters. See Idempotency.

That is the entire request. There is no merchant field, no terminal field, and no currency field — merchant and terminal come from your credentials, and the currency is always MNT.

Amount rules

Rule	Value
Unit	Whole tugrik. No minor units exist.
Minimum	1
Maximum per charge	1,000,000

An amount above the per-charge maximum is currently rejected as 400 amount must be positive. The message is misleading — it means positive and within the cap. If you see it on a plainly positive number, check the amount against the ceiling.

The request body is strict

Unknown fields are rejected, not ignored:

Rejected with 400 invalid request body

{ "qrToken": "vqr_…", "amountMnt": 12500 }

amountMnt is not amountMNT. Other Vibepay surfaces spell it in lowercase, and this one deliberately refuses to guess: silently ignoring the field would leave amountMNT at zero and charge the customer nothing while telling you the sale succeeded. Failing loudly is the safer answer.

The body is also capped at 1 MiB and must be valid JSON. All three failures return the same 400 invalid request body.

The response

201 Created

{
  "id": "tx_01k2y7v9j0e8ra7cx3mbq4d5nf",
  "amountMNT": 12500,
  "status": "COMPLETED",
  "type": "CHARGE",
  "vatReceiptID": "",
  "vatStatus": "pending",
  "terminalID": "ter_01k2y7v8t5f3s9wq1mzd7b6cxa",
  "createdAt": "2026-08-18T09:14:22.481739Z"
}

id · string · required

The transaction identifier. Store this. It is the only way to refund the payment later.

amountMNT · integer · required

What was charged. Always positive, even after a reversal — status carries that instead.

status · string · required

COMPLETED on a fresh charge, REVERSED once refunded.

type · string · required

Always CHARGE for anything you create.

vatReceiptID · string · required

The VAT receipt number (ДДТД). Always empty here — the receipt is issued afterwards.

vatStatus · string

Always pending on a fresh charge. See VAT receipts.

terminalID · string

The terminal that took the payment.

createdAt · string

RFC 3339 UTC timestamp of the commit.

The response carries no wallet, card, employer or customer identifier, and it never will. A till handled by cashiers should not hold data it has no use for. If you need a customer reference for your own records, use id.

Reading the outcome

Branch on the HTTP status. Do not pattern-match the message text.

Status	Meaning	Cashier should
201	Approved. Money moved.	Complete the sale
422	Declined for a specific reason — read code	Show the reason, offer another payment method
409	Already spent, or a duplicate	Verify before recharging
400	Your request is malformed	Nothing — this is an integration bug
401	Credentials dead	Re-pair the terminal
429 / 5xx	Unknown outcome	Retry idempotently, or verify

Never treat a timeout or a 5xx as a decline. The charge may have committed before the connection dropped. Retry with the same Idempotency-Key or check GET /v1/transactions — anything else risks charging the customer twice.

A worked integration

import requests, uuid
from requests.auth import HTTPBasicAuth

BASE = "https://api.vibepay.mn"
AUTH = HTTPBasicAuth(TERMINAL_USER, TERMINAL_PASS)

def charge(qr_token: str, amount_mnt: int, idempotency_key: str):
    r = requests.post(
        f"{BASE}/v1/transactions/charge-by-token",
        json={"qrToken": qr_token, "amountMNT": amount_mnt},
        headers={"Idempotency-Key": idempotency_key},
        auth=AUTH,
        timeout=30,
    )

    if r.status_code == 201:
        return "approved", r.json()

    if r.status_code == 422:
        # The only status with a JSON body and a stable code.
        return "declined", r.json()["code"]

    if r.status_code == 409:
        # Already spent or a duplicate — never silently recharge.
        return "verify", r.text.strip()

    if r.status_code in (429, 500, 502, 503, 504):
        # Outcome unknown. Retry with the SAME key, or reconcile.
        return "unknown", r.text.strip()

    r.raise_for_status()

# One key per sale attempt, reused across every retry of that attempt.
status, detail = charge(scanned, 12500, f"order-84271-{uuid.uuid4()}")

Every decline code

What each one means and what to tell the customer.

Safe retries

How the same key collapses a retry into one payment.