Charging a wallet

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

string

required

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

integer

required

Whole tugrik. ₮12,500 is 12500.

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"
}

string

required

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

integer

required

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

string

required

COMPLETED on a fresh charge, REVERSED once refunded.

string

required

Always CHARGE for anything you create.

string

required

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

string

Always pending on a fresh charge. See VAT receipts.

string

The terminal that took the payment.

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.

Get started

Taking payments

Going live

The request

Amount rules

The request body is strict

The response

Reading the outcome

A worked integration

Every decline code

Safe retries

​The request

​Amount rules

​The request body is strict

​The response

​Reading the outcome

​A worked integration

Every decline code

Safe retries

The request

Amount rules

The request body is strict

The response

Reading the outcome

A worked integration