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

# CLAUDE

# CLAUDE.md

This file guides Claude Code (claude.ai/code) when working in this repository.

## Project Overview

`orqex/orchestrate-docs` is the public documentation for **Orqex Orchestrate**, built with
**Mintlify** and published at `docs.orqex.com`. It is **English only**.

The documentation has one job: give an integrator everything needed to integrate, and
nothing that helps a competitor understand or rebuild the product.

## Disclosure policy (read this before writing anything)

Orchestrate is a strategic asset. These rules are not stylistic — they are the reason this
documentation was rewritten from scratch.

* **Never list supported countries, currencies or payment methods.** Coverage is discovered
  at runtime (`/payment/intents/{id}/countries`, `.../countries/{cc}/methods`) or looked up
  in the dashboard. No catalogues, no matrices, no counts.
* **Never name a payment provider**, with one deliberate exception: the `gateway_options`
  reference on `/payments/custom-checkout`, which documents `stripe`, `pawapay` and `test`
  because integrators need those keys. Nowhere else.
* **Never explain internals**: routing rules, failover decisions, gateway selection,
  scoring, orchestration strategies, DCC. `failover` on an attempt is documented as an
  informational field with no value list, and readers are told not to branch on it.
* **Never use coverage-implying examples.** Use `US` / `DE` and `USD` / `EUR`, and the
  sandbox method code `test`. No African country codes, no real mobile-money or wallet
  method codes.
* **Never describe dashboard screens.** Point to the dashboard as the place where
  configuration and coverage live, and stop there.

Before opening a PR, run the leak scan in "Validation" below.

## Structure

```
docs.json                    Mintlify config: theme, navigation, redirects
api-reference/openapi.json   OpenAPI 3.1 — the API Reference tab is generated from this
index.mdx                    Overview
quickstart.mdx
authentication.mdx
api-conventions.mdx          Envelopes, amounts, pagination, idempotency, rate limits
errors.mdx
payments/                    overview, hosted-checkout, custom-checkout, next-actions,
                             refunds, requery, testing
payouts/                     overview, create, instruments, testing
webhooks.mdx
utils/                       exchange-rates, method-status
mcp/                         overview, tools
sdk/php/                     installation, usage, laravel
images/                      Brand logo and icon, light/dark
```

Tabs: **Guide**, **API Reference**, **SDK**. There is deliberately no Dashboard tab.

## Local commands

```bash theme={null}
npm install                          # PUPPETEER_SKIP_DOWNLOAD=true if the install fails
./node_modules/.bin/mintlify dev     # preview at http://localhost:3000
./node_modules/.bin/mintlify broken-links
```

## Conventions

* **Style:** minimalist and integration-focused, in the spirit of ProcessOut and Stripe.
  Short prose, then the concrete thing. A page should be scannable in under a minute and
  complete enough to integrate from. Prefer a table or a code block over three paragraphs.
* **Theme:** Orqex brand colours (`#144419` / `#cdf546`) and the Axazara fonts. Logo and
  icon in `images/` are used as-is. Do not change branding.
* **Code samples:** cURL and PHP (the official SDK). Placeholders `sk_live_...` /
  `sk_sandbox_...`.
* **Navigation:** create the `.mdx`, then list its path without the extension in
  `docs.json`. Internal links are absolute, e.g. `/payments/refunds`.
* **Redirects:** the old bilingual URLs (`/en/...`, `/fr/...`) are mapped in
  `docs.json.redirects`. Wildcard rules must stay last so specific rules win.

## API reference

* Generated from `api-reference/openapi.json`. **Edit the spec, not per-endpoint pages.**
* The spec covers **only** the public API under `/v1`, and must match
  `orqex/orchestrate-api` `routes/api/public/v1.php` on `main` exactly — currently 25
  operations. Never invent a field, path, enum value or response shape.
* Mintlify only supports internal `$ref` within a single document.
* Sanitisation carried by the spec: `method_code` and `method` are plain strings with no
  enum; `failover.decision` is an unenumerated object; `gateway_options` is a free-form
  object; examples use neutral data.

## Accuracy rules

* Mirror the backend. Verify against `orqex/orchestrate-api` on `main` before writing —
  Form Requests for parameters, API Resources for response shapes, `app/Listeners/Pulses/`
  for webhook events and payloads, `app/Enums/` for values.
* **Do not fabricate.** Two traps that have already bitten:
  * Deliveries to a `webhook_url` are unsigned (`doNotSign`). Project endpoints are signed.
    Keep that distinction.
  * `payment.attempt.action_required` and `payout.pending` exist as identifiers but are
    **not dispatched**. Do not document them. Every other event goes to both channels.
  * Trigger names are not event names: `payment.completed` is subscribed to as
    `payment_captured`, and both refund events share `payment_refunded`.
* Amounts are in major units on every resource, payouts included. `fee_amount` on a payout
  is the exception: a plain integer in minor units.
* The sandbox test gateway outcome is driven by the last two digits of the payer's phone
  number, not the amount. For payouts it is the last two digits of the destination
  (phone number, account number or wallet address).

## Validation before a PR

1. `docs.json` is valid JSON and every referenced page resolves to a file.
2. `./node_modules/.bin/mintlify broken-links` passes.
3. Leak scan returns nothing outside the `gateway_options` table:

```bash theme={null}
grep -rniE "stripe|pawapay|flutterwave|paystack|cinetpay|cryptomus|fedapay|spotflow|payaza|m-pesa|mtn|moov|airtel|vodacom|djamo" --include="*.mdx" --include="*.json" . | grep -v node_modules
grep -rnoE "\bmomo_[a-z_]+|wallet_[a-z_]+" --include="*.mdx" --include="*.json" . | grep -v node_modules
grep -rniE "routing rule|orchestration strateg|round.robin|multi-account|dcc engine|scoring" --include="*.mdx" --include="*.json" . | grep -v node_modules
```

4. `main` is protected (PR required); never push to it directly.