- Loop hosted-payment links to embed or share a link to a Loop payment page to accept payments
- Checkout sessions component, a low-code, prebuilt payment form that can embedded into your website
Checkout sessions overview
Checkout sessions define the Stripe products, usingprice-ids, and if applicable the cus-id, inv-id, sub-id, ref-id, metadata, coupons, free trials parameters. This allows Loop to either create a new subscription in Stripe with the desired requirements or link a payment to an existing customer / subscription in Stripee.
Checkout Sessions come in two types: general-purpose (reusable templates) and one-time (session-specific) links.
General-Purpose
General-purpose links are reusable templates created with the template: true parameter. Characteristics:- Reusable: Can be shared and used multiple times
- Evergreen: Never expire
- Fixed parameters: All generated one-time links will have the same parameter values
- Template behavior: Best for scenarios where all customers should have identical parameters
One-Time
One-time links are session-specific and handle individual customer payments. Characteristics:- Single-use: Become inactive after successful payment
- 14-day expiration: Valid for 14 days from creation
- Unique parameters: Can include unique values for each customer (
cus-id,inv-id,sub-id,ref-id,metadata,coupons,free trials) - Customer-specific: Each link can have different parameter values
- Automatically generated when a general-purpose link is clicked
- Created directly via API for specific customers
When to Use Each Type
| Use Case | Link Type | Reason |
|---|---|---|
| Public product page with fixed discount | General-purpose | Same discount for all customers |
| Email marketing with universal coupon | General-purpose | One coupon code works for all recipients |
| Customer-specific invoice | One-time | Requires unique inv-id for each customer |
| Existing customer checkout | One-time | Requires unique cus-id for each customer |
| Existing subscription | One-time | Requires unique sub-id for each customer |
| Personalized referral links | One-time | Requires unique ref-id for each customer |
Important Rule
If you need unique parameter values for different customers (e.g., differentref-id, cus-id, inv-id, or custom metadata for each customer), you must create individual one-time links for each customer. General-purpose templates can only create one-time links with identical parameter values.
Checkout Sessions endpoint
Payment links can be made by calling the Checkout Sessions endpoint. Required parameters Links must either containelements, externalSubscriptionId or an externalInvoiceId. These inputs are mutually exclusive. This is the only required field.
As noted above, payment links can either be general-purpose links that are reusable and not tied to a specific customer, subscription or invoice or one-time links that once consumed they become inactive. General purpose links are created using the parameter template: true.
Each time a customer clicks on a general purpose link, a new one-time payment link is created with a unique id. This link represents a specific customer’s payment session and once a payment confirms with that link, it will become inactive.
One-time payment links are valid only for 14 days. Conversely, general-purpose payment links are ever-green and can continue to generate new one-time payment links when clicked on by a customer.
Additional parameters
Loop provides several additional parameters:| Parameter | Description |
|---|---|
billDate | To take a payment for a new subscription that you want to start on a specific date (e.g. Jan 1); use in conjunction with the elements. |
freeTrialDays | Only for subscriptions. If provided, the Stripe subscription will be created with this trial period. |
couponCode | We use the user facing code, called the promotion codes, as the input (e.g. SUMMERSALE) If provided, the discount will automatically be applied to the payment link. We only support certain coupon parameters defined here |
email | If provided, the customer will not be able to change this email. If a Stripe customer does not exist, it will be created with this email. |
referenceId | This will be included in all webhooks |
cartEnabled | Enable or disable cart on the checkout page |
Metadata | Info that will be included on the Agreement Created webhook (Loop webhook) that is sent when someone uses the payment link to attach a payment method |
minimumAllowanceAmount | By default loop requires payers to have enough to make the first payment made via loop. You can require an amount higher than the 1st payment using this parameter. |
minimumBalanceAmount | By default loop requires the customer to have enough to cover the first payment made via loop, you can require a higher amount using this parameter. |
successUrl | If you would like to provide a dynamic redirect link specific to individual customers at the end of the checkout session, use this parameter. By passing this URL it sets the redirect link for that session and will override any redirect URL set at the entity or merchant level. |