Checkout Concepts

Checkout has two entry models: a reusable PaymentLink template and a concrete, expiring CheckoutSession. Payment Links create or resume a session only when the buyer starts the interactive flow. API integrations create a session directly and may use catalog priceId values or inline priceData. Both entries render the same hosted checkout and share invoice, subscription, payment, gateway, retry, and result behavior.

status describes the buyer lifecycle (OPEN, COMPLETE, EXPIRED), while paymentStatus independently describes money movement. Treat the signed purchase_succeeded event—not a redirect—as the fulfillment signal.

It is written for product, operations, support, and business teams. It focuses on the customer journey, what checkout is intended to do, and the business outcomes it can produce.

Purpose

Checkout is the customer-facing flow where a buyer confirms what they want to purchase and completes payment.

Pharos checkout can support:

• one-time purchases
• subscription purchases
• mixed carts with one-time and subscription items
• free or discounted orders
• trial-based subscriptions

Functionally, checkout is where the system turns customer intent into an order, invoice, payment, and possibly a subscription.

What Checkout Does

At a high level, checkout is responsible for:

1. showing the customer what they are buying
2. collecting customer and billing information
3. collecting or initiating payment
4. creating the business records needed to complete the sale

The exact experience can vary depending on:

• country
• currency
• enabled payment gateways
• payment method
• whether the cart contains subscriptions
• whether a trial or discount applies

Main Checkout Outcomes

Checkout can end in a few different business outcomes.

Successful checkout

This happens when the required payment is completed or when no immediate payment is needed.

Examples:

• a card payment succeeds
• a free order requires no payment
• a subscription starts in trial and does not need to be charged immediately

Functionally, this means the purchase is accepted and the related records are created.

Pending checkout outcome

Sometimes the customer completes the checkout form, but the payment still requires confirmation or later completion.

Examples:

• a redirect-based method
• a bank transfer flow
• a ticket or cash-payment flow

Functionally, this means the checkout flow was submitted successfully, but the business should wait for the final payment result before treating the transaction as fully collected.

Failed checkout outcome

This happens when the payment cannot be completed.

Examples:

• card declined
• invalid payment method details
• provider rejection
• timeout or processor error

Functionally, this means the customer must retry or use another method.

Checkout and Product Types

Checkout can handle different kinds of commercial offers.

One-time products

These are paid once.

Checkout creates the sale and attempts to collect the amount immediately unless the amount is zero.

Subscription products

These create an ongoing billing relationship.

Depending on the configuration, checkout can:

• charge the first invoice immediately
• start the subscription in trial
• create a subscription that will be paid later through invoice collection

Mixed carts

Checkout can also support mixed behavior, for example:

• a one-time setup fee plus a subscription
• multiple subscription items in the same purchase
• trialed subscription items plus immediately chargeable items

Functionally, checkout is responsible for splitting what is due now from what will be billed later.

Customer Information Collected During Checkout

Depending on the setup, checkout can collect:

• first name
• last name
• email
• billing address details
• country
• postal code
• custom fields defined by the business

This information helps Pharos:

• identify the customer
• create the invoice
• route the payment correctly
• personalize follow-up communication

Payment Method Selection

Checkout can offer different payment methods depending on business configuration.

Functionally, the available methods may vary based on:

• the selected country
• the selected currency
• the configured payment gateways
• the payment method families enabled for that checkout

The customer sees the methods that are relevant to their route and context.

Country Selection and Currency Availability

Checkout uses country selection as part of payment routing.

Functionally, this means the selected country does more than change address context. It also helps determine:

• which currency is active
• which gateways are eligible
• which payment methods can be shown

How currency availability works

Checkout only offers currencies that are valid for the full cart.

In practice, this means a currency is selectable only when:

• every product in the checkout supports that currency
• the business has a valid payment route for that country and currency combination

If one product supports USD but another does not, USD will not be offered for that checkout.

Why checkout may default to a local currency

When checkout can infer the buyer's country and currency, it tries to start with the route that best matches that buyer.

For example:

• a buyer in Argentina may see ARS selected first
• a buyer in Brazil may see BRL selected first

This default does not necessarily mean other currencies are unavailable. It only means checkout picked the most natural starting route for that customer.

How customers switch currency

Checkout does not treat currency as a completely separate selector.

Instead, the customer changes route through the country selection control in the footer. If the same country has more than one valid currency route, the customer can choose between those available currency options there.

Example:

• Argentina (ARS)
• Argentina (USD)

So if a payment link supports both ARS and USD, checkout may still open in ARS first while allowing USD through the country selector.

Support guidance

If a customer says "the link only allows one currency," support should verify two things:

1. every product in the checkout supports the requested currency
2. the business has an enabled routing rule or valid gateway path for that country and currency

If both are true, the customer should be able to reach that option from the country selector even if checkout initially loads in a different currency.

Pricing, Discounts, and Totals

Checkout is also responsible for showing the correct financial summary.

This includes:

• item prices
• quantities
• discounts
• coupon impact
• total due now
• future recurring amount for subscriptions

If the cart contains trials, checkout distinguishes between:

• what is charged today
• what will be charged later after the trial ends

Checkout and Invoices

Checkout creates the financial basis for the purchase.

Functionally:

• an invoice represents the amount owed
• a payment represents the attempt to collect that amount
• checkout may create subscription records when recurring items are present

This means checkout is not only a UI flow. It is also the business handoff into billing and subscription management.

Checkout may create an invoice that is collected immediately, later, or through a follow-up billing flow.

For the full invoice lifecycle and status definitions, see Invoices. For payment attempt outcomes, see Payments.

Checkout and Subscription Creation

When the cart contains subscription products, checkout may create a subscription immediately.

The initial subscription status depends on the commercial situation:

• if there is a trial, the subscription starts as trialing
• if automatic collection is required and the first payment fails, it starts as incomplete
• if payment is successfully established, it can move into active
• if invoice collection is used, it can start as active and then rely on invoice due dates

Functionally, checkout is the entry point into the subscription lifecycle.

What the Customer Can Experience

From the customer’s point of view, checkout may look like:

• an immediate pay-and-confirm flow
• a pay-later or invoice-based flow
• a trial start with no charge today
• a pending flow with extra payment instructions

Support and operations should expect these different experiences and not assume that every checkout ends with an immediate final payment result.

What Support and Operations Should Expect

Checkout success does not always mean "money collected immediately."

Teams should distinguish between:

• checkout submitted successfully
• payment completed successfully
• subscription created successfully
• invoice still awaiting collection

This is especially important for:

• asynchronous payment methods
• trial subscriptions
• invoice-based subscription collection
• discounted or free orders

Functional Summary

Checkout is the commercial entry point where Pharos:

• presents what the customer is buying
• captures the customer and billing details
• starts the payment flow
• creates the invoice
• creates subscriptions when needed
• determines whether the purchase is completed now or needs follow-up

From a business perspective, checkout is where a customer moves from browsing to a real financial relationship with the business.