Reference

OpenAPI specification

The REST API and every webhook payload as a machine-readable OpenAPI 3.1 document. Import it, generate a client from it, or hand it to an AI.

View as Markdown

Everything the prose pages describe about the REST surface — every endpoint, request body, response shape, error body, and all five webhook payloads — is also published as one OpenAPI 3.1 document:

The spec

GET https://payer.mv/developers/docs/openapi.json

The file is authored in the same repository as the API code and published with these docs, so it is the precise contract: field names, types, nullability, enum members, limits and status codes as the API actually behaves. Where a prose page and the spec disagree, trust the spec and tell us.

What it covers

Surface	Operations
Checkout API	`POST /checkout/sessions` · `GET /checkout/sessions/{id}` · `POST /checkout/sessions/{id}/cancel`
QR Code API	`POST /qr-codes` · `GET /qr-codes` · `GET /qr-codes/{id}` · `POST /qr-codes/{id}/deactivate`
Webhooks	All five `checkout.session.*` events, in the spec's `webhooks` section: the delivery envelope, the session snapshot, the signature and event headers, and the retry contract.

Shared conventions — bearer auth, scopes, the Idempotency-Key header, the Idempotent-Replay response header, error and validation bodies, rate limits — are modelled once in components and referenced everywhere they apply.

Not in the spec: the OAuth2 endpoints, which follow RFC 6749 rather than a Payer-specific contract, and the GraphQL API, which describes itself through introspection.

Import it

Postman, Insomnia, Bruno and friends import the URL directly and give you a ready-made collection with one request per operation — auth header, body schema and examples filled in.

Generate a typed client

TypeScript (Hey API)

npx @hey-api/openapi-ts \
  -i https://payer.mv/developers/docs/openapi.json \
  -o src/payer

Any language (OpenAPI Generator)

openapi-generator-cli generate \
  -i https://payer.mv/developers/docs/openapi.json \
  -g go -o ./payer

The webhook payloads are typed too — generate the WebhookEnvelope model and your handler parses deliveries into real types instead of any.

Tip

Building with an AI assistant? Give it the spec URL alongside the Markdown docs — the spec answers "what exactly does this field look like", the prose answers "how do the pieces fit together".

Versioning

The spec's info.version matches the webhook api_version (currently 2026-07-01). Additive changes — a new endpoint, a new optional field, a new event — do not bump it and are safe by construction: parse leniently and ignore fields you don't know. It only changes with a documented, backward-incompatible change to the contract.