Barion OpenAPI

An unofficial OpenAPI 3.1 document for Barion's REST APIs. It contains all 27 operations from Barion's official endpoint index and works with Hey API.

This project is not affiliated with or endorsed by Barion Payment Zrt. Barion and its product names are trademarks of their respective owners.

Why this exists

Barion documents its API, but it does not publish an official OpenAPI spec. While they publish sdks for some languages, most languages lack support, and are left to reconstruct the same request/response/error types, validation rules, and HTTP client in those languages.

barion.openapi.yaml gives client generators a shared input.

i.e to name a few:

You can use it with Hey API for TypeScript(with several adapters available)/ soon Python,
OpenAPI Generator for many languages,
Kiota for Microsoft's supported client targets,
NSwag for C# and TypeScript, or
Stainful (stainless replacement) to generate an idiomatic Python SDK locally from the OpenAPI document and a stainless.yml configuration.

This repository does not try to maintain another hand-written Barion SDK. It only maintains the API contract on a best effort basis(no guarantees), so each project can generate a client suited to its language, framework, and HTTP stack.

How it was created

The full creation record is in HOW-IT-WAS-CREATED.md. It covers the original browser capture, source hashing, generation rules, reviewed overrides, sandbox tests, and Hey API verification.

this was synthesized using codex 5.6 sol - medium with the built in browser.

Rebuild it

Barion places Cloudflare in front of its documentation and rejects ordinary scripted requests. Capture runs in a persistent local Chrome profile:

cd Barion-OpenAPI
bun install
bun run capture

Complete the Cloudflare check if Chrome asks. The script then captures the official endpoint inventory, every linked endpoint page, referenced property type pages, authentication pages, and the callback page. It records each page's MediaWiki revision and a SHA-256 content hash under sources/.

The raw documentation capture stays local and is Git-ignored. Barion's wiki does not publish a clear redistribution license for the documentation.

Generate the OpenAPI document from the local capture:

bun run generate
bun run check

The output is barion.openapi.yaml. Generation fails when an official endpoint has no captured operation, two pages claim the same method and path, or the generated inventory differs from the official endpoint index.

Compare the result with the pinned, unofficial client-api/barion-python OpenAPI document:

bun run compare

This writes third-party-comparison.json. The comparison is diagnostic only. It never copies third-party paths or schemas into the generated document.

Sandbox verification

Copy .env.example to .env and add sandbox-only credentials. The .env and disposable payment state files are Git-ignored.

bun run probe:sandbox
bun run probe:sandbox:recipients
bun run probe:sandbox:payment
# Complete the 10 HUF payment in Barion's sandbox checkout.
bun run probe:sandbox:payment:finish

bun run probe:sandbox:payment:start-reservation
# Complete the checkout, then:
bun run probe:sandbox:payment:finish-reservation
bun run probe:sandbox:payment:finish

bun run probe:sandbox:payment:start-delayed
# Complete the checkout, then choose capture or cancel:
bun run probe:sandbox:payment:capture
bun run probe:sandbox:payment:cancel

The final command refunds the test payment only when its live state is Succeeded. See SANDBOX-VERIFICATION.md for the per-operation evidence and the endpoints that cannot be safely proven with one sandbox account.

Accuracy rule

The official Barion pages are authoritative. Third-party client specifications may help find omissions, but they must not silently override Barion's documentation. Unknown or conditional constraints remain documented instead of being guessed into stricter schemas.

License

The source code is available under the MIT license. The generated API description includes factual protocol information derived from Barion's public documentation. See NOTICE.md for attribution and scope.