Refunds

POST /v1/transactions/{txID}/reverse

curl -i -u 'term_a7f3k9d2:vpt_…' -X POST \
  https://api.vibepay.mn/v1/transactions/tx_01k2y7v9j0e8ra7cx3mbq4d5nf/reverse

204 No Content

No request body. No amount. No JSON in the response. The customer’s full original amount is back in their wallet.

The rules

Full amount only

There is no partial refund. If you need to refund part of a sale, reverse the whole charge and take a new one for the correct amount.

Once

A second attempt returns 409. See below — that is not a failure.

30 minutes, same terminal

This route only reverses a charge taken by the calling terminal within the last 30 minutes. Anything older, or taken by another terminal, returns a 403 with a machine code — see below.

Your charges only

Another merchant’s transaction returns 403, indistinguishable from “not a charge”.

It also works while the customer’s wallet is suspended. A benefit being frozen must never trap money that is rightfully theirs.

The 30-minute window

The terminal credential exists to take payments, so this route is scoped to the one refund a till legitimately makes: undoing its own mistake — wrong amount, wrong customer, charged twice — moments after it happened. Everything else is a manager action: a signed-in merchant admin can reverse any charge, from any terminal and any date, in the Vibepay merchant dashboard (Transactions → open the charge → Refund). Outside the window (or from a different terminal) you get a 403 with a JSON body and a stable code, so your POS can tell the cashier what to actually do:

403 — outside the window

{
  "error": "refund window expired — refund this charge from the merchant dashboard",
  "code": "REFUND_WINDOW_EXPIRED"
}

403 — another terminal's charge

{
  "error": "charge was taken by a different terminal — refund it from the merchant dashboard",
  "code": "REFUND_FOREIGN_TERMINAL"
}

Show the instruction, not “forbidden”. Map both codes to a message that points the cashier at the merchant dashboard. The refund is not being refused — it is being routed to someone with the authority to make it.

The plain-text 403 (forbidden) is different: it means the transaction belongs to another merchant or is not a charge, and it carries no code on purpose.

Treat 409 as success

409 Conflict

transaction already reversed

The customer has their money back. Your local record is simply behind.

Converge, do not retry. On a 409, mark the sale refunded in your own system and show the cashier a success message. This is exactly what the official Vibepay POS app does, and it makes a refund button safe to press twice.

r = requests.post(f"{BASE}/v1/transactions/{tx_id}/reverse", auth=AUTH, timeout=30)

if r.status_code == 204 or r.status_code == 409:
    mark_refunded(tx_id)          # both mean the money is back
elif r.status_code == 403:
    code = r.json().get("code") if "json" in r.headers.get("content-type", "") else None
    if code in ("REFUND_WINDOW_EXPIRED", "REFUND_FOREIGN_TERMINAL", "REFUND_FOREIGN_DEVICE"):
        show("Refund this charge from the Vibepay merchant dashboard.")
    else:
        show("This transaction can't be refunded from this terminal.")
elif r.status_code == 404:
    show("Transaction not found — check the receipt number.")
else:
    show("Refund failed, please try again.")

You need the transaction id

tx_01k2y7v9j0e8ra7cx3mbq4d5nf — the id from the charge response. There is no way to refund by QR code, by amount, or by time.

Store the id against your own order record at the moment of sale. If you lose it you can still find the transaction in GET /v1/transactions by amount and timestamp, but that is a manual, error-prone reconciliation in front of a waiting customer.

Printing it on the customer receipt is a good habit. It makes a walk-in refund a lookup instead of a search.

What happens behind the scenes

You get your 204 immediately. Three things then happen asynchronously, none of which can delay or block the refund:

The wallet is credited

Already done by the time you get the 204 — this part is synchronous.

The VAT receipt is cancelled

Vibepay voids the receipt with the tax authority. vatStatus on the transaction moves to voided. You do not need to file anything.

Settlement is adjusted

If the original charge had already been paid out to you in an earlier weekly cycle, the amount is netted off your next payout. Nothing is clawed back from your bank account.

Errors

Status	Body	Meaning
`204`	(empty)	Reversed
`400`	`invalid transaction id`	The id is malformed — check the `tx_` prefix
`401`	`unauthorized`	Credentials dead
`403`	JSON, `code: REFUND_WINDOW_EXPIRED`	More than 30 minutes since the charge — refund it in the merchant dashboard
`403`	JSON, `code: REFUND_FOREIGN_TERMINAL`	Another terminal’s charge — refund it in the merchant dashboard
`403`	JSON, `code: REFUND_FOREIGN_DEVICE`	Same terminal, but the charge was taken by a different enrolled device. Refund it on that device, or in the merchant dashboard. Applies only to device-session (`Bearer`) callers — a Basic-authenticated terminal is scoped to the terminal, not the device.
`403`	`forbidden` (plain text, no code)	Another merchant’s transaction, or not a charge
`404`	`transaction not found`	No such id
`409`	`transaction already reversed`	Already refunded — treat as success
`5xx`	`internal error`	Retry; the operation is safe to repeat

Reversal is naturally idempotent — the worst a repeat can do is return 409 — so it takes no Idempotency-Key and none is needed.

What happens to the tax receipt

How VAT issuance and voiding work, and how to observe them.

Get started

Taking payments

Going live

The rules

Full amount only

Once

30 minutes, same terminal

Your charges only

The 30-minute window

Treat 409 as success

You need the transaction id

What happens behind the scenes

Errors

What happens to the tax receipt

​The rules

Full amount only

Once

30 minutes, same terminal

Your charges only

​The 30-minute window

​Treat 409 as success

​You need the transaction id

​What happens behind the scenes

​Errors

What happens to the tax receipt

The rules

The 30-minute window

Treat 409 as success

You need the transaction id

What happens behind the scenes

Errors