Payment links

What a link has collected

Send exactly one of link or manage. With the link: the terms, state (open/expired) and, for an invoice, whether it is paid. With the manage token: the same plus who paid - for a reusable link the payments found on chain (read in steps; complete: false means ask again for more), for a subscription link its subscribers with their last charge and next attempt. Answers already read from the chain are remembered, never read twice.

Request body

linkstring

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

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.

Response

The link's terms and what it has collected.

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.

state'open' | 'expired'

paidboolean

completeboolean

linkstring

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.

finalboolean

Reusable links: no later payment is possible (the link and every intent opened from it have expired).

truncatedboolean

More than 5,000 payments: the list stops there.

codestring

Invoice links: why a payment found on chain is not counted yet (e.g. PAYMENT_CONFIRMING).

Example response

{
  "recipient": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "amount": "10.00",
  "amount_units": "2500000",
  "payment": {
    "tx_hash": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
    "reference": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
    "amount_units": "2500000",
    "payer": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9"
  },
  "payments": [
    {
      "tx_hash": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
      "reference": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
      "amount_units": "2500000",
      "payer": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9"
    }
  ],
  "subscribers": [
    {
      "subscription_id": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
      "payer": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
      "last_tx": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708"
    }
  ]
}

What a link has collected

Request

Request body

Response

Example response

Changes