​

CLAUDE.md

​

Project Overview

​

Disclosure policy (read this before writing anything)

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

​

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

​

Local commands

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:

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.