OpenAPI document

The OpenAPI 3.1 document is the source of truth. Every first-party SDK is generated from it; you can do the same.

Where to find it

Environment	URL
Sandbox	https://api.sandbox.paylera.io/openapi/v1.json
Live	https://api.paylera.io/openapi/v1.json

YAML versions are at the same paths with .yaml instead of .json.

The document is updated continuously to match the deployed API. The ETag header on GET lets you cache responses and re-fetch only when the spec changes.

Browse it interactively

The Scalar-rendered, interactive docs:

Environment	URL
Sandbox	https://api.sandbox.paylera.io/scalar/v1
Live	https://api.paylera.io/scalar/v1

Try-it sends real requests using your API key. Use the sandbox URL for try-it unless you actually want to charge a customer.

Pinning a version

The default OpenAPI document represents the latest stable API version shipped. To get the document as it was at an older version:

GET /openapi/v1.json?version=2025-10-01

This is what you want when generating a client to pin against a specific dated API version.

Generation tooling

Any spec-compliant generator works. Some pairings teams ship:

Generator	Notes
openapi-generator	Mature, ~50 target languages. The official SDKs use a heavily-customised template; the default template gets you 80% of the way.
oapi-codegen (Go)	Produces idiomatic Go interfaces; what we use internally.
orval (TypeScript)	If you want React Query bindings out of the box.
NSwag (.NET)	What our C# SDK uses.
datamodel-code-generator (Python)	If you only need the schema models, not a client.

What the document covers

• Every endpoint with full request / response shapes.
• Every error envelope with stable problem discriminators.
• Every webhook event type with payload schema (under components.events).
• Idempotency, pagination, expand, and filter parameters declared per-endpoint.
• Examples for every request and response.

Drift guarantees

The deployed API never drifts from the document. CI runs both forwards (every endpoint declared in the document is implemented and matches schema) and backwards (every implemented endpoint is in the document). A drift fails the build; we ship together or not at all.

Webhook event schemas

Webhook event payloads are part of the OpenAPI document under the components.events keyword. Code-gen tools that treat OpenAPI events as a first-class concept (e.g. modern openapi-generator versions) emit typed event handlers; older generators ignore them, in which case use the schemas under components.schemas.

Local validation

Validate the document against the spec:

npx @apidevtools/swagger-cli validate openapi/v1.json

We run the same validator in CI; you’ll never see a malformed document in production.

Auth in the doc

The document declares bearerAuth as the security scheme. Generators will produce a constructor argument for the API key.

If your generator produces a “set authorization header on every request” hook, plug it there instead of editing the generated code.