> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/billing/payment-links.md).

# Payment links

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/payment-links.md).
{% endhint %}

A **payment link** opens the Snapfix **payment page** (the web\_payments app, at package.snapfix.com) for one price or one **package** that staff have set up. Staff copy the link in the admin app and send it to the customer. On the page the buyer signs in (or, on some links, goes on as a guest), picks the **site** to pay for, chooses the package's optional items, adds invoice details and pays by card or SEPA Direct Debit through Stripe. The payment starts a Stripe subscription, or creates an invoice for one-off items. Only the web has this page.

## Rules

### Making the links

* A link has one of two types. `/single/:id` sells one price, where `:id` is the price's ID; `/multi/:id` sells a package with optional items, where `:id` is the package's ID ([Snapfix payment](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md)).
* The admin app's [Paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md) copies a `/single/` link for each price. The [Stripe payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/stripe-payment.md) page creates a package with its Stripe prices and copies its `/multi/` link ([`admin_create_stripe_product_v3`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_stripe_product_v3)).
* A HubSpot deal offers two links ([HubSpot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md)). "Generate Snapfix Payment URL" creates a package for the deal's line items, with the company's Stripe customer and the site, and copies its payment page link. "Generate Stripe Checkout URL" creates a Stripe checkout session through a service outside these repos \[[ASK-6](https://github.com/snapfix/docs/blob/main/ASK.md#ask-6-confirm-these-repos-are-retired)] and logs the link against the deal ([`POST /v1/admin/sales/company-stripe-checkout`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalescompany-stripe-checkout)); that link opens Stripe's own page, not the payment page.
* No code sends a link to a customer: staff copy it and send it themselves.
* The production build takes live Stripe payments; every other build uses Stripe's test mode (web\_payments @ 7c2c3ddffd, `src/environments/environment.prod.ts:7`, `src/environments/environment.ts:11`).

### Who can pay

* Anyone with the link can open the page. A `single` link needs a sign-in first. A `multi` link needs one too, unless the package has its own Stripe customer: then "Continue to Payment Screen" lets a guest go on without signing in ([Snapfix payment: steps](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md#steps)).
* No `single` link can be paid today: the page sends the package ID as the text "undefined", and the server refuses it with "invalid package".
* A buyer without a Snapfix account gets a sign-up form that cannot finish: both sign-up routes return before they do any work, so no code is sent. Such a buyer can pay only as a guest, on a package with its own Stripe customer. A refused email check opens the same form.
* A signed-in buyer picks one of the sites where they have an admin row; when the server returns one live row, the page picks it and skips the step. The list keeps blocked rows and deleted sites ([`webcust_parent_list`](https://docs.snapfix.com/engineering-reference/api/console.md#post-actionwebcust_parent_list)).
* The signed-in payment checks only that the buyer has a row on the site, of any role, deleted rows included ([`create_stripe_subscription_v3`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actioncreate_stripe_subscription_v3)).
* The guest payment runs on the shared login built into the page and checks no user and no site; the server does not tie the Stripe customer it is sent to the package ([`/create-stripe-subscription-v3`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-create-stripe-subscription-v3)).
* A signed-in buyer of a package with its own Stripe customer is charged on the chosen site's customer when the site has one, while a guest is charged on the package's \[[ASK-225](https://github.com/snapfix/docs/blob/main/ASK.md#ask-225-which-stripe-customer-should-a-signed-in-buyer-of-a-package-with-its-own-customer-be-charged-on)].

### Items

* Mandatory items are always in the order, at their default quantity; the buyer ticks the optional ones. A quantity changes only on an editable item, between its minimum and maximum ([Snapfix payment: inputs](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md#package-items)).

### Invoice details

* The country is required; the address, the VAT number and the PO are optional. The site's address fills the fields, and the signed-in payment saves the invoice and billing addresses on the site ([`create_stripe_subscription_v3`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actioncreate_stripe_subscription_v3)).
* The VAT field shows for countries with a VAT type. An empty number passes, though the field's help says a valid number is needed; a typed number must pass the country's check, and an invalid one keeps "Continue" disabled ([Snapfix payment: invoice details](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md#invoice-details)). Valid Canadian and UAE numbers fail that check. The server sends any number to Stripe as an EU VAT ID.
* For an Irish invoice address the page adds a fixed "23% VAT" to the total. The server lets Stripe's automatic tax decide, so the amount charged can differ \[[ASK-147](https://github.com/snapfix/docs/blob/main/ASK.md#ask-147-should-the-payment-page-show-the-tax-that-stripe-charges)].

### Start date and payment

* On a `multi` link that the page treats as a subscription, the buyer picks a start date, today by default, within the package's permitted days before and after today. A date outside that range silently becomes tomorrow. A package with a fixed start date fixes the date.
* One-off items have no start date, and the pay button reads "Pay" instead of "Start your subscription". A `single` link, and a `multi` link where the buyer signs in on the page, always read as a subscription, even for one-off prices.
* The buyer pays by card, or by SEPA Direct Debit where the package offers it. The pay button works only when the card or IBAN fields are complete and the terms are accepted.
* The page creates the Stripe payment method with the signed-in buyer's name, sign-in email and mobile number; a guest sends only the invoice address.
* When neither the site's details nor the package hold a Stripe customer, the page asks the server for the site's customer, which creates one when the site has none. Any signed-in user can get or create that customer for any site ([`prod_get_stripe_customer_id`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionprod_get_stripe_customer_id)).
* The server creates the subscription, or an invoice for one-off items, and the page confirms the first payment with Stripe ([Subscription result object](https://docs.snapfix.com/engineering-reference/api/billing.md#subscription-result-object)).
* The success page says "Your subscription is now active and applied to your Snapfix account.", but no route in the repos records a live subscription or package for the site afterwards \[[ASK-142](https://github.com/snapfix/docs/blob/main/ASK.md#ask-142-who-records-live-stripe-subscriptions)]. What a payment does to the plan is in [Subscriptions](https://docs.snapfix.com/product/features/billing/subscriptions.md). A successful payment clears the sign-in the page stored.

### Sign-in

* The page signs in through authpy: "Continue" checks the email, and "Login" signs in. It sends its authpy calls with the shared login built into its code.

## Flow

```mermaid
flowchart TD
  open["Buyer opens the link"] --> kind{"Single price or package?"}
  kind -- "single" --> signin["Sign in"]
  kind -- "multi" --> read{"Package found and within its dates?"}
  read -- "no" --> missing["Package not found"]
  read -- "yes" --> customer{"Package has its own Stripe customer?"}
  customer -- "yes, guest" --> items["Choose items"]
  customer -- "no" --> signin
  signin -- "multi" --> items
  signin -- "single" --> price["Read the price"]
  price --> site["Choose a site the buyer administers"]
  items -- "signed in" --> site
  items -- "guest" --> invoice["Invoice details"]
  site --> invoice
  invoice --> pay["Card or SEPA, start date, terms, pay"]
  pay --> stripe["Server creates the subscription or invoice; Stripe confirms"]
  stripe --> done["Success page"]
```

## Platforms

| Capability                                | Web                                                             | iOS | Android |
| ----------------------------------------- | --------------------------------------------------------------- | --- | ------- |
| Make a package or price and copy its link | Staff admin app only                                            | No  | No      |
| Pay through a payment link                | Yes, on package.snapfix.com                                     | No  | No      |
| Pay as a guest                            | Only on `multi` links whose package has its own Stripe customer | No  | No      |
| Create an account on the payment page     | No; the step cannot finish                                      | No  | No      |
| Pay by card or SEPA Direct Debit          | Yes, as the package allows                                      | No  | No      |

## Screens

* [Snapfix payment](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md): the payment page, step by step.
* [Paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md): the admin app's prices and their single-price links.
* [Stripe payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/stripe-payment.md): the admin app's Stripe packages and their package links.
* [HubSpot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md): payment and checkout links made from a deal.

## API and data

* [Billing API](https://docs.snapfix.com/engineering-reference/api/billing.md):
  * [`POST /read-package-v3`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-read-package-v3): a package and its prices, for a `multi` link (through authpy).
  * [`POST ?action=snapfix_package`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionsnapfix_package): one price, for a `single` link.
  * [`POST ?action=prod_get_stripe_customer_id`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionprod_get_stripe_customer_id) and [`POST ?action=sandbox_get_stripe_customer_id`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionsandbox_get_stripe_customer_id): the site's Stripe customer, by build.
  * [`POST ?action=create_stripe_subscription_v3`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actioncreate_stripe_subscription_v3): the payment for a package without its own Stripe customer.
  * [`POST /create-stripe-subscription-v3`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-create-stripe-subscription-v3): the payment for a package with its own Stripe customer (through authpy).
* [Console API](https://docs.snapfix.com/engineering-reference/api/console.md): [`webcust_parent_list`](https://docs.snapfix.com/engineering-reference/api/console.md#post-actionwebcust_parent_list) (the sites a buyer can pay for) and [`webcust_parent_detail`](https://docs.snapfix.com/engineering-reference/api/console.md#post-actionwebcust_parent_detail) (the site's address and billing details, which members who are not admins can read \[[ASK-124](https://github.com/snapfix/docs/blob/main/ASK.md#ask-124-should-members-who-are-not-admins-see-the-sites-billing-details)]).
* [Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md): [`admin_create_stripe_product_v3`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_stripe_product_v3) (a package and its link) and [`POST /v1/admin/sales/company-stripe-checkout`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalescompany-stripe-checkout) (a deal's checkout link).
* Tables: [`package_server`](https://docs.snapfix.com/engineering-reference/db/tables/package_server.md) and [`package_server_pricing`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_pricing.md) (packages and their prices), [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) (the site's Stripe customer and VAT ID), [`tPri_Address`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_address.md) and [`tPri_ParentAddress`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parentaddress.md) (the addresses a payment saves), [`tPri_Org_StripeCheckoutUrlLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_stripecheckouturllog.md) (deal checkout links).

## Depends on

* [Subscriptions](https://docs.snapfix.com/product/features/billing/subscriptions.md): what a payment does to the site's plan and billing portal.
* [Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md): the staff tools that make packages, prices and deals.
* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): the account the buyer signs in with.
* [Site details](https://docs.snapfix.com/product/features/console/site-details.md): the site's address, Stripe customer and VAT details.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the admin role that decides which sites a buyer can pick.
* Stripe (external): payment methods, subscriptions, invoices and tax.

## Edge cases

* **Package not found:** a `multi` link to a package that is missing, deleted, not started yet or already ended shows "Package not found" ([Snapfix payment: states](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md#states)). A `single` link checks neither the package's dates nor whether its price or package is deleted, which matters once single links can be paid.
* **No admin site:** a signed-in user who administers no site sees a notice and nothing to pay for.
* **Customer lookup fails:** the payment step stays a skeleton and nothing retries.
* **VAT refused by Stripe:** the notice explains the format and links to Stripe's tax ID guide.
* **Payment refused:** the message shows as a notice and the form stays, so the buyer can try again.
* **Customer IDs:** the site read gives any signed-in user a site's Stripe customer ID, which the guest payment accepts.
* **Offline:** not applicable; the page is web only and does not check the connection.
* **Time zones:** none. The start date limits are counted in days from today.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/billing/payment-links.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
