PFlux
DOCS
GitHub Integration enquiries
INTEGRATIONS/SELF-HOSTED CHECKOUT

Self-hosted checkout

The P2Flux payment page on your own domain, under your own headers — and, with your wallets listed, refusing every payment that is not addressed to them.

PACKAGEBuilt page, no build step
DOWNLOADGitHub releases · free
APIapi.p2flux.com, unchanged
SUPPORTPaid service
YOUR DOMAIN → P2FLUX API → USDC ON BASE

The payment page your buyers see can run on your own server instead of pay.p2flux.com. Payments do not change: buyers pay from their own wallet straight to yours through the P2Flux contracts, and P2Flux never holds the money, wherever the page is served from.

Overview

The self-hosted checkout is the same page P2Flux hosts, published as built files: an index.html, its assets and a short settings file. It is meant for companies that want the payment page under their own domain, their own security headers and their own update schedule, and that want proof that the page cannot be pointed at another wallet.

Download it from GitHub releases. Every release lists the ZIP’s SHA-256.

What changes, what stays

Hosted (pay.p2flux.com)Self-hosted
Who serves the pageP2FluxYou
UpdatesWhen P2Flux deploysWhen you install a release
Security headersP2Flux’sYours (an example is included)
Wallets allowed to receiveAny, as the payment saysOnly those in your config.js (if you list them)
Contracts, network and amountsChecked against the published contractsThe same
Create and confirm paymentsP2Flux APIP2Flux API
Network fee in USDCSent by P2FluxSent by P2Flux

Install

Download the release, check it, unpack it, and create your settings from the example:

terminal
sha256sum p2flux-checkout-<version>.zip   # compare with the release notes
unzip p2flux-checkout-<version>.zip -d pay   # index.html, assets/ … directly in pay/
cd pay && sha256sum -c SHA256SUMS
cp config.example.js config.js

Serve the folder over HTTPS, at the root of a domain (https://pay.yourcompany.com/) or on a path (https://yourcompany.com/pay/). On a path the address must end with a slash: the page loads its files relative to itself. Then make one small test payment.

config.js

The page reads your settings before it starts, and refuses to run without valid ones. Releases never contain a config.js, so installing an update keeps yours.

config.js
window.__P2FLUX_CHECKOUT__ = {
  network: 'base',                 // or 'base-sepolia' for the test network
  recipients: ['0xYourWallet…'],   // optional, recommended
}
SettingValue
network'base' (Base Mainnet, real USDC) or 'base-sepolia' (test network). It selects the P2Flux API, the public RPC and the contracts the page accepts.
recipientsOptional, recommended. The only wallets allowed to receive. Remove the line to accept any recipient.
NOT CONFIGURED

The page shows “This checkout is not configured” when config.js is missing or invalid: an unknown network, a malformed wallet address, an empty list, an invalid brand or an unknown setting. It never guesses.

Branding

Show your own logo and colour instead of P2Flux’s: put the logo file next to index.html and add a brand to config.js.

config.js
  brand: { logo: 'logo.svg', color: '#0f766e', name: 'Your Shop' },
  • logo: a file served with the page (.svg, .png, .webp, .jpg; letters, digits, - _ . and / in the name), shown at most 24 px high and 180 px wide, smaller on a narrow phone. A web address is not accepted: the page loads nothing from other sites.
  • color: #RRGGBB, dark enough for white button text (contrast of at least 4.5:1); a light colour makes the configuration invalid.
  • name: optional, the logo’s text alternative, at most 40 characters.

The page’s address stays in the card header and “Powered by P2Flux” appears under the card. On pay.p2flux.com, branding is available to partners - contact us.

Server and headers

Any web server works; the headers are what matter. The package includes nginx.example.conf with all of them:

  • Content-Security-Policy with connect-src naming the P2Flux API and public RPC of your network, and frame-ancestors 'none' (it only works as a header).
  • Cache-Control: no-store for index.html and config.js; long caching for assets/.
  • Unknown paths answer 404, never the page.
  • No Cross-Origin-Opener-Policy header: the page reports the result to your shop page through window.opener, which that header breaks.

Links have the form <your checkout>/#/<page>/<token>, with the page pay, subscribe, cancel, refund, approve, link or links. The SDKs build them for you:

IntegrationSetting
JavaScript SDK 0.9+checkoutUrl option, then checkoutLink(page, token)
PHP SDK 0.9+checkoutUrl option, then checkoutLink($page, $token)
Laravel 0.3+P2FLUX_CHECKOUT_URL
WooCommerce pluginthe filter p2flux_wc_checkout_url

Release 1.1.0 and later include the payment link screens, and the create form works on your copy too: <your checkout>/#/new. Building checkoutLink('link', …) and checkoutLink('links', …) needs @p2flux/sdk 0.10.0, p2flux/sdk-php 0.10.0 or p2flux/laravel 0.4.0.

What the wallet list protects

  • Payments and subscriptions: the receiving wallet must be in your list.
  • Cancellations: the subscription being cancelled must be to a wallet in your list.
  • Allowance restore: the screen that restores a subscription’s allowance (#/approve/…) opens only for a subscription to a wallet in your list.
  • Payment links: the page opens and creates only links that pay a wallet in your list.
  • Refunds: the wallet that sends the refund is checked against your list. Where the refund goes (the original payer) and the most that may be refunded are read by the page itself from the original payment the refund names, on chain: it must go to that payment’s payer and be no more than was paid. Which payment is being refunded is still the API’s statement — check the payer and amount in your wallet against the order.
  • Contracts, network and amounts: always checked, with or without a list — the contracts against the published P2Flux contracts compiled into the page, the amount shown against the amount signed.
  • Without a list, any recipient a payment names is accepted, as on pay.p2flux.com.

If anything the API answers does not match, the page refuses before the buyer is asked to sign: “nothing was sent”. Payments are still created and confirmed by the P2Flux API; a compromised API could report a payment that did not arrive, so confirm high-value orders in your wallet. A version that confirms payments without the P2Flux API is not available.

Updates

Each release lists what changed. Install it like the first time; your config.js stays. If P2Flux ever moves to new contracts, a checkout release that accepts them comes first, announced in advance in its release notes, before the API switches. A page that is not updated by then refuses payments rather than accept unknown contracts — watch the repository’s releases to be told.

Payment links created with a return_url need checkout 1.3.0 or newer; an older copy refuses them as invalid. Links without one are unaffected. On a self-hosted page the return address of a direct payment is the API’s statement alone (a link carries its own, which the page holds the API to), so the page shows the “Back to …” button and never goes back by itself.

Payment links that carry your invoice number (merchant_ref) need checkout 1.4.0 or newer; an older copy refuses them as invalid. Links without one, and direct payments, are unaffected.

Refunds from a Safe (see Refunds), the accounting statement page (#/statement) and the fee statement page (#/fees) are in checkout 1.4.0 or newer.

The ZIP’s SHA-256 in the GitHub release notes is what ties the files to P2Flux; the SHA256SUMS file inside only proves the files match each other.

Support

Self-hosting is supported as a paid service: installation help, server and header reviews, and priority help with updates. Write to contact@p2flux.com. Questions about payments and the API itself are answered as for every P2Flux user.