> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibepay.mn/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> What the Vibepay Charge API does, who it is for, and how a payment travels through it.

Vibepay is a meal-benefit platform. Employers fund a monthly stipend for each of their staff,
those staff spend it at participating merchants, and Vibepay settles with the merchant weekly and
issues a Mongolian VAT receipt for every single card charge.

This documentation covers the one API you need to take that payment: **the Charge API**. If you
are building a point-of-sale, a kiosk, a self-checkout, or an ordering app that should accept
Vibepay, you are in the right place.

<Note>
  Already using the official Vibepay POS app on a phone or tablet? You do not need this API — the
  app talks to it for you. This is for merchants integrating Vibepay into their own software.
</Note>

## How a payment works

There is no card to swipe and no PIN pad. The cardholder's card lives inside Apple Wallet or
Google Wallet as a pass, and that pass displays a QR code that changes after every payment. Your
terminal scans it and posts it here.

```mermaid theme={null}
sequenceDiagram
    participant C as Cardholder<br/>(wallet pass)
    participant P as Your POS
    participant V as Vibepay Charge API
    participant T as Tax authority

    C->>P: Shows the QR code on their pass
    P->>V: POST /v1/transactions/charge-by-token
    V->>V: Debit wallet + retire the scanned code
    V-->>P: 201 — approved
    P->>C: Hand over the meal
    V-)T: Issue the VAT receipt (asynchronous)
```

The important part of that diagram is the dotted line at the bottom. **The VAT receipt is issued
after the payment, not during it**, so the charge response can never carry a receipt number. That
is a deliberate design decision and it shapes how you should build your integration — see
[VAT receipts](/vat-receipts).

## The whole API

Three endpoints. That is the entire merchant surface.

<CardGroup cols={3}>
  <Card title="Charge" icon="qrcode" href="/charge">
    `POST /v1/transactions/charge-by-token` — scan a code, take the money.
  </Card>

  <Card title="Refund" icon="rotate-left" href="/refunds">
    `POST /v1/transactions/{txID}/reverse` — give all of it back.
  </Card>

  <Card title="History" icon="list" href="/transactions">
    `GET /v1/transactions` — what this terminal has taken.
  </Card>
</CardGroup>

## What to know before you start

<AccordionGroup>
  <Accordion title="Amounts are whole tugrik — there are no minor units" icon="coins">
    ₮1,500 is `1500`, not `150000`. Vibepay has no concept of a fractional tugrik anywhere. If you
    are porting an integration that used cents or *möngö*, this is the first thing to fix.
  </Accordion>

  <Accordion title="This API cannot be called from a browser" icon="shield-halved">
    It sends no CORS headers, so a web page's `fetch()` will be blocked by the browser. Call it
    from your server or from native POS software. This is intentional: your terminal password
    would otherwise have to live in JavaScript that anyone can read.
  </Accordion>

  <Accordion title="Refunds are all-or-nothing" icon="rotate-left">
    You can reverse a charge in full, at any time, once. There is no partial refund, no
    time limit, and no separate void.
  </Accordion>

  <Accordion title="Declines return JSON — every other error returns plain text" icon="triangle-exclamation">
    This trips up most integrations on day one. A `422` gives you a JSON body with a stable
    `code`; a `404`, `409` or `500` gives you a bare line of English text. Branch on the HTTP
    status first. [Errors and declines](/errors) has the full map.
  </Accordion>
</AccordionGroup>

## Not covered here

Vibepay's employer-facing endpoints — creating wallets, issuing cards — live on the same host but
use a completely different authentication scheme and are not part of a merchant integration. If
you are a merchant, the three endpoints above are everything you can call.

<Card title="Take your first payment" icon="rocket" href="/quickstart" horizontal>
  Five steps from credentials to a live charge and a refund.
</Card>