Skip to main content

How these docs work

The reference pages are generated from committed OpenAPI specs under api-docs/specs/. Those specs are produced and refreshed by the generate-api-docs skill from each service's route tables and request/response types, and are reviewed like any other code change — every API change shows up as a spec diff in the merge request. The site build reads the committed specs from disk; no service needs to be running.

A contract test in payments-backend serializes a real response object per endpoint and asserts it validates against the committed schema, so a schema can't silently go missing or drift from the code.

The gateway rewrites the prefix​

The public path is /institution/payments/*; the gateway in front of the backend rewrites /institution to /v1 before proxying, so a public GET /institution/payments/config reaches the app's GET /v1/payments/config. That difference is captured in each spec's server list (dev uses the /institution base, local uses /v1 directly), so the URL shown always matches the environment you pick.

Some features are owned by account-events-service​

The Collect features (getting paid, funding history, collections, scheduled withdrawals, settlements) are proxied to account-events-service, which owns their request/response schemas. payments-backend only forwards them. Their reference is generated from account-events' source types and shown here at the public /institution/payments/* paths — the routes you actually call. Doc updates are driven from payments-backend (account-events does not serve its own spec): the generate-api-docs skill reads the account-events repo's latest local source and refreshes the committed account-events.json, reviewed as a normal diff.

Regenerating locally​

# In api-docs/ — no services required, the specs are committed.
pnpm install --frozen-lockfile
pnpm run generate-docs   # generates MDX from ./specs and ./external-specs, plus the combined Web API spec
pnpm start               # preview at http://localhost:8080

To refresh a spec after changing routes or types, run the generate-api-docs skill and review the diff to api-docs/specs/*.json.