Help and DocumentationContact Us

ZAHLEN

API User Guide

Appendix A - OpenAPI Specification

Discovery document | Endpoint catalog | Client-generation guidance

Version 1.0 | Source baseline: zahlen_deploy_0616A.tar.gz | June 2026

‌Appendix A - OpenAPI Specification

OpenAPI is a machine-readable description format for HTTP APIs. It helps developers discover routes, authentication requirements, supported methods, and response categories. Tools can use an OpenAPI document to render interactive documentation, generate starter clients, create test cases, and compare API contracts between releases.

1. ‌Discovery endpoint

   curl -sS https://api.example.com/v1/openapi.json | python -m json.tool

   The discovery endpoint itself does not require the ApiKeyAuth security requirement in the static document. Other listed routes are marked with the ApiKeyAuth scheme. Environment policy may still place network or gateway controls in front of discovery.

2. ‌Top-level document structure

   
   

   Property	Type	Meaning
   openapi	string	OpenAPI specification version used by the document. Zahlen returns 3.0.3.
   info	object	Human-readable API title, version, and description.
   paths	object	Route templates and supported HTTP methods.
   components	object	Reusable definitions, including the API- key security scheme.

   
   

   {

   "openapi": "3.0.3", "info": {

   "title": "Zahlen Payment Events API", "version": "v1",

   "description": "Payment Events, Batch Processing, Webhooks, Observability, and Governance APIs."

   },

   "paths": { "...": {} },

   "components": { "securitySchemes": { "...": {} } }

   }

1. ‌Security scheme

   
   

   "ApiKeyAuth": { "type": "apiKey",

   "in": "header",

   "name": "X-API-Key"

   }

For authenticated routes, send the merchant API key in the X-API-Key request header. Do not put the key in the URL, query string, JSON body, browser code, or logs.

1. ‌Commercial route catalog

   
   

   Method	Path	Purpose
   POST	/v1/payment-events	Submit one or more payment events.
   POST	/v1/payment-events/batch	Submit a batch and receive batch- oriented response data.
   GET	/v1/payment-events/{event_id}	Retrieve one stored payment event.
   GET	/v1/payment-events/{event_id}/decision	Retrieve the decision associated with an event.
   GET	/v1/payment-events/{event_id}/ processor-result	Retrieve downstream processor execution evidence.
   GET	/v1/payment-events/batches/{batch_id}	Retrieve batch detail and paginated event identifiers.
   GET	/v1/payment-events/batches/ {batch_id}/summary	Retrieve batch-level summary and distributions.
   GET	/v1/payment-events/batches/ {batch_id}/decisions	Retrieve paginated decisions for a batch.
   GET	/v1/payment-events/batches/ {batch_id}/processor-results	Retrieve paginated processor results for a batch.
   POST	/v1/webhook-subscriptions	Create a webhook subscription.
   GET	/v1/webhook-subscriptions	List visible webhook subscriptions.
   DELETE	/v1/webhook-subscriptions/ {subscription_id}	Delete or deactivate a subscription.

   
   

   Additional commercial endpoints

   The actual deployed API also contains retry-decision, retry-outcome, health, and version contracts documented elsewhere in this guide. Do not assume that the static discovery document lists every deployed merchant-facing route.

