Refunds

Lock the terms of a refund

A refund is a plain USDC transfer from the merchant's own wallet to the wallet that paid. There is no refund contract, no relayer and no P2Flux custody in the path: P2Flux charges no refund fee, returns none of its original commission, and the merchant pays the gas.

Everything is derived from the chain. You supply identifiers and an integer amount - there is no field for a recipient anywhere in this API, because a refund endpoint that accepted one would be a withdrawal endpoint.

P2Flux keeps no refund history. It cannot tell you whether a payment was already refunded, and calling this twice will happily prepare two valid refunds. One refund per payment is your integration's rule to enforce, and the safe place is BEFORE this call: reserve the order row atomically, then prepare.

The returned refund_token is short-lived and for a browser only. Do not store it - reconciliation later goes through /v1/refunds/verify with the original settlement, which needs no token.

Request body

intentstring

A signed P2Flux capability: payment intent (p2f1.), setup token (p2setup2.), subscription capability (p2s2.), cancel token (p2cancel1.) or refund token (p2refund1.). Opaque to the caller and unforgeable - the signature is what authorises the call. Treat it as a bearer secret: keep it server-side, never in a URL query or a log.

subscriptionstring

A signed P2Flux capability: payment intent (p2f1.), setup token (p2setup2.), subscription capability (p2s2.), cancel token (p2cancel1.) or refund token (p2refund1.). Opaque to the caller and unforgeable - the signature is what authorises the call. Treat it as a bearer secret: keep it server-side, never in a URL query or a log.

tx_hashstring required

A 32-byte hex value, lowercase. Transaction hashes and references.

period_indexinteger

Recurring only. Refunds are per charge, never per subscription.

amountstring required

An integer count of micro-USDC (6 decimals), as a string. 2500000 is 2.50 USDC. Used wherever a decimal would invite a rounding error - notably refund amounts.

Example request

{
  "tx_hash": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
  "amount": "2500000"
}

Response

Terms for the merchant's wallet to send.

refund_tokenstring

A signed P2Flux capability: payment intent (p2f1.), setup token (p2setup2.), subscription capability (p2s2.), cancel token (p2cancel1.) or refund token (p2refund1.). Opaque to the caller and unforgeable - the signature is what authorises the call. Treat it as a bearer secret: keep it server-side, never in a URL query or a log.

chain_idinteger

tokenstring

An EVM address.

merchantstring

An EVM address.

payerstring

An EVM address.

original_amountstring

A USDC amount as a decimal string, up to 6 decimal places. Never a JSON number: binary floating point cannot represent most decimal prices exactly, and this is money.

original_amount_unitsstring

An integer count of micro-USDC (6 decimals), as a string. 2500000 is 2.50 USDC. Used wherever a decimal would invite a rounding error - notably refund amounts.

refund_amountstring

A USDC amount as a decimal string, up to 6 decimal places. Never a JSON number: binary floating point cannot represent most decimal prices exactly, and this is money.

refund_amount_unitsstring

An integer count of micro-USDC (6 decimals), as a string. 2500000 is 2.50 USDC. Used wherever a decimal would invite a rounding error - notably refund amounts.

expires_atinteger

Unix seconds; about fifteen minutes out.

Example response

{
  "token": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "merchant": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "payer": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "original_amount": "10.00",
  "original_amount_units": "2500000",
  "refund_amount": "10.00",
  "refund_amount_units": "2500000"
}

Lock the terms of a refund

Request

Request body

Example request

Response

Example response

Changes