> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paychainhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Openapi reference

# 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.

<Info>
  **Reference note:** The OpenAPI contract covers the public merchant API. Use it alongside the flow guides so schemas are paired with fulfillment and reconciliation guidance.
</Info>

## Where to find it

| Format        | Location                                |
| ------------- | --------------------------------------- |
| JSON contract | `/docs/openapi` on the PayChain web app |
| Human guides  | This documentation site                 |

## How to use OpenAPI with these docs

* Start with [Payment flows](payment-flows) to choose the right integration pattern.
* Use [SDK guide](sdk-guide) if you are building with Node.js or TypeScript.
* Use [REST API guide](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](supported-networks-tokens).

## Not covered by OpenAPI

Some product actions are handled through the dashboard or support-assisted workflows instead of the public merchant API. Use the dashboard for account settings, API key management, billing changes, and payout-route administration unless a public API endpoint is documented.

## Authentication

External API requests use the `x-api-key` header.

```http theme={null}
x-api-key: $PAYCHAIN_API_KEY
content-type: application/json
```

Use `Idempotency-Key` on mutating requests.

```http theme={null}
Idempotency-Key: order_123_invoice
```

## Production use

When generating clients from OpenAPI, keep these integration rules in your application code:

* Store API keys only on your backend.
* Send `Idempotency-Key` on mutating requests.
* Verify webhook signatures with the raw body.
* Fetch the canonical resource before fulfilling customer value.
* Handle unknown error codes and enum values gracefully.