Skip to main content
A pay link is a durable URL that creates Lightning payment attempts for a fixed destination and recipient. A fresh visit to /pay/<shortId> starts checkout through a mobile Cash App handoff page or a desktop QR page. The link has no expiry, but each payment attempt has its own invoice deadline. Reopening an attempt does not renew it.

​
Create

Pay links are server-key only. Create one that delivers 25 USDC on Base to a fixed recipient:
Replace SERVER_KEY with your fn_... key. Use a new X-Idempotency-Key for each operation and reuse it when retrying that same request. Amounts are integer strings in the asset’s smallest unit: "100000" is 0.001 BTC; "50000000" is 50 USDC on Base. Read each asset’s decimals from /routes.
The response is 201 with { payLink }, including id, shortId, and a configured shortUrl. Supported assets are USDB, USDC, USDT, and PathUSD, subject to the API’s destination constraints. Hedera is excluded.

​
Amount modes

Send exactly one:
  • amountOut: exact-out delivery in destination smallest units, in whole cents. Invoice-funded fees increase the payer’s amount; partner-invoiced platform fees are separate.
  • amountFiatUsd: "1.00" to "50000.00", converted at visit-time spot. Eligible invoice-billed stablecoin payments use exact-out automatically; otherwise exact-in applies and deducted fees reduce delivery.
Use the order’s returned economics and expiresAt. The payer app controls its USD display.

​
Manage

  • GET /v1/pay-links: paginated list; disabled links are excluded by default.
  • GET /v1/pay-links/:id: read one link.
  • DELETE /v1/pay-links/:id: disable with X-Idempotency-Key. The URL returns 404; existing orders are unaffected.

​
Reconciliation

Orders carry payLinkId and payLinkLabel in webhooks. History has no pay-link filter; query by recipientAddress and match webhook payLinkId.

​
Restrictions

Pay links are not available to residents of New York City. Pay-link endpoints are not part of the OpenAPI spec; this page and Pay links API are the reference.