Use Payment Links

A Payment Link is a reusable, Dashboard-visible checkout template. Use it when an operator can manage a published offer and your website, CRM, campaign, message, or QR code only needs a stable URL.

Creating, editing, previewing, or resolving a Payment Link does not itself create a commercial obligation. When the hosted checkout initializes, Pharos creates or resumes a concrete Checkout Session that snapshots the offer. From that point onward it uses the same checkout and payment pipeline as an API-created session.

Prerequisites

• Products and Prices exist for every item in the offer.
• The Payment Link is ACTIVE and has not passed expiresAt.
• At least one valid payment route supports the intended country and currency.
• Branding, custom fields, promotion codes, installments, and checkout settings are configured as needed.
• A webhook endpoint is ready to receive the authoritative payment result.

Configure and publish

1. Create or select the Products and Prices you want to sell.
2. Create the Payment Link in Dashboard or through the Payment Links API.
3. Configure the offer, custom fields, promotion codes, allowed installments, branding, and expiration.
4. Activate the link and copy its hosted /checkout/:slug URL.
5. Publish that URL on your site, in a campaign or message, or as a QR code.
6. Complete a sandbox purchase and verify your webhook handler before going live.

<a href="https://checkout.example.com/checkout/summer-offer">
  Buy now
</a>

The URL is the capability that opens the offer. Keep campaign parameters on the published URL when you need attribution. A custom domain changes the public host, not the Payment Link identity or its downstream lifecycle.

Runtime flow

1. Buyer → merchant channel: The buyer clicks the reusable URL on your site, campaign, message, or QR code.
2. Browser → Pharos Checkout: Pharos resolves the active Payment Link and renders its hosted route without creating an invoice or payment.
3. Checkout → Collections: The checkout initializes the interactive flow. Collections creates a new Checkout Session snapshot, or resumes the matching open session stored for that browser tab.
4. Collections → Checkout: The snapshot supplies stable items, prices, recurrence, fields, promotion settings, installments, and expiration for this attempt. Later Payment Link edits cannot rewrite it.
5. Buyer → Checkout: The buyer provides contact and billing information, selects an available country, currency, and payment method, and submits the purchase.
6. Checkout → shared commerce pipeline: Pharos validates the server-owned snapshot, prepares the final quote, and creates the applicable customer, invoice, subscription, payment, and payment-attempt records.
7. Pharos ↔ payment provider: The provider may return an immediate result, request another action or redirect, or leave the payment processing asynchronously.
8. Pharos → buyer: Checkout shows success, processing instructions, a retryable failure, or the next required action.
9. Pharos → your webhook endpoint: Lifecycle events describe the checkout attempt. Your system fulfills only after verifying the signed purchase_succeeded event.

Reusable template and session snapshot

The Payment Link and its Checkout Sessions have independent lifecycles:

• Editing products, prices, fields, promotion settings, or installments affects only sessions created later.
• Setting the link to INACTIVE, expiring it, or deleting it prevents new sessions.
• An already-open session keeps the snapshot created for that buyer attempt until the session completes or expires.
• Refreshing the same flow can resume its matching open session; the public URL remains /checkout/:slug.
• Dashboard preview remains presentation-only and creates no Checkout Session, invoice, subscription, or payment.

Understand the outcome

Checkout Session status and paymentStatus answer different questions:

A browser success page or checkout_session_completed webhook is not proof that funds were collected. Asynchronous payment methods may finish after the buyer has left checkout.

Troubleshooting

• The link is not found: Confirm the slug, active status, deletion state, and expiration.
• The offer has no valid price: Confirm every linked product has a Price and that the cart has a valid composition.
• A country, currency, or method is missing: Confirm the full cart supports it and that an enabled payment connection and route are available.
• Recent edits are not visible: Start a new attempt. An existing session intentionally keeps its original snapshot.
• A buyer appears stuck: Retrieve the related session and compare its status, paymentStatus, and expiration before asking the buyer to retry.
• Your system did not fulfill: Check signature verification, duplicate handling, delivery attempts, and whether purchase_succeeded was received.

Next steps

• Compare with Cart Checkout
• Implement Collections Webhooks
• Review Checkout Concepts