PFlux
DOCS
GitHub Integration enquiries
PAYMENTS/ONE-TIME PAYMENTS

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.

ENDPOINTS3
ASSETUSDC
FEE1%
INTENT TTL1 hour

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

POST/v1/payments

Mint a payment intent. Unknown fields are rejected outright.

FIELDTYPEREQUIREDNOTES
recipientstringYesAddress that receives the payment. 0x + 40 hex characters.
amountstringYesDecimal USDC, e.g. "100.00". Up to 6 decimal places and 12 integer digits. Minimum 0.01 — smaller amounts are refused as AMOUNT_OUT_OF_BOUNDS before an intent exists. (A hosted-service boundary, not a contract rule: the splitter itself has no floor.)
gas_payment_modestringNonative (the default) or payment_token. See Who pays the network fee. Omit it and nothing changes.
private_paymentstringNohinkal: also offer the buyer a private payment from a Hinkal balance. Base only, not with payment_token. See Private payments.
notify_urlstringNoAn https address P2Flux notifies once this payment is verified on chain. See Webhooks. Omit it and nothing changes.
return_urlstringNoWhere the hosted checkout sends the buyer after paying. See Send the buyer back. Omit it and nothing changes.
merchant_refstringNoYour own order or invoice number, 1 to 64 characters. The on-chain reference becomes a commitment to it. See Your order number. Omit it and nothing changes.

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.

RESPONSEWHAT IT IS
intentSigned token. Everything else is derived from it; this is what the checkout needs.
reference32 random bytes. Your handle on this payment — store it against the order.
amountThe amount, formatted to six decimals.
expires_atUnix seconds. One hour after creation by default.
payChain id, splitter, token, recipient, amount in base units and the reference — the parameters of the transaction.
checkout_urlThe hosted checkout for this payment (pay.p2flux.com on Mainnet, pay-test.p2flux.com on the test network): open it, or send the buyer there.
return_urlOnly when you sent one: the address as kept.
merchant_ref, reference_saltOnly when you sent merchant_ref: it, and the random 32-byte salt P2Flux chose for the commitment. Store both with the order.
merchant_ref_verifiedOnly when you sent merchant_ref: true when this request proved control of the receiving wallet (a p2flux-merchant-token for recipient, or a partner key), else false.

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.
RULE

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:

commitment
reference = keccak256( "p2flux.merchant_ref.v1"  ||  reference_salt (32 bytes)  ||  merchant_ref )

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).

TEST VECTORVALUE
salt0x1111111111111111111111111111111111111111111111111111111111111111
merchant_refINV-1042
reference0x03f0752ac8d6e9e6b5bffa5a84881ce0d69c595da28be9ddd91fca4306478f52

Check it with Foundry’s cast, or any Keccak-256 tool:

terminal
cast keccak $(cast concat-hex $(cast from-utf8 p2flux.merchant_ref.v1) \
  0x1111111111111111111111111111111111111111111111111111111111111111 \
  $(cast from-utf8 INV-1042))
# 0x03f0752ac8d6e9e6b5bffa5a84881ce0d69c595da28be9ddd91fca4306478f52

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.

1Create the payment with the mode. An unsupported network or token is refused here with PAYMENT_TOKEN_GAS_UNSUPPORTED — before a customer sees anything.
2The hosted checkout resolves it and receives a quote: the buyer’s network fee, the buyer’s total, and an expiry a couple of minutes out.
3The buyer signs the token authorization for that exact total. No transaction, no ETH.
4P2Flux submits it. The price, the P2Flux fee, the fixed network fee and the buyer’s network fee are split in one transaction.
5/v1/payments/verify returns the usual verdict plus an accounting block naming every unit.
ASK BEFORE YOU OFFER IT

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.

1The buyer needs a Hinkal balance first; the page does not take deposits. Hinkal charges the buyer its own fee on top (about 0.02 USDC plus 0.1%). Your amount arrives in full, minus the usual P2Flux fee.
2On chain the payer is Hinkal’s contract, not the buyer’s wallet. /v1/payments/verify reports accounting.refundable: false.
3No automatic refund: /v1/refunds/prepare answers REFUND_PAYER_UNSUPPORTED, because money sent to that contract would not reach the buyer. Ask the buyer for an address and send it yourself.
WHAT STAYS PUBLIC

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

POST/v1/payments/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.

MESSAGEDIRECTIONPAYLOAD
p2flux.readycheckout → your page—
p2flux.helloyour page → checkoutAnswer to p2flux.ready.
p2flux.payment.completedcheckout → your pagetx_hash, reference, settlement_receipt

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.

QUERY PARAMETERVALUE
p2flux_referenceThe payment’s reference — find the order with it.
p2flux_txThe transaction hash, when known.
p2flux_statuspaid, or confirming when the transaction is sent but not yet deep enough (no automatic return then; the buyer can still go back).

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.

THE RETURN IS NOT PROOF

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

POST/v1/payments/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.

ONE RESPONSE SHAPE

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:

PAYMENT_CONFIRMINGNot yet provable. Either the transaction is not deep enough, or no receipt has been seen for that hash at all. Keep the same hash and verify again — see below.
TRANSACTION_REVERTEDThe transaction was mined and failed. Nothing moved.
INVALID_REFERENCEThe receipt does not contain this payment.
TERMS_MISMATCHRecipient, amount or fee in the receipt does not match the intent.
WRONG_TOKENThe expected USDC movements are not in the receipt.
PAYMENT_ALREADY_PROCESSEDThe contract has already settled this exact payment.
INVALID_INTENTThe intent is malformed, forged or for another deployment.

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.

THE RULE

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.

READING HISTORY IS NOT LIMITED BY EXPIRY

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.

POST/v1/payments/recover

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.

found: trueThe payment exists. The response carries the ordinary verification result alongside it, so a recovered payment is proved to the same standard as one you verified with a hash you were given.
found: true, valid: falseThe transaction was found but does not yet verify — most often still confirming. Carries tx_hash and a code; treat it exactly as you would that code from verify.
found: falseNothing settled as of the block in as_of_block. This is a statement about now, never a verdict. A payment broadcast late can still arrive, so never record the order as unpaid on the strength of it — ask again later.
COST

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.

NOT A REVERSAL

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.

IDEMPOTENCY IS YOURS

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.

Something more than a standard integration?
Marketplace flows, platform billing and custom settlement logic.
Discuss an integration