Refunds
A refund is a transfer from your wallet back to the payer. P2Flux works out who and how much, and verifies it afterwards — it never holds the money in between.
A refund is a transfer from the merchant’s wallet to the payer’s. P2Flux works out who and how much from the original settlement, locks those terms so they cannot be edited in a browser, and verifies afterwards that the transfer happened. It never takes custody and never sends the transaction itself.
How a refund works
A completed blockchain payment cannot be reversed — that is true of the chain, not a P2Flux limitation. So a refund is a second, separate payment going the other way, and the endpoints here exist to make that safe rather than to move money.
Neither endpoint accepts a destination address, a merchant or a maximum from the caller. All three are derived from the original settlement on chain. If a caller could name the destination, a refund button would be a withdrawal form.
1. Lock the terms
Work out the refund from the original settlement and lock it.
Exactly one of intent or subscription identifies the settlement, and either way the transaction hash is required: the capability says what was authorized, the receipt says what actually happened.
The response returns refund_token, chain_id, token, merchant, payer, the original_amount and the refund_amount (each with a base-unit twin), and expires_at.
It lives fifteen minutes and exists only to carry the terms to a browser. Reconciliation later uses /v1/refunds/verify with the original settlement, which needs no token at all.
2. The merchant sends it
Open the hosted checkout at <checkout>/#/refund/<refund_token> and connect the merchant wallet. The checkout shows the locked terms and sends the transfer.
Before the merchant’s wallet is asked to send, the checkout — hosted or self-hosted — reads the original payment the refund names from the chain itself: the refund must go to the wallet that made that payment, come from the wallet that received it, and be no more than was paid. Check in your wallet that the payer and amount are the ones of the order you are refunding.
It reports back to the opening page by postMessage, twice: p2flux.refund.sent when the transaction is broadcast, and p2flux.refund.confirmed once it has settled. Both carry tx_hash.
You can also skip the checkout entirely. Nothing here is privileged: a refund is a plain token transfer of refund_amount to payer, so a treasury tool or a script that already holds the merchant key can send it and you verify the result the same way.
When the refund is confirmed, the checkout offers a refund receipt to download (CSV or JSON): the original transaction, the refund transaction, the amount, both wallets and the original payment’s merchant_ref when known. Refunds also show on your accounting statement, even when the payment was in an earlier month.
Refunds from a Safe
If your merchant wallet is a Safe, the people who handle refunds do not need the Safe’s owner keys. Give a support wallet a daily USDC limit with Safe’s own Allowance module (in the Safe app: Settings → Setup → Spending limits, token USDC, reset every day). The Safe keeps the money; the support wallet can only move up to its limit per day.
Open the refund link and connect the support wallet. The checkout sees that it is not the Safe, reads its remaining limit from the module, and sends the refund through it: the USDC still goes straight from the Safe to the wallet that paid, for the locked amount only, after the same check of the original payment. Verification is unchanged, because the transfer is from the Safe. If the limit left today is too small, nothing is sent (REFUND_ALLOWANCE_LOW).
The Allowance module is Safe’s, already on Base and Base Sepolia at 0xAA46724893dedD72658219405185Fb0Fc91e091C; the checkout only accepts that address. P2Flux holds nothing and can move nothing; the limit is yours to change or remove in the Safe.
3. Verify it landed
Confirm the refund happened, and that it is settled.
Takes the original settlement again — tx_hash plus intent or subscription and period_index — with refund_amount in base units and refund_tx_hash. Deliberately not the prepare token, so you can reconcile hours or days later, after a crash or a support ticket, without having kept a fifteen-minute token alive.
A settled refund returns status: "REFUNDED" with refund_tx_hash, refund_amount, original_amount, payer, merchant and block_number.
Refunding a renewal
Refunds are per charge, never per subscription. Identify the renewal with the capability, the transaction that charged it, and its period_index. Refunding one renewal does nothing to the subscription itself: it stays active and the next renewal will still be due.
The refundable amount is what the customer was charged for that period, excluding the network cost they reimbursed. To stop future charges as well, the customer cancels — see Cancel and revoke.
Refund idempotency
A refund is a real wallet-to-wallet USDC transfer. P2Flux verifies that a refund matches the original payment, but the stateless API does not track whether you have already issued another refund for that payment. Nothing here will stop a second one, and a second one moves real money out of your wallet. Your integration must enforce refund idempotency.
P2Flux does not keep a global refund ledger. That is the same statelessness that means we never hold your money — and it has the same consequence in both directions: no record for anyone to freeze, and no record to check against.
So refund limits are enforced by the merchant integration, which is the only part of the system that knows what an order is:
- Through an official P2Flux integration, this is already handled. Each one keeps its own refund record and refuses a second refund for the same payment — Tipster Script does today, and the same holds for commerce plugins as they arrive.
- Through the SDKs or the API directly, it is yours to implement. Persist refund state against your own order record and block duplicate sends before they reach a wallet. Neither SDK does this for you: they are thin clients over the API and keep no state of their own.
Record the refund against the order the moment you call /v1/refunds/prepare, not after the transfer confirms — the gap between sending and confirming is exactly where a retry or a double-click lands. Reconcile later with /v1/refunds/verify, which needs no token and works days afterwards.