2. ‌Governance and observability routes in discovery

   
   

   Method	Path	Category
   POST / GET	/v1/admin/api-keys	API key lifecycle
   DELETE	/v1/admin/api-keys/{key_id}	API key revocation
   GET	/v1/admin/api/metrics	API metrics
   GET	/v1/admin/api/activity	API activity
   GET	/v1/admin/api/webhook-operations	Webhook operations
   GET	/v1/admin/api/health	Administrative API health
   GET	/v1/admin/api/tenant-usage	Tenant usage reporting
   GET	/v1/admin/api/audit-trail	API audit records
   GET	/v1/admin/api/documentation	Structured documentation and examples
   GET	/v1/admin/developer-portal	Developer portal data
   GET	/v1/openapi.json	OpenAPI discovery

   
   

   Authorization boundary

   Routes under /v1/admin/* are administrative resources. A merchant X-API-Key must not be assumed to grant access. Use only the authorization method and enterprise contract approved for the deployment.

3. ‌Path objects and operations

   Each path contains one or more HTTP operations. The static document provides a generated summary, common response descriptions, and security metadata.

   "/v1/payment-events": { "post": {

   "summary": "POST payment events", "responses": {

   "200": {"description": "Successful response"}, "401": {"description": "Missing or invalid API key"}, "429": {"description": "Plan quota exceeded"}

   },

   "security": [{"ApiKeyAuth": []}]

   }

   }

Actual routes may also return validation, authorization, not-found, conflict, or server-error responses. Chapter 11 defines the broader error-handling model.

1. ‌Downloading and storing the specification

   
   

   curl -sS https://api.example.com/v1/openapi.json -o zahlen-openapi-v1.json

   
   

   python -m json.tool zahlen-openapi-v1.json > /dev/null

• Store the downloaded document as a build or test artifact, not as a secret.

• Record the environment, download time, and deployed application version.

• Validate that the openapi property is 3.0.3 and the info.version value is expected.

• Do not silently replace a pinned contract during a production build.

• Review differences before adopting a newly downloaded document.

1. ‌Inspecting with jq

   
   

   # List all paths

   jq -r '.paths | keys[]' zahlen-openapi-v1.json

   
   

   # List method and path pairs

   jq -r '.paths | to_entries[] as $p |

   $p.value | keys[] | "\(. | ascii_upcase) \($p.key)"' zahlen-openapi-v1.json

   
   

   # Inspect the API-key security scheme

   jq '.components.securitySchemes.ApiKeyAuth' zahlen-openapi-v1.json

1. ‌Contract validation in Python

   
   

   import json

   from pathlib import Path

   spec = json.loads(Path("zahlen-openapi-v1.json").read_text()) assert spec["openapi"] == "3.0.3"

   assert spec["info"]["version"] == "v1"

   assert "/v1/payment-events" in spec["paths"]

   assert "post" in spec["paths"]["/v1/payment-events"]

   
   

   scheme = spec["components"]["securitySchemes"]["ApiKeyAuth"] assert scheme == {

   "type": "apiKey",

   "in": "header",

   "name": "X-API-Key",

   }

   
   

   print("Zahlen discovery contract validated")

Contract checks should fail clearly when a required route, method, version, or security definition changes. Keep the checks small and focused so a failure tells the developer what changed.

1. ‌Client generation guidance

   Many tools can generate API clients from OpenAPI. For Zahlen, use generated output as a starting point rather than unquestioned production code because the static discovery document does not contain the complete detailed schemas for every operation.

   
   

   Generated artifact	Recommended treatment
   HTTP method and path constants	Generally safe after review.
   Authentication middleware	Confirm it sends X-API-Key only from secure server-side configuration.
   Request models	Generate from the detailed schema export, not only the static discovery document.
   Response models	Compare with documented Pydantic-derived schemas and nullable fields.
   Retry behavior	Implement manually; generators should not decide payment or transport retry policy.
   Error mapping	Extend to cover 400, 403, 404, 409, 422, 429, 500, and 503.
   Timeouts and logging	Add explicitly; do not rely on generator defaults.

   
   

   Payment schedule safeguard

   Generated clients must not schedule authorization attempts. Zahlen payment retries remain fixed at Day 1, Day 2, Day 6, and Day 16. OpenAPI tooling describes HTTP operations; it does not replace the business retry policy.

2. ‌Comparing specifications between releases

   1. Download the specification from the current environment and the candidate environment.

   2. Normalize JSON formatting so differences are readable.

   3. Compare paths, methods, security requirements, versions, and response categories.

   4. Review removed or renamed operations as potentially breaking changes.

   5. Run request and response contract tests against the candidate deployment.

   6. Approve the new contract before updating generated code or production artifacts.

   
   

   python -m json.tool openapi-current.json > current.pretty.json python -m json.tool openapi-candidate.json > candidate.pretty.json

   diff -u current.pretty.json candidate.pretty.json

1. ‌OpenAPI versus the detailed schema reference

   
   

   Source	Best use
   /v1/openapi.json	Route discovery, method discovery, security-scheme discovery, basic tooling.
   Detailed JSON schema export	Exact fields, required properties, nullability, constraints, and nested models.
   This API User Guide	Developer workflows, examples, safety rules, retry behavior, and interpretation.
   Runtime responses	Final evidence of deployed behavior; capture identifiers and errors for diagnostics.

   
   

   Source-of-truth rule

   For payload construction, use the detailed request and response schema definitions. For discovery, use /v1/openapi.json. When sources appear inconsistent, stop integration work and confirm the deployed contract with the Zahlen onboarding or platform team.

   
   

2. ‌Appendix checklist

   • The discovery document downloads successfully from the correct environment.

   • The OpenAPI version is 3.0.3 and the API version is v1.

   • The required route and method pairs are present.

   • ApiKeyAuth uses the X-API-Key header.

   • Administrative routes are treated as separately governed.

   • Detailed request and response schemas are validated outside the static discovery document.

   • Generated clients include explicit timeouts, error mapping, logging, and idempotency.

   • Contract differences are reviewed before release.

   • No generated behavior can create payment attempts outside Day 1, Day 2, Day 6, and Day 16.