One-time payments
A signed intent, a transaction the buyer sends from their own wallet, and a server-side verification that decides whether you fulfil.
A one-time payment is a signed intent, a transaction the buyer sends, and a server-side verification. P2Flux stores none of it: the intent carries its own contents, and verification re-reads the chain.
No server of your own? A payment link is an invoice or a fixed price you send as a URL, and the checkout creates the intent when the buyer opens it.
Create a payment
Mint a payment intent. Unknown fields are rejected outright.
There is deliberately no reference field. P2Flux generates it, so customer ids and emails cannot be pushed into the payment layer even by accident. Your order number goes in merchant_ref instead, under rules that keep it out of the chain.
Your order number
Send merchant_ref (SDK: merchantRef in JavaScript, 'merchant_ref' in PHP) and it comes back wherever the payment does: resolve, verify, recover, the payment.paid webhook and refund verification. P2Flux stores nothing — it rides inside the signed intent.
- 1 to 64 ASCII letters, digits and . _ : / # -. No spaces and no @, so an e-mail address is refused. Anything else answers INVALID_REQUEST (400) before an intent exists.
- Signed, not encrypted: the buyer sees it. Anyone holding the intent can read it. Use an order or invoice number, never a name, an e-mail address or other personal data.
- The reference on chain is keccak256("p2flux.merchant_ref.v1" || reference_salt || merchant_ref), with a fresh random salt per payment. The chain shows only the hash: the same order number paid twice gives two unrelated references, and nobody can guess the number from it.
- With the salt, anyone can prove the payment on chain was created with that merchant_ref, without asking P2Flux — see Proving a payment to an auditor.
- merchant_ref alone is not proof that a payment is yours. Anyone can create a payment to your wallet with your invoice number. Every answer that echoes it adds merchant_ref_verified: true only when the request that created the payment (or link, or subscription) carried a merchant token for the receiving wallet, or a partner key.
Match a payment or notification on the reference (or intent) you stored for the order, and on the amount — never on merchant_ref alone. merchant_ref_verified tells you the creator proved control of the receiving wallet.
Proving a payment to an auditor
Give the auditor the transaction, the merchant_ref and the reference_salt. The reference in the transaction’s Paid (or SponsoredPaid) event must equal the hash of the three parts below, as UTF-8 bytes and the 32-byte salt, concatenated:
This proves the payment was created with that merchant_ref — not by itself that it is your order: anyone can create a payment to your wallet with your invoice number. That the payment belongs to the order comes from your own records (the intent or reference you stored when you created it), or from merchant_ref_verified: true (the creator proved control of the receiving wallet).
Check it with Foundry’s cast, or any Keccak-256 tool:
In code, both SDKs check it locally: checkMerchantRef(reference, salt, 'INV-1042') in JavaScript, P2FluxClient::checkMerchantRef($reference, $salt, 'INV-1042') in PHP. Only payments created by POST /v1/payments with a merchant_ref commit to it; payment links and subscriptions carry it in their signed token only.
Who pays the network fee
By default the buyer sends the payment transaction and pays the chain’s network fee in its native currency — ETH on Base. That is gas_payment_mode: 'native', it is what happens when you send no such field, and its fees are unchanged.
With gas_payment_mode: 'payment_token' the buyer needs no ETH at all. They sign one authorization; P2Flux submits the transaction and pays the ETH, and the buyer reimburses that cost in USDC, inside the same transaction; the merchant-funded fixed network fee of 0.10 USDC comes out of the amount, as on a subscription. If the transaction fails, both halves fail: the buyer is charged nothing.
GET /v1/capabilities says which networks, tokens and operations support this. Architectural possibility is not support: a token that implements the right standards on a network P2Flux has not deployed to reports false, and every request for it is refused deterministically.
A quote expires. That same instant is inside the buyer’s signature, so a stale quote cannot be executed by anyone — if it lapses, ask for a fresh one and let the buyer sign again. The quoted fee is a price agreed in advance, not a measurement of the gas the transaction turns out to use; what it actually cost is reported separately for reconciliation.
Private payments (Hinkal)
With private_payment: 'hinkal' the hosted checkout shows a second button, Pay privately with Hinkal, next to the wallet list. It opens a separate page, private.pay.p2flux.com, where the buyer pays from their Hinkal shielded balance: Hinkal’s Emporium contract calls the same splitter every payment uses. Settlement, verification, the reference and your fees are unchanged, and the normal wallet payment stays available. Offer it only if you want to; omit the field and nothing changes.
Amount, recipient and time are on chain as for every payment; the buyer’s wallet is not. Hinkal’s server builds the proof and sees the buyer’s Hinkal account and this payment. Base Mainnet only: the test API on Base Sepolia refuses the field, because Hinkal does not run there. Subscriptions cannot be paid privately.
Resolve
Authoritative terms for a checkout to display.
The hosted checkout calls this; you only need it if you are building your own payment page. It exists because a browser must never trust what it can decode out of a token itself — a tampered intent has to fail here, before anyone is shown or asked to sign anything.
It also asks the contract whether the payment is still payable, so a buyer is never sent to their wallet for a transaction that would revert.
The response includes confirmations_required — how deep the server will require the transaction to be before verification says valid. A checkout can wait that depth out on its own RPC and then verify once, instead of polling while the blocks accumulate; the hosted checkout does exactly that. Advisory only: the server applies the policy itself regardless.
Present the payment
Open the hosted checkout at <checkout>/#/pay/<intent>. The intent travels in the URL fragment — the part after the #. Browsers do not put a fragment in the HTTP request or in the Referer header, so it does not reach the server or its access logs, and the checkout clears it from the address bar once it has read it. It is still a value present in the page: treat it as a secret with respect to anything else running there, and keep it out of client-side analytics and error reporting.
The checkout reports back to the opening page by postMessage. Check the origin, and treat the message as a prompt to verify rather than as proof of payment.
Send the buyer back
A shop that sends the buyer to the checkout instead of opening a window (a redirect, as most payment providers work) passes return_url when it creates the payment and sends the buyer to checkout_url. After a confirmed payment the page shows a button naming your site (“Back to shop.example”) and, when it was not opened as a window, goes back by itself after about three seconds. A page opened as a window shows the button only; your page takes over from the p2flux.payment.completed message.
The address must be https (http is accepted on the test network only, for a shop on localhost), without a user name or password, not a P2Flux address or one that reads like it, at most 512 characters; your query is kept and a fragment is dropped. It is signed into the intent, so nobody but P2Flux’s own API can change where the buyer is sent; a self-hosted checkout therefore shows the button and never goes back by itself.
Anyone can open your return address with any parameters. Confirm the payment with /v1/payments/verify (or a webhook) before delivering anything, exactly as without it.
Verify
Server-side proof that a payment landed. Never skip it.
Takes the intent and the tx_hash. Everything is checked against the receipt: the settlement id derived from token, recipient, amount and reference; the recipient and token actually paid; that net plus fee equals the signed amount; that the fee is exactly 1%; that the USDC transfers happened; and that the transaction is three confirmations deep.
It optionally takes a third field, settlement_receipt — the sealed token a previous successful verification of this same payment returned, couriered to your page by the hosted checkout in the p2flux.payment.completed message. Presenting it lets the server answer immediately without re-reading the chain. It is opaque, short-lived, and bound to exactly this intent and transaction on this network: a missing, expired, tampered or mismatched receipt is silently ignored and the full verification runs instead. Always safe to pass along whatever the browser handed you — the server, never the receipt, is the authority.
This endpoint does not signal outcomes with HTTP status codes. Every answer it reaches — success or not — is HTTP 200, carrying either the success object or { "valid": false, "code": … }. Branch on valid, not on the status code. Only transport-level failures differ: a malformed body is 400, too many requests is 429, and an unexpected server fault is 500.
A successful verification returns valid: true with tx_hash, reference, amount, block_number, block_hash and the settlement_receipt described above, plus merchant_ref and reference_salt when the payment was created with one, and screening_list (version, fetched_at): which sanctions list screening was answered from — keep it with the verdict. Anything else returns valid: false and one of these codes:
What PAYMENT_CONFIRMING means
It means the payment cannot yet be proved — not that it succeeded. One code covers two situations the API cannot tell apart from the outside:
- A transaction exists and is mined, but is not yet three confirmations deep.
- No receipt has been seen for that hash at all — it may be pending, the node answering may not have caught up, or no such transaction may ever have been broadcast.
Absence of a receipt is deliberately treated as “keep waiting” rather than “nothing happened”, because telling someone who has just paid that their transaction does not exist is the worse of the two mistakes. That is precisely why the code must not be read as confirmation of payment.
Do not fulfil until you get valid: true. While the answer is PAYMENT_CONFIRMING, keep the same tx_hash and verify again — do not send the buyer back to checkout, and do not create a second intent. A new intent carries a new reference, which the contract will settle a second time.
Confirming answers carry a Retry-After header naming the sensible pause (a few seconds — settlement on Base takes seconds, not minutes). Honour it: the server also remembers its last verdict per payment for a short window, so re-asking faster than the header just returns the same answer from memory.
Expiry
An intent expires one hour after creation by default. Expiry governs starting a payment: after it, /v1/payments terms can no longer be resolved and a checkout will not open with that intent. Create the intent when the buyer is ready to pay, not when the cart is built.
Verification and refunds deliberately ignore the intent’s expiry. A transaction that settled while the intent was live is an irreversible fact and stays true an hour later, so a payment broadcast in the last seconds of an intent’s life and confirmed after it can still be verified and still be refunded. Everything else about the token is checked exactly as strictly — the signature, the deployment binding, the field shapes — because it is the signature that proves the terms, and signatures do not expire.
Replay protection
The contract records each settlement by an id derived from the token, recipient, amount and reference, and refuses a second one. Because the reference is fresh per intent, the same buyer can re-order the same item at the same price as often as they like — but one receipt can never be used to verify two orders.
If the browser callback never arrives
The p2flux.payment.completed message is how you normally learn the transaction hash. It is a browser event, so it can be lost: the buyer closes the popup, the tab crashes, the phone locks, the connection drops between signing and delivery.
Find the settling transaction from the intent alone.
Send the intent and nothing else — no hash, no hint. P2Flux searches the chain for the settlement that intent describes and verifies anything it finds the ordinary way.
Recovery can search a wide range of blocks, which makes it the most expensive call this API offers. It runs at low priority, so recovering yesterday’s payment gives way to taking today’s, and it is limited to 30 calls a minute per caller and 6 per payment. Use it when a callback is missing — the normal flow is still checkout, transaction hash, verify, and recovery is not a substitute for it.
Two things still make this smoother, and both are your side of the integration: persist the intent and reference against the order before the buyer is sent anywhere — recovery needs the intent — and never respond to a missing callback by creating a second intent. The replay guard protects the first reference, not a new one, so a second intent is a second payment the buyer can genuinely be charged for.
Refunds
Supported, as a transfer from your wallet back to the payer — P2Flux derives the terms from the original settlement and verifies the result, but never holds or sends the money. Partial amounts are allowed. Full detail in Refunds.
A completed blockchain payment cannot be undone. A refund is a second payment going the other way, which is why it costs you gas and why P2Flux cannot make it happen on your behalf.
P2Flux keeps no global refund ledger, so nothing in the API prevents a second refund of the same payment. Your integration has to. See Refund idempotency.