Collections
Choose how your business will send buyers to Pharos-hosted checkout and collect payment.
Collections covers inbound selling and payment collection. It is separate from Payments, which covers outbound payments to recipients and suppliers.
Both collection models end in the same Pharos-hosted checkout. A Payment Link is a reusable offer managed by an operator. A Checkout Session is one concrete cart created by your backend. Once a session exists, both models use the same checkout, invoice, subscription, gateway, payment, and webhook pipeline.
Find your use case
| Use Payment Links | Cart Checkout | |
|---|---|---|
| Best for | A fixed or reusable offer published by an operator | A cart whose contents are decided by your application |
| Setup | Dashboard first; API access is optional | Backend integration with the /api/v1 API |
| Catalog | Uses configured Products and Prices | Uses catalog priceId values or inline priceData |
| Public URL | Reusable /checkout/:slug URL | One /checkout/session/:id URL per cart |
| Cart changes | Edit the Payment Link for future sessions | Mutate an open session with Idempotency-Key and If-Match |
| Buyer experience | Pharos-hosted checkout | The same Pharos-hosted checkout |
| Fulfillment | Wait for the signed purchase_succeeded webhook | Wait for the signed purchase_succeeded webhook |
Use Payment Links
Choose Use Payment Links when an operator can define the offer in Dashboard and publish the same URL on a website, campaign, message, or QR code. It is the fastest path when the offer is reusable and your application does not need to construct the cart at runtime.
Cart Checkout
Choose Cart Checkout when your backend owns the cart, needs inline pricing, or must add, update, or remove items before redirecting the buyer. Your API key remains on your server; the browser only receives the hosted checkout URL.
Before you start
For either model:
- Configure at least one payment connection and a valid route for the countries and currencies you intend to support.
- Decide whether you are collecting a one-time payment, starting a subscription, or using a trial or mixed cart.
- Configure a webhook endpoint before going live.
- Treat the buyer redirect as navigation only. Fulfill only after verifying
purchase_succeeded.
Payment Links also require configured Products and Prices. Cart Checkout may use the catalog or snapshot inline priceData without creating catalog records.
Shared runtime after session creation
- Pharos persists a Checkout Session. A Payment Link is snapshotted when its hosted flow initializes; an API integration creates the session directly.
- The buyer completes hosted checkout. Pharos collects the required customer and billing information and offers only payment routes valid for the session.
- Pharos prepares the commercial records. The shared pipeline calculates the final quote and creates the applicable customer, invoice, subscription, payment, and attempt records.
- The payment provider responds. The outcome may be immediate, require a redirect or action, or remain processing for an asynchronous method.
- The session lifecycle advances. Session
statusdescribes the buyer flow;paymentStatusdescribes the money movement. - Your backend receives signed events. Use Collections Webhooks to reconcile the result and fulfill only after
purchase_succeeded.