Get started

Phala Pay documentation

Documentation is grouped by who reads it. New to Phala Pay? Start with How Phala Pay works.

Integrate (merchants)

For a merchant's backend team, connecting an account to an operator's instance.

Document	What it covers
Integration guide	The quickstart, quotes, deposit addresses, treasuries, sweeps, webhooks and fulfillment, refunds, testing, go-live, and the API reference by topic.
API reference	Every endpoint and schema, built from crates/topup/openapi.json (how it is built).
`@phala/pay`	The framework-free browser checkout core.
`@phala/pay-react`	React components, hooks, icons, and styles.
`@phala/pay-server`	The merchant server client and API types; offline helpers at `@phala/pay-server/helpers`.
`phala-pay`	The Python client.
Integrator sandbox	Scripted payment scenarios, locally or against an operator's test mode.

For the operator who runs an instance, onboards merchants, and handles incidents.

Document	What it covers
Self-hosting guide	The steps, in order, from an environment repository and a verified release to a credited test deposit, and on to going live.
Deployment reference	GitHub setup, releases and deploys, sealed secrets, attested settings, RPC providers, the custom domain, Sentry, attestation, onboarding, and merchant setup.
Service configuration	The `topup` commands, flags, and environment.
Contract deployment	Deploying and verifying the deterministic forwarder factory on a chain.
Backup and restore	WAL-G backups, the restore-check variant, restores, and drills.
Runbooks	One runbook per alert or incident, and the alert index.
Phala's instance	Phala's own deployment, as a worked example: its staging routes, the reference product behind the demo, the website, and its onboarding policy.

Document	What it covers
Architecture	The specification: trust model, contracts, schema, state machine, chain reads, quotes, webhooks, API, reconciliation, deployment, and policies.
Forwarder contracts	The `ForwarderFactory` and forwarder model, flush semantics, and tests.
Database migrations	Database roles and grants, and what each migration changes.
Changelog	Each release's integrator-visible changes to the HTTP API, webhooks, and SDKs (the SDKs' releases before v0.5.0: JS, Python).

Document	What it covers
How Phala Pay works	The model, the payment lifecycle, and who owns what.
Design: multi-tenant Phala Pay	The decision record behind the current design, with its amendments.
Design: per-account payment settings	The decision record for payment settings (v0.6.0); current usage is in the integration guide.
Design: deployment configuration	The configuration decision record (v0.3.0); its RPC schema is superseded by chain reads.
Design: zero-downtime planned upgrades	Not adopted (owner: no second CVM, 2026-10-05); maintenance 503 and SDK upgrade tolerance implemented instead.
Design: chain reads	Read/verify endpoints, dual coverage, checkpoints and operator compatibility; current operations are in the RPC runbook.
Design: SDK ergonomics	Phases 1–2 implemented in 0.9.0; phase 3 (setup CLI) pending: server client, pins, setup, checkout handoff, ledger recipes, and the owner’s compatibility decision.
Plan: Go SDK	Proposed backend scope, security parity, generation and release decisions, and acceptance gates; not implemented.
Plan to production	What remains before Phala's own instance goes live.

CONTRIBUTING.md covers the development setup, tests, conventions, and releases. Report vulnerabilities as described in SECURITY.md.

RPC queue performance evidence and concurrent migration behavior are recorded in Concurrent migration recovery.