Additional functionality
Last updated
Last updated
Loop allows you to configure additional functionality (outlined below) by appending it to the end of the Loop checkout page URL. These fields are case sensitive.
Below is a table of the syntax for configuring additional functionality on the checkout. Additional descriptions, including limitations, can be found in the following sub-pages.
If you are appending multiple functionalities together, the first functionality requires the "?" and the other functionalities are appended with an "&" in place of the "?". For example:
| Functionality | Appended after item_id |
|---|---|
Many of these parameters can be used together and impact their functionality. Thus, we've outlined several examples and scenarios here.
There are some cases, particularly when using features in Stripe that to avoid confusion it makes sense to hide the cart. You can do this by appending cartEnabled=false to the end.
If you want your customer's email to be pre-filled when they open the hosted checkout page, you can pass the customer's email in the checkout URL.
Please note:
You should pass in the encoded form of the email into the URL for it to properly handle special characters. For example, I should not pass "andrew+test@loopcrypto.xyz" in the URL; instead, I should pass "andrew%2Btest@loopcrypto.xyz" in the URL for the email to display correctly on the checkout page as "andrew+test@loopcrypto.xyz".
If you are using an integration (Stripe, Chargebee) we will use this email as a record locator in that system and associate the checkout in the case of a match.
When the email is set in the URL in this way, the end user still needs to sign a transaction as a part of the checkout flow. The user clicks the blue button under the email address, which will prompt a signature request and then associate the email address with the wallet sending the funds.
Companies can pass a reference ID in the checkout URL to map to users in their external systems.
Please note:
You should pass in the encoded form of the reference ID into the URL for it to properly handle special characters. The reference ID that you pass will be returned in the webhooks related to that Agreement, and also in API responses for that Agreement. You can then use this reference ID to handle user permissioning in your external system according to your requirements.
If you are using Loop's Stripe integration, you can pass a unique reference ID via the checkout, and that reference ID will be populated in the Metadata section of a Stripe invoice. See an example below of the Metadata section in Stripe.
By default, Loop will check a customer's token balance before allowing them to finish checkout to ensure they have enough to make at least the first payment. To calculate this minimum balance required, we use the following logic:
Calculate the total value of the cart (i.e. adding the prices of all the items in the cart, regardless of when the payment is due)
This does not take into consideration any taxes, coupons, discounts except in the case of an invoice where Loop will use the final invoice amount which may be inclusive of any taxes, coupons, or discounts.
For “Price Varies” items, the item amount is read as $0. This means that if there is only a Price Varies item in the checkout cart then the minimum balance required will be $0 unless the minimumBalanceReqiured parameter is used and overrides this logic.
Companies may want to override this default required amount, especially in scenarios where the cart is hidden (cartEnabled=false) or an item is "Price Varies." Scenarios where the the amount of the cart will vary based on factors such as metered usage, subscription quantities, or the use of coupons or discount codes are perfect examples of where you would want to use this parameter.
When using the parameter, make sure to pass in a USD value in "1000s" (i.e. 5000 = $50) to the URL.
Loop will convert the USD amount to the required token amount using an oracle and use this amount to hold a customer on the first step if not met.
When the cart is hidden (i.e., cartEnabled=false), the minimum balance is set by whichever amount is GREATEST, between (1) the checkout amount, or (2) the minimumBalanceReqiured parameter (if set).
How is the checkout amount calculated?
If this is an invoice checkout, use the invoice total amount
If not an invoice, use the sum of all item amounts, without discounts
By default, Loop will suggest 12x the amount of the subscription for monthly subscriptions and 1x the amount of the one-time payment for one-time payments.
However, companies may want to override this default suggested amount if the amount of the subscription will vary based on factors such as metered usage, subscription quantities, or the use of coupons or discount codes.
Please note:
The amount is specified in USD cents, i.e. a value of 100 equates to $1.00 USD. When this parameter is set, the checkout will display the amount specified. An example is shown below:
The checkout page enables the purchase of multiple subscriptions and one-time items (frequency = 0).
To use this, simply pass to the URL the ItemIDs to be purchased, separating the itemIDs with a comma.
This is the same as converting a customer from fiat to crypto.
We do not validate IDs. Thus, a customer will be able to successfully checkout but no record will be created in the third party system. Thus, we strongly suggest you test the ID is working properly.
We return validExternalSubscription":true or validExternalSubscription":false which indicates whether we were able to look up the subscription ID or not.
You can inspect the page and check the network tab to see the results with a valid check.
If you have a customer that is already subscribed to a Stripe plan and wants to pay in crypto, you can send the user the payment link but include the ID in the URL.
In Stripe the subscription ID can be found by navigating to Customers -> select the customer -> select the subscription -> subscription details.
For example: sub_1N4pReEsKlmFX3FHH40hJAC5
In Chargebee the subscription ID is the id of the existing subscription in CB.
For example: https://loopcrypto-test.chargebee.com/d/subscriptions/Azz5l4TaUIDUvqqb where Azz5l4TaUIDUvqqb is the subscription id
In Stripe, the following 3 settings are in place as shown in the image below.
Payment: “Email invoice to the customer to pay manually”
Payment due: “0 days”
Invoice payment page: leave unchecked
And then click Update Subscription at the bottom-right of the page.
You will see an invoice created for the product immediately in Stripe with the bill date being the current day. The current period will be set to today for one year.
In Chargebee, when you create a subscription for a customer, you should ensure that "Auto-collection" is set to "No."
You can only combine items that have the same tokens configured and from the same source (i.e. Loop, Stripe or Chargebee) or else the transaction will fail. For Stripe items, you can only combine subscriptions that have the same repayment refrequency (this is a Stripe limitation). For example, if one item only accepts "USDC" and "WETH", it can only be combined with other items that accept only "USDC" and "WETH".
Before you send the link, you must ensure that on the customer's subscription page, the payment is set to manual.
?cartEnabled=false
?email=<customer email address>
?refId=<external reference ID>
?minimumBalanceRequired
?defaultSpendingCap=<default spending cap>
?item_id=<item_id>,<item_id>,...
?sub=<stripeSubscriptionId>
