One-time payments

Create a one-time payment intent

Signs an intent for one payment to one recipient. The intent is the whole record - P2Flux stores nothing and learns nothing later that the token itself does not carry.

The reference is generated here and never accepted from the caller, deliberately: 32 random bytes carry no meaning, so a shop cannot push an order id, a customer id or an email into P2Flux by putting it in the reference. Keep your own order -> reference mapping.

Store the intent. It is what verifies the payment later, and what recovers it if the callback is lost. An intent whose expiry has passed still verifies and still refunds - see /v1/payments/verify. Minimum amount: 0.01 USDC. Smaller amounts are refused as AMOUNT_OUT_OF_BOUNDS before an intent is created - the hosted verification pipeline cannot be run profitably below one cent. The splitter contract itself has no such floor; the minimum is a hosted-service boundary, applied only when an intent is issued.

post/v1/payments

Request

  • Base URL: https://api.p2flux.com
  • URL: https://api.p2flux.com/v1/payments
  • Auth: none required

Request body

recipientstring required

An EVM address.

amountstring required

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.

gas_payment_mode'native' | 'payment_token'

How the buyer pays the chain's network fee. Omit for native: the buyer sends the transaction and pays gas in the chain's own currency, exactly as every integration written before this field existed. With payment_token the buyer needs none of that currency - P2Flux sends the transaction and the buyer reimburses the quoted network cost in the payment token, plus a flat gas-service fee (0.10 USDC). Ask /v1/capabilities first: an unsupported network or token is refused here with PAYMENT_TOKEN_GAS_UNSUPPORTED rather than after a customer has been sent to a checkout that cannot work.

Example request

{
  "recipient": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "amount": "10.00"
}

Response

The signed intent and everything the checkout needs to build the transaction.

intentstring required

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.

referencestring required

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

amountstring required

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.

expires_atinteger required

Unix seconds. After this the intent cannot START a payment; it can still verify and refund one.

Example response

{
  "intent": "p2f1.k1.eyJ2IjoxfQ.c2lnbmF0dXJl",
  "reference": "0x4c2958875c223c9880b5b6262b0c069ad6727461c6443475ca2690b872e411ad",
  "amount": "10.000000",
  "expires_at": 1787139462,
  "pay": {
    "chain_id": 8453,
    "splitter": "0x5a3bd0945cd0c80b124870881de49a717d20e0d0",
    "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "recipient": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
    "amount_units": "10000000",
    "reference": "0x4c2958875c223c9880b5b6262b0c069ad6727461c6443475ca2690b872e411ad"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.