Share a Payment Link

Payment Links are designed for catalogs, campaigns, donations and support-assisted collection. Each public visit starts a new Checkout Session, so payment addresses and Payment Intents are never shared between customers.

Choose an amount model

• Use fixed amount for a product, plan or known service. Define line items and let Paybytoken calculate the total.
• Use customer-entered amount for donations, account top-ups or variable invoices. Define a minimum, optional maximum and optional suggested amounts.

Create and manage the link from the Merchant Portal or the Payment Links API. The public page uses your checkout branding and enabled stablecoin/network options.

Publish a fixed link

Create links from a trusted server and use an idempotency key tied to the catalog version. A fixed link owns a reusable order template; each customer visit still creates an independent Checkout Session and Payment Intent.

curl https://api-prod.paybytoken.io/api/v1/payment_links \
  -X POST \
  -H "Authorization: Bearer $PAYBYTOKEN_SECRET_KEY" \
  -H "Idempotency-Key: payment-link:starter-pack:v3" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Starter pack",
    "currency": "usd",
    "amount_mode": "fixed",
    "line_items": [
      {
        "quantity": 1,
        "unit_amount": "50.00",
        "product_data": { "name": "Starter pack" }
      }
    ],
    "supported_tokens": [
      { "chain": "base", "currency": "USDC" },
      { "chain": "ethereum", "currency": "USDC" }
    ],
    "collect_customer_email": "auto",
    "metadata": { "catalog_id": "starter_pack_v3" }
  }'

Store the Payment Link ID as the management identifier and publish only its returned public URL. If price or product meaning changes materially, publish a versioned replacement rather than silently changing what an already-shared campaign promises.

Configure customer-entered amounts

Customer-entered links are appropriate only when your business can accept a variable amount. Define a server-controlled minimum and, when applicable, a maximum. Suggested amounts are UI shortcuts, not authorization boundaries.

At checkout creation, Paybytoken validates the submitted amount against the link's active rules. Your webhook handler must still associate the successful Payment Intent with the generated Checkout Session rather than trusting an amount shown by the browser.

Share safely

The public link is intended to be shared. A merchant secret key, internal API response, visit ID or Checkout Session client secret is not. Add your own client_reference_id when starting checkout if you need to correlate a customer or campaign without exposing sensitive data.

Deactivate a link when it should stop accepting new sessions. Existing sessions keep their own expiry and lifecycle; deactivation does not silently cancel a transfer already in progress.

Use this lifecycle:

1. create the link without publishing its URL; newly created links are active;
2. verify branding, amount rules and enabled token combinations, or deactivate it while correcting configuration;
3. activate when necessary and publish the public URL;
4. fulfill each resulting payment from its verified Payment Intent event; and
5. deactivate when the campaign or catalog version ends.

Payment Link activation controls new checkout starts. It is not a kill switch for blockchain transactions already submitted by customers.

Measure without treating analytics as money

Payment Link analytics report visits, checkout starts, successful payments, gross volume and attribution. Use them for conversion analysis. Use Payment Intents, balance transactions and signed webhooks for fulfillment and financial reconciliation.

Use an anonymous campaign or customer reference in client_reference_id. Keep personal data, wallet addresses and secrets out of source, medium and campaign fields. A visit can exist without a checkout, and a checkout can expire without a payment, so conversion stages must remain separate.

Choose another resource when needed

• Use a Checkout Session when your application already owns a specific cart or order.
• Use a Payment Request when one named customer owes a durable balance and may need reminders or partial allocation.
• Use customer balances when funds remain owned by a persistent merchant-scoped customer account.