How a PolyPay Hosted Payment Works

A code-aligned walkthrough of order creation, wallet and amount allocation, on-chain confirmation, and signed webhook delivery.

Last reviewed against the PolyPay implementation: August 17, 2026.

Payment lifecycle at a glance

1. The merchant creates an order with a merchant order ID, amount, asset, network, and optional callback URLs.
2. PolyPay validates that the asset/network pair is supported and allocates an enabled merchant receiving wallet plus an exact payable amount.
3. The customer opens the hosted payment URL and transfers the displayed amount to the displayed address before expiry.
4. A chain listener detects the transfer, records its transaction hash, and moves the order through confirmation.
5. After the required chain confirmation succeeds, PolyPay marks the order paid and sends a signed webhook.

1. Order creation and idempotency

A merchant-provided mch_order_id is scoped to the merchant and environment. Repeating an active order request returns the existing order instead of silently creating another payable order. After an order expires, Hosted Checkout can reuse the same merchant order ID and creates a fresh payment attempt after payment-method selection. The response contains trade_id, actual_amount, address, expiration_time, and payment_url.

2. Receiving wallet and exact amount allocation

PolyPay selects from the merchant’s enabled wallets that support the requested asset and network. It then reserves the wallet-and-amount combination for the order lifetime. actual_amount is therefore the value the payer must send; integrations should not recalculate or round it.

Reference network fees during method selection

When currency and network are not preset, Hosted Checkout selects USDT whenever the merchant supports it. If the default receiving wallet supports USDT, its network is selected and placed first; otherwise TRON is preferred, followed by the first remaining USDT network. For USDC, Ethereum follows the default wallet network. A network appears only once when it is both the default and the common network. If USDT is unavailable, the selector falls back to the default wallet’s preferred currency. Currency cards keep a stable product-defined order and are not reordered by the default wallet. Whenever the payer changes currency, Hosted Checkout automatically selects the first network in that currency’s ordered network list; the payer can still choose another compatible network. The payment-method response includes short-lived fee_quotes for each asset and network. PolyPay refreshes live unit rates from chain RPC or fee endpoints, combines them with a standard transfer profile, and returns standard_fee_usd using the live USD price of the network fee asset. Base and Optimism estimates also include representative L1 data and operator fees reported by the OP Stack GasPriceOracle. available is current, stale is the last successful observation after a refresh failure, and unavailable means no numeric value should be displayed. Hosted Checkout keeps the selector focused and does not show fee estimates; the connected wallet remains the source of the final network fee.

For public comparison without authentication, GET /api/v1/pay/public/network-fees returns low, standard, and fast estimates for every supported transfer profile. PolyPay Tools uses the same data and compares the standard estimate for USDT, USDC, and each network’s native asset side by side. Open the live fee explorer.

Receiving wallet review

PolyPay silently screens new receiving wallets and wallets whose address or network changes. Intermediate review states are not shown in Wallet Management. If an address is confirmed as belonging to an exchange or custodial platform, the wallet is disabled and cannot be edited or re-enabled. Wallet Management shows a reason link that opens the appeal and support entry points. Name, currency, and monitoring-range edits do not restart screening.

3. Pay with WalletConnect or the displayed address

For supported USDT and USDC orders on TRON and EVM networks, Hosted Checkout can open a compatible wallet through WalletConnect and request the exact token transfer. The regular payment QR code remains visible on desktop; on mobile it is collapsed behind “Scan with another device” so the exact amount and receiving address stay prominent. For a TRON account whose Active Permission requires multiple signatures, checkout collects the first TronLink signature, creates a short-lived cross-device session, and displays a QR code for an authorized co-signer. That multisig QR code remains a required part of the mobile flow. The phone signs the exact same transaction, verifies the accumulated weight with getSignWeight, and broadcasts only after the permission threshold is reached. The browser may display the transaction hash returned by the wallet, but it never submits that hash as payment evidence. PolyPay independently discovers the transfer through its chain listener, matches the reserved network, token contract, recipient, and integer base-unit amount, and waits for the required confirmations before changing the order state. The QR code and manual address flow use the same server-owned confirmation path.

4. Observable order states

5. Webhook delivery and verification

PolyPay signs callbacks with Ed25519 v2. Verify the signed merchant ID, environment, timestamp, nonce, and raw request body using the public key selected from the platform JWKS by key ID. A non-2xx response is treated as a failed delivery. Store the event ID and process each event idempotently.

6. Choose the correct source of truth

A browser redirect improves customer experience, but it is not proof of payment. Update the merchant order from a verified webhook or an authenticated order-status query. Keep fulfilment idempotent because a webhook can be delivered more than once.

Responsibility boundary

Merchant

Own receiving wallets, protect API credentials, verify webhooks, and fulfil the business order idempotently.

PolyPay

Create and track payment orders, allocate payable details, observe configured chains, and deliver signed status events.

Payer

Use the exact network, address, asset, and amount shown before the order expires.

For implementation details, continue with the API Key guide and Webhook Security guide. API Key · Webhook Security

FAQ