# 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.

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:

```http title="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](/contact).

## What it covers

| Surface | Operations |
| --- | --- |
| [Checkout API](/developers/docs/checkout) | `POST /checkout/sessions` · `GET /checkout/sessions/{id}` · `POST /checkout/sessions/{id}/cancel` |
| [QR Code API](/developers/docs/qr-codes) | `POST /qr-codes` · `GET /qr-codes` · `GET /qr-codes/{id}` · `POST /qr-codes/{id}/deactivate` |
| [Webhooks](/developers/docs/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](/developers/docs/oauth) 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

```bash title="TypeScript (Hey API)"
npx @hey-api/openapi-ts \
  -i https://payer.mv/developers/docs/openapi.json \
  -o src/payer
```

```bash title="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](/developers/docs/llms.txt) — 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.