Payment links

Open a payment link (buyer)

What the checkout calls when a buyer opens a link. One-time kinds return an ordinary intent (pay it as any intent); subscriptions return an ordinary 15-minute setup token; after finalize, the buyer's page joins the link with /v1/links/subscribe, which charges the first period. With payer, when that wallet already has a subscription through this link, the answer carries existing (with cancel and restore sessions) INSTEAD of a setup token - one subscription per wallet per link. This answer is given even after the link expired or the kind was switched off, so a subscriber can always cancel through the link.

Refused with LINK_UNAVAILABLE (reason: CONTRACT_CHANGED) when the contract a one-time link was made for has been replaced: re-minting it on another contract could let an invoice be paid twice.

Request body

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.

payerstring

An EVM address.

Example request

{
  "payer": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9"
}

Response

An intent or a setup token, plus the link's 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.

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.

referencestring

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

intent_expires_atinteger

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

setup_expires_atinteger

Example response

{
  "recipient": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "amount": "10.00",
  "amount_units": "2500000",
  "reference": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
  "existing": {
    "subscription_id": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708"
  }
}

Open a payment link (buyer)

Request

Request body

Example request

Response

Example response

Changes