Payment links

Create a payment link

Signs a link - nothing is stored. Send link to buyers as <checkout>/#/link/<link> (the SDKs build it: checkoutLink('link', link)); keep manage for yourself and open it as <checkout>/#/links/<manage>.

  • once: an invoice. Every open mints an intent with the same reference, so the contract itself refuses a second payment. Expires in at most 30 days (default 7).
  • reusable: a fixed price, payable any number of times until it expires (at most a year).
  • subscription: a recurring payment. Each buyer signs once and pays the first period at once (/v1/links/subscribe); P2Flux keeps the subscription and collects every later period. When the buyer cannot pay, it retries after 1 hour, 6 hours and then daily, within the first quarter of the period (at most 3 days), then skips the period; three periods in a row the buyer could not pay end it. Periods missed because of trouble on P2Flux's side never count against the buyer. Period at least one day.

Which kinds a deployment offers is its choice; a kind not offered answers LINK_UNAVAILABLE.

LINK_UNAVAILABLE carries a reason: KIND_NOT_OFFERED (this deployment does not offer that kind), CONTRACT_CHANGED (the settlement contract a one-time link was made for was replaced), SUBSCRIPTIONS_FULL (the list of subscriptions P2Flux collects is at its capacity).

post/v1/links

Request

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

Request body

kind'once' | 'reusable' | 'subscription' required
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.

labelstring

Optional note for the buyer, shown as “Note from the link’s creator · not verified by P2Flux”: up to 60 characters; letters, ASCII digits, currency signs, spaces and . , : ; ' ( ) # & + _ ! ? % - / ; nothing that reads as a web or e-mail address (no letter after a full stop), no look-alike letters mixed from other scripts, and no mention of P2Flux or 'verified'.

expires_atinteger

Unix seconds, between about 1 hour and 30 days (once) or 366 days (other kinds) from now; a value a few minutes above the maximum is clamped to it.

gas_payment_mode'native' | 'payment_token'

One-time kinds. Fixed for the link's whole life.

periodinteger

Subscription: seconds between charges, at least 86400.

periodsinteger

Subscription: number of charges (1-1200); omit for until cancelled.

suspend_after_daysinteger

Subscription links: days without a successful payment after which a subscriber is paused (suspended, not ended); a successful collect restarts it.

Example request

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

Response

The signed link, its private manage token and its terms.

kind'once' | 'reusable' | 'subscription' required
idstring required

16 random bytes. Every payment through a one-time link has a reference that starts with it.

chain_idinteger required
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.

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

labelstring

The merchant's note, shown to the buyer as "Note from the link's creator, not verified by P2Flux".

created_atinteger required
expires_atinteger required

Unix seconds. After this the link takes no new payments or subscriptions; payments made before stay valid and subscriptions already signed keep being collected.

gas_payment_mode'native' | 'payment_token'

One-time kinds only.

periodinteger

Subscription only: seconds between charges (at least one day).

periodsinteger

Subscription only: number of charges; absent = until cancelled.

suspend_after_daysinteger

Subscription links: days without payment before a subscriber is paused.

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

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

Example response

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

Changes

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