Phala Pay
Self-hosted, non-custodial crypto payments API for merchants: quotes, deposit addresses, signed
webhooks, and refunds, running in an attested confidential VM.
What it is
- An API-only payments service in Stripe's shape. Merchants create quotes and deposit
addresses with API keys, and credit their customers from signed
deposit.credited webhooks.
- Self-hosted. Each operator runs its own instance in a dstack
confidential VM on Phala Cloud, for the merchant accounts it onboards.
- Non-custodial. Payments land in CREATE2 forwarder contracts that can only pay the
merchant's own treasury. The service holds no funds and sends no transactions.
What it isn't
- Not a hosted service. Phala's instance serves its own products: RedPill (live) and Phala
Cloud (planned). Other merchants run their own (self-hosting).
- Not a wallet, exchange, or dashboard. There is no custody, trading, fiat conversion,
signup, or merchant UI; merchants use the API and the SDKs.
- Not a compliance service. Beyond direct sanctions screening, compliance (KYC, KYT, the
Travel Rule) is each operator's and merchant's responsibility.
Quickstart
Pick the path that matches your role:
- Merchants integrating with an operator's instance: the
integration quickstart.
- Operators running their own instance: the
one-command deploy starts a verified release on
Phala Cloud; the self-hosting guide covers the environment repository,
merchant onboarding, and upgrades.
- Evaluators and contributors: the local sandbox
builds and runs the stack, then pays and credits a quote end to end.
To see it running, pay.phala.com has a live demo: a cloud console's
billing page that takes the test tokens of Phala's staging routes
on Sepolia and Base Sepolia. The site is static, on Cloudflare Workers; its demo calls an API-only
reference merchant backend at pay-demo-api.phala.com, an ordinary merchant account of Phala's
staging instance (staging reference product).
Features
- Quotes: a locked price and an exact token amount on the customer's own deposit address,
valid for
(window_start, expires_at]. One window is open per customer and route; a new quote
closes the previous window. Late, partial, or extra payments are still credited, at spot.
- Deposit addresses: one persistent, rotatable address per customer for every supported token
on every chain (the same address where the treasury is the same). Quotes use this address;
other transfers are credited at spot within per-transfer limits.
- Fast credit, watched to finality: checkout transaction hints take the instant processing
path, with credit in seconds at route confirmation (about 30 seconds after paying on Ethereum,
about 7 seconds on Base). Unhinted transfers are discovered by a five-minute scan. Every credit
is independently verified by a second RPC provider and watched to finality: reversed with
deposit.reversed if a reorganization proves
the payment replaced; one whose transaction leaves the chain with its nonce unspent stays
credited and not final, within the account's cap on such credit, and raises an operator alert.
- Signed webhooks: Standard Webhooks with ed25519 keys per account and mode, derived in the
CVM and pinned by merchants from TDX attestation.
- Merchant sweeps and refunds: merchants sweep forwarders and pay refunds from their own
wallet or Safe; the service verifies refunds at finality.
- Stripe-style API: test and live modes, secret and restricted keys, idempotency keys, events,
cursor pagination, and Stripe's error object.
- Screening and pricing: sanctions screening against verified OFAC SDN snapshots and audited
operator supplements; dual-source Chainlink feed prices and Uniswap V2 TWAP prices with
freshness and deviation checks.
- Operable in a CVM: reproducible images, an attested compose, encrypted WAL-G backups,
restore mode, Sentry alerts linked to runbooks.
How it works
A merchant's backend creates a quote or a customer's deposit address with its API key; the payer
pays a CREATE2 forwarder that can only pay the merchant's treasury; the service, in an attested
CVM, watches the chain with two RPC providers and sends a signed deposit.credited webhook; the
merchant sweeps forwarders to its treasury with its own wallet or Safe.
How Phala Pay works has the diagram, the payment lifecycle, and who owns what.
Documentation
The documentation index lists every document.
SDKs
| Package | Install | For |
|---|
@phala/pay | npm install @phala/pay viem | Framework-free browser checkout, retrieval, wallet, payment URI, icons, formatting, and public types |
@phala/pay-react | npm install @phala/pay-react react react-dom | React checkout components, hooks, icons, and @phala/pay-react/styles.css |
@phala/pay-server | npm install @phala/pay-server | Merchant client and API types; offline webhook, pins, address/ledger helpers, and sweep builders at @phala/pay-server/helpers |
phala-pay | pip install phala-pay | The Python backend client, webhook verification, and address pinning |
The SDKs share the service's version: pin the one equal to your operator's service version
(compatibility). The Python SDK's low-level client is generated
from crates/topup/openapi.json, the API's OpenAPI document.
Status
Phala Pay is pre-1.0 and has had no third-party security audit. Phala's production instance,
https://pay-api.phala.com, runs v0.13.1 for RedPill with live Ethereum USDC/USDT and Base USDC.
Staging (https://pay-api-staging.phala.com) serves test routes on Sepolia and Base Sepolia.
Post-launch status records the remaining onboarding and pilot gates.
Contributing
Contributions are welcome. CONTRIBUTING.md covers the development setup,
tests, and pull request conventions, and everyone taking part follows the
code of conduct.
Security
Report vulnerabilities privately, as described in SECURITY.md. Do not open public
issues for them.
License
Apache-2.0
