Charge a wallet by scanned QR token

Debits the cardholder’s wallet by amountMNT and records the transaction. The scanned token’s nonce is rotated in the same database transaction as the debit, so the token you just charged is dead the instant the charge commits — a second attempt with the same token returns 409.

The merchant and terminal are taken from the authenticated credential and are never read from the request body. Send the barcode payload exactly as scanned.

The response always reports vatStatus: "pending": the VAT receipt is minted out-of-band and attached to the transaction later. Poll GET /v1/transactions to learn the receipt number.

POST /v1/transactions/charge-by-token

Charge a wallet by scanned QR token

cURL

curl --request POST \
  --url https://api.vibepay.mn/v1/transactions/charge-by-token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "qrToken": "vqr_AXk9Lm0pQr2sTu4vWx6yZa8bCd0eFg2h.Ij4kLm6nOp8qRs0t",
  "amountMNT": 12500
}
'

201

Example

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

Authorizations

Authorization · string · header · required

Per-terminal HTTP Basic credentials, issued in the Vibepay merchant dashboard under Terminals. The username starts with term_ and the password with vpt_. Every authentication failure — missing header, unknown username, wrong password, suspended terminal — returns the same 401, so the response can never be used to discover valid usernames.

Headers

Idempotency-Key · string

A unique key for this checkout attempt, reused across every network retry of that same attempt so a timeout cannot double-charge. Omitting the header is allowed and turns retry collapsing off. Sending a blank or whitespace-only value is rejected with 400 — that reads as idempotency being implemented while silently disabled. Keys are scoped per merchant, not per terminal.

Required string length: 1 - 255

Body

application/json

Unknown fields are rejected with 400. This surface spells the amount amountMNT with an uppercase suffix; amountMnt is an unknown field and will fail rather than be read as zero.

qrToken · string · required

The barcode payload scanned from the cardholder's wallet pass, passed through byte for byte. Always begins with vqr_. Single-use: it stops working the moment a charge against it commits.

Pattern: ^vqr_

Example:

"vqr_AXk9Lm0pQr2sTu4vWx6yZa8bCd0eFg2h.Ij4kLm6nOp8qRs0t"

amountMNT · integer<int64> · required

Amount in whole Mongolian tugrik. There are no minor units — ₮1,500 is 1500. Must be positive and no greater than 1,000,000 per charge.

Required range: 1 <= x <= 1000000

Example:

12500

Response

201

application/json

Charge approved and committed. The wallet has been debited and the VAT receipt is queued.

The projection a terminal sees. It deliberately omits the wallet, card, employer and merchant identifiers: a device handled by cashiers carries no more customer-identifying data than it needs.

id · string · required

Transaction identifier. Store this — it is the only handle for a later reversal.

Example:

"tx_01k2y7v9j0e8ra7cx3mbq4d5nf"

amountMNT · integer<int64> · required

Amount in whole tugrik, always positive. A reversal does not negate it; status carries that instead.

Example:

12500

status · enum<string> · required

COMPLETED for a live charge, REVERSED once it has been refunded.

Available options: COMPLETED, REVERSED

Example:

"COMPLETED"

type · enum<string> · required

CHARGE is the only type a terminal creates. CREDIT (an employer top-up) and RECLAIM (a leaver's unspent balance being swept) exist elsewhere in the system and are never reversible from a terminal.

Available options: CHARGE, CREDIT, RECLAIM

Example:

"CHARGE"

vatReceiptID · string · required

The Mongolian VAT receipt number (ДДТД) once the tax authority has issued it. Empty on a fresh charge, because issuance is asynchronous. Retained after a reversal as the historical record.

Example:

""

createdAt · string<date-time> · required

When the transaction committed, as an RFC 3339 timestamp in UTC.

Example:

"2026-08-18T09:14:22.481739Z"

vatStatus · enum<string>

Where the charge sits in the VAT pipeline. Present only on a CHARGE. pending means the receipt is queued, issued means vatReceiptID is populated, and voided means the charge was reversed and its receipt cancelled.

Available options: pending, issued, voided

Example:

"pending"

terminalID · string

The terminal that took the payment. Omitted on transactions created outside a terminal.

Example:

"ter_01k2y7v8t5f3s9wq1mzd7b6cxa"