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 every webhook payload) 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`
Mandates API	`POST /mandates` · `GET /mandates` · `GET /mandates/{id}` · `POST /mandates/{id}/revoke` · `POST /mandates/{id}/charges`
QR Code API	`POST /qr-codes` · `GET /qr-codes` · `GET /qr-codes/{id}` · `POST /qr-codes/{id}/deactivate`
Subscriptions API	`GET /subscriptions` · `GET /subscriptions/{id}` · `GET /subscriptions/{id}/invoices` · `POST /subscriptions/{id}/cancel`, plus the `mode` and `price_data` fields on checkout session create
Webhooks	Every `checkout.session.`, `mandate.`, `subscription.` and `invoice.` event, in the spec's `webhooks` section: the delivery envelope, the session, mandate, charge, subscription and invoice snapshots, 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, with the 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.