Skip to main content

​
OpenAPI Reference

The OpenAPI reference is the exact HTTP contract for direct PayChain integrations. Use it when you need endpoint paths, request bodies, response schemas, query parameters, and error shapes.
Reference note: The OpenAPI contract is external-only. Dashboard session routes, admin routes, internal routes, mock routes, and health endpoints are excluded.

​
Where to find it

FormatLocation
JSON contract/docs/openapi on the PayChain web app
Repo sourceapps/web/contracts/openapi.json
Human guidesThis documentation site

​
How to use OpenAPI with these docs

  • Start with Payment flows to choose the right integration pattern.
  • Use SDK guide if you are building with Node.js or TypeScript.
  • Use REST API guide if you are calling PayChain over HTTPS directly.
  • Use this OpenAPI reference when you need exact fields, schemas, and path details.

​
Included surfaces

The external contract includes the core merchant integration surfaces:
  • Businesses.
  • Customers.
  • Invoices.
  • Public invoice status.
  • Balances.
  • Transactions.
  • Withdrawals.
  • Webhook configuration and delivery events.
  • Networks.
  • Tokens.
  • Prices and supported assets.
For human-readable network guidance, see Supported networks and tokens.

​
Excluded surfaces

The contract intentionally excludes:
  • Admin endpoints.
  • Dashboard-only session flows.
  • API key creation and rotation flows.
  • Internal infrastructure routes.
  • Mock/testing-only routes.
  • Health and metrics endpoints.
Security note: If an endpoint can change admin configuration, create API keys, alter billing state, or manage internal infrastructure, it should not appear in the external OpenAPI contract.

​
Authentication

External API requests use the x-api-key header. 
x-api-key: $PAYCHAIN_API_KEY
content-type: application/json
Use Idempotency-Key on mutating requests. 
Idempotency-Key: order_123_invoice

​
Updating the contract

When endpoint behavior changes, regenerate the external contract from the repo and review it before publishing: 
pnpm --filter @paychain/web contracts:pull
Before publishing, confirm:
  • No admin paths are included.
  • No internal provider or signer details are included.
  • Examples use placeholder IDs, addresses, and secrets.
  • Webhook routes are included.
  • Response schemas match the deployed API.