OpenAPI Specification

We publish a machine-readable OpenAPI 3.1 specification covering every endpoint in this reference.

Where to find it

The spec is published alongside this documentation, at:

https://swisscrm.gitbook.io/swisspay/api-reference/openapi.yaml

If you need a different format (JSON, bundled with examples, or a particular OpenAPI version), email support@swisspay.ai.

What you can do with it

• Generate a client SDK in your language of choice with openapi-generator-cli, oapi-codegen, or any equivalent.
• Import into Postman or Insomnia to get a ready-to-go collection.
• Run mocked servers with Prism or similar — useful for local dev and tests before pointing at the live API.
• Validate requests in your CI with spectral or oas-validate before you ship.
• Drop into AI agents — see Using the API with AI agents (MCP).

Versioning

• The current spec is v1.
• We add fields and endpoints without bumping the major version.
• Breaking changes ship under a new prefix (/api/v2/...) — v1 continues to work during a documented deprecation window.

Importing into common tools

Postman

In Postman, click Import → Link and paste your published spec URL. Postman generates a collection that mirrors this reference.

openapi-generator-cli

openapi-generator-cli generate \
  -i https://swisscrm.gitbook.io/swisspay/api-reference/openapi.yaml \
  -g typescript-fetch \
  -o ./swisspay-client

prism (mock server)

npx @stoplight/prism mock https://swisscrm.gitbook.io/swisspay/api-reference/openapi.yaml

Reporting spec issues

If you spot a mismatch between the spec and the actual API behaviour, please email support@swisspay.ai with:

• The endpoint and method.
• What the spec says.
• What you observed.
• The Swisspay-Request-Id from the offending response, if you have one.