phala-pay

Phala Pay for Python (3.12+), in the shape of Stripe's SDK: create a quote, hand its client_secret to the browser checkout (@phala/pay), and fulfil from the signed deposit.credited webhook.

Install

uv add phala-pay        # or: pip install phala-pay

phala-pay shares the service's version: pin the one equal to your operator's service version (compatibility). phala-pay[eoa] adds the signer an EOA treasury's proof needs (pay.treasuries.set_eoa).

Quickstart

The operator creates your account and hands your contact its first secret key, ppay_sk_test_…; roll it on receipt, keep it offline for administration, and create a restricted key (ppay_rk_…) for your servers.

Create a quote for the signed-in account and return its client secret to the browser:

import os

from phala_pay import PhalaPay

pay = PhalaPay(
    api_base="https://pay.example.com",
    api_key=os.environ["PHALA_PAY_API_KEY"],  # a restricted key, ppay_rk_…
    # Your pins, configured here and never read from the service: every quote and deposit address
    # is recomputed from them, failing closed (AddressMismatchError); a live key requires all.
    account="acct_…",
    forwarder=(FACTORY, IMPLEMENTATION),  # pinned from the attested deployment
    treasuries={11155111: TREASURY},  # your own treasury per chain, as you proved it
)

quote = pay.quotes.create(
    client_reference_id="team-42",  # your id for the customer; credits are addressed to it
    amount=2500,  # US cents
    chain_id=11155111,
    asset="pha",
    idempotency_key=order_id,  # for 24 hours the same key replays this quote and client secret
)
# The page renders <Checkout clientSecret expectedAddress apiBase /> (@phala/pay).
return {"client_secret": quote.client_secret, "expected_address": quote.address}

Fulfil from the webhook, once per deposit, and answer 2xx after the credit is committed:

from phala_pay import SignatureVerificationError

try:
    event = pay.webhooks.construct_event(
        raw_body, request.headers, WEBHOOK_PUBLIC_KEY, "acct_…", expected_livemode=False
    )
except (SignatureVerificationError, ValueError):
    return Response(status_code=400)

if event.type.startswith("deposit."):
    # Credit, refund, and reversal alike: per deposit, serially, merge the snapshot and move the
    # balance to `amount - amount_refunded - amount_reversed` (0 unless credited or reversed).
    apply_deposit(event.deposit)

Events arrive in any order; the snapshot's cumulative amount_refunded and amount_reversed make the result independent of it (docs/integration.md §2.3; apply_deposit in sdk/examples/fastapi_app.py).

WEBHOOK_PUBLIC_KEY is your account's webhook key in the mode, whpk_…, pinned from GET /v1/attestation (docs/integration.md §5.3); pass a list of keys while a rotation overlaps. construct_event fails closed: it checks the Standard Webhooks signature, the timestamp (five minutes' tolerance), that the body's id is the webhook-id, and that the event's account and livemode are the expected ones; event.data.object is the Deposit (a Quote for quote.*, a Refund for refund.*) as it was when the event happened: it is rendered with the change and never re-rendered, so read the object again for its current state. *.updated events carry event.data.previous_attributes, and an event your own request caused names it in event.request (id, idempotency_key). sdk/examples/fastapi_app.py is a complete FastAPI backend with both routes.

Reference

Every request sends the API key as Authorization: Bearer …: a restricted key, ppay_rk_…, for production servers (pay.api_keys.create(permissions=[...]), which never manages keys, treasuries, webhook endpoints, webhook keys, or account settings), or a secret key, ppay_sk_…, kept offline for administration. Transport errors, 429 (after its Retry-After), 5xx, and 409 idempotency_key_in_use are retried with backoff, reusing one Idempotency-Key per POST; a response the service saved for the key, even a 500, comes back marked Idempotent-Replayed and is raised as it is, since the request already ran. Failures raise ApiError with the service's stable code, error_type, param, doc_url, request_id (the response's Request-Id), and retry_after. Business-state failures, such as deposit_not_final or quote_unexpected_state, are 400; only idempotency_key_in_use is 409. Status arguments have Literal hints, and EventType names every event (phala_pay.QuoteStatus, DepositStatus, RefundStatus, TreasuryStatus, EventType, …); the generated models keep statuses as str, so a value added later still parses. forwarder=(factory, implementation), pinned from the attested deployment, treasuries={chain_id: treasury}, your own treasury per chain as you proved it, and account= (acct_…) are the pins every open quote and every network of an active deposit address is recomputed from, never the response's treasury: a compromised service could return an attacker's treasury with its valid address. An address you cannot derive, or one naming another treasury than your pinned one of its chain, raises AddressMismatchError. A live key requires all three pins and fails closed without them; in test mode account is read once from GET /v1/account, and an unpinned treasury falls back to the response's with an UnpinnedTreasuryWarning. topup_sdk.deposit_address(factory, implementation, treasury, account=, livemode=, client_reference_id=, version=) recomputes any deposit address offline; pass the treasury of the network, since a chain whose treasury differs has its own address.

Sweeping. Funds stay in the forwarders until you sweep them, with your own wallet or Safe:

from topup_sdk import flush_transactions, safe_batch, write_safe_batch

forwarders = list(pay.forwarders.list(chain_id=1, sweepable=PHA))  # never a sanctioned one
calls = flush_transactions(forwarders, PHA)  # offline: one factory.flush per treasury
write_safe_batch("sweep.json", safe_batch(1, TREASURY_SAFE, calls))  # for the Transaction Builder

flush_transaction(factory, treasury, salts, token) encodes one call offline from exported forwarders (pay.export_account writes them all), so funds stay sweepable without the service; safe_batch writes the Safe Transaction Builder's BatchFile JSON with its checksum.

Treasuries. An EOA proves itself with pay.treasuries.set_eoa(chain_id=, address=, private_key=) (install phala-pay[eoa]); a Safe's owners sign the challenge's message as a Safe message with the Safe{Core} SDK and submit it with pay.treasuries.create (docs/integration.md §1.6, "Safe treasuries").

metadata follows Stripe's: up to 50 string key/value pairs, keys of up to 40 characters without square brackets, values of up to 500 characters. An update merges: a key set to "" is unset, and metadata="" unsets every key. A deposit starts with a copy of its quote's metadata, so an order id set on the quote arrives in the deposit.credited webhook's data.object.metadata. Do not store sensitive information in it.

Lower-level modules: topup_sdk (webhook and admin request signatures, address derivation, attestation, TopupClient) and topup_client (generated from crates/topup/openapi.json; do not edit). uv run topup-sdk send-test-event --url … --seed-file test.seed --client-reference-id … sends a signed test event, a duplicate, and a forged copy to a webhook receiver whose test instance pins that seed's public key. See docs/integration.md for the integration guide and the versioning and deprecation policy, deploy/product/reference_product for a complete product, and deploy/sandbox/README.md for the sandbox.

Development

make sync    # install the locked environment
make check   # ruff, mypy --strict, pytest, and the regeneration no-op check

phala-pay is released with the service: the v<version> tag's Release workflow publishes it to PyPI (environment pypi) with trusted publishing (CONTRIBUTING.md, "Releasing"). Its changes are in the top-level CHANGELOG.md, under "Python SDK"; its releases before v0.5.0, versioned on their own, stay in sdk/python.