Phala Pay API (0.10.0-rc.6)

Send an API key as Authorization: Bearer ppay_rk_test_… (test mode) or ppay_rk_live_… (live mode). A restricted key (ppay_rk_, Stripe) holds only the permissions it was created with and never manages keys, treasuries, webhook endpoints, webhook keys, or account settings: run production with one. A secret key (ppay_sk_) holds every permission; keep it offline, for administration. The key selects the account and the mode; every object carries livemode, and a key never sees the other mode's objects.

Every response carries Request-Id: req_… (Stripe). Quote it when you contact support. An event caused by an API request names it in request.id, with the Idempotency-Key the request sent.

Every POST accepts an Idempotency-Key of up to 255 characters (Stripe). For 24 hours a repeat of the same request returns the first response, with Idempotent-Replayed: true, whatever it was, including a 500, so a retry never runs a request twice; a repeat with another request is 400 idempotency_key_reused, and one while the first still runs is 409 idempotency_key_in_use. A request that did not execute is not saved and runs again on a retry: one that failed validation (parameter_*), was rate limited (429), or met 503 unavailable.

Lists are newest first with Stripe's cursor pagination (Stripe): limit (1 to 100, default 10), and starting_after or ending_before, the id of an object of the list; has_more says whether more follow. Lists with a created filter take created[gt], created[gte], created[lt], and created[lte] in Unix seconds.

Every change is an event, delivered to your webhook endpoints and listed by GET /v1/events (Stripe). data.object is the object as it was when the event happened, rendered with the change and never changed afterwards; *.updated events add data.previous_attributes. Deliveries are retried until delivered and never given up on; a webhook endpoint's pending_deliveries, oldest_pending_at, and last_attempt show whether it is keeping up, and GET /v1/events?delivery_success=false lists what it has not received.

Errors are Stripe's error object (Stripe): {"error": {"type", "code", "message", "param", "doc_url"}}. 400 means the request cannot succeed as sent or in the objects' current state, 401 authentication, 403 permission, 404 a missing object, 409 only an Idempotency-Key still in use, 429 too many requests (with Retry-After in seconds), and 5xx the service. Branch on code; message may change.

422. The environment has a configured attached-pending refund limit (production 2, staging 1), and permits one new attachment per rolling 24 hours, across all merchants and modes. This is not retryable; contact the operator before sending or attaching another payout. The refund stays pending and reserved. Repeating the same attachment does not consume quota; existing attachments continue verification.

422. The chain has reached its permanent pilot limit of 1,000 issued addresses, including retired and expired addresses. This is not retryable; the operator must upgrade the scanning/provider plan before issuing more.

503. The requested chain is temporarily not ready. Retry after the indicated delay.

503. Fresh dual-source prices are unavailable or the UTC daily snapshot cap is exhausted. Retry after the indicated delay; no stale price is returned.

400. A parameter is malformed or out of range; param names it. Fix the request.

400. A required parameter is absent; param names it.

400. The operation does not take a parameter the request sent; param names it.

400. The amount is below the minimum of the route, or nothing is left to refund.

400. The amount is above the route's maximum deposit, or above what is left to refund.

400. The quote would take the open quotes of your account in this mode past a cap: their number (max_open_quotes of GET /v1/config), their credit (max_open_amount_per_account), or one customer's credit (max_open_amount_per_customer). Wait for quotes to be paid, expire, or be canceled, or ask the operator to raise the cap.

400. A pause of the account, the customer, or the route blocks the operation (quotes, settlement, or refunds). Your own quotes pause lifts with POST /v1/account/resume; the operator lifts its own.

400. Reconciliation froze the chain pending the operator's review; no quote is issued on it until the operator lifts the block.

400. Your payment settings do not accept the asset on the chain in this mode, or accept nothing yet (GET /v1/payment_settings): quote an asset GET /v1/config lists, or accept it with POST /v1/payment_settings.

400. After a restore of the service, your payment settings wait for your reconfirmation: send your complete configuration with POST /v1/payment_settings.

400. The account has no treasury on the chain: POST /v1/treasuries/challenge, then POST /v1/treasuries.

400. The treasury proof does not prove the address: the message is not the challenge, or the signature does not verify.

400. The treasury challenge expired; request a new one.

400. The treasury challenge was already used; request a new one.

400. The signature does not recover to the address and no contract is deployed there at the chain's finalized block; deploy the Safe first (ERC-6492 signatures are refused).

400. A sanctions list names the treasury address.

400. A treasury change is already pending on the chain; cancel it first.

400. The address is already the chain's treasury.

400. Only a pending treasury can be canceled.

400. The quote's address already received a payment, so the quote cannot be canceled.

400. The quote's payment window has closed, so it cannot be canceled; it expires on its own.

400. The quote is complete or expired; only an open quote can be canceled.

400. Admin: only a deposit the pump processes, detected or confirmed, can be nudged; a credited deposit waits for its sweep, which only a finalized Flushed event records.

400. The deposit cannot be refunded: it is not credited or rejected, or it was reversed.

400. The deposit is not final yet and could still be reversed; request the refund once final is true (about 15 minutes after its block on Ethereum).

400. A sanctions list names the refund's destination address.

400. The transfer log already pays another refund.

400. The refund's status does not allow the action: it is not pending, it is already marked paid with another transaction, or, being marked paid, it cannot be canceled.

400. The API key is revoked or already rolled.

400. The account's last active key of the mode cannot be revoked; create or roll a key first.

400. The account has its maximum of active deposit addresses in the mode.

400. The deposit address is retired; rotate the customer's active address instead.

400. The account has 16 webhook endpoints in the mode; delete one first.

400. The webhook endpoint is disabled; enable it before resending events to it.

400. The Idempotency-Key was used with a different request (type idempotency_error). Use a new key for a new request.

401. Admin API only: the RFC 9421 request signature did not verify.

401. Admin API only: the request signature was already used; sign the request again.

401. No Authorization: Bearer header with an API key (ppay_rk_… or ppay_sk_…).

401. The API key is malformed, unknown, or revoked.

401. The API key was rolled and its overlap has ended; use the key it was rolled to.

403. The key may not make this request: a restricted key lacks the permission, or the request manages keys, treasuries, webhook endpoints, webhook keys, or account settings, which needs a secret key.

403. The account is not enabled for live mode; use a test key until the operator enables it.

404. No such object in the key's account and mode.

409. A request with this Idempotency-Key is still running (type idempotency_error); retry shortly with the same key. The only 409.

429. Too many requests of the account and mode (100 per second live, 25 test), or reads of one quote's or deposit address's public view. Retry after Retry-After seconds, with exponential backoff.

429. The customer made too many quotes in the last minute, or rotated its deposit address too often in the last hour. Retry after Retry-After seconds.

500. The service failed. Retry with the same Idempotency-Key: a request that started executing replays this response, so it never runs twice; a new key runs it again.

503. A dependency (pricing, sanctions screening, attestation) is temporarily unavailable. Retry with backoff; the same Idempotency-Key runs the request again.

503. A planned upgrade temporarily pauses new mutations. Reads continue while the process is up. Retry after Retry-After with the same Idempotency-Key; the request has not executed. The pause expires automatically if deployment fails.

503. The service was restored from backup and is frozen until the operator has reconciled it with you: every request with an API key is refused, reads too, and nothing is credited or delivered meanwhile. Retry after Retry-After seconds; the operator contacts you for your records since the restore point.

400. Admin API only: a restore reconciliation action needs the service frozen after a restore.

400. Admin API only: a chain is not rescanned since the restore (GET /v1/admin/restore); the freeze cannot be lifted yet.

A locked price and a single-use address for one payment.

A customer's persistent address, credited at spot on every chain and asset.

Payments recorded on chain: credited, rejected, or reversed, and when they are final.

Refunds you pay from your treasury and attach with mark_paid.