Subscriptions
Below are directions on how to use Chargebee as your subscription management platform and thus leverage the subscription management capabilities of Chargebee while accepting crypto payments.
Overview
Steps
1. Get setup up using the automated setup
Get setup in minutes by simply providing Loop with your Chargebee site URL, API Key, and configuring your webhooks. Don't want to do this? Reach out to Loop for directions on our manual setup.
2. Add a plan in Chargebee (if necessary)
A Chargebee plan is equal to a Loop subscription item.
When a new Chargebee integration is configured, any plans you already have created in Chargebee are automatically imported into Loop. You can find these plans and their related payment link on the Subscriptions page within Loop's Company Dashboard.
Chargebee requires each subscription for a customer to have a plan. You can charge for "addons" or "charges" only in conjunction with charging for plans, not by themselves.
Adding a new plan
If you do need to add a new plan, you would add it In Chargebee. Navigate to your Product Catalog in Chargebee then to Plans. You can then create a new plan and assign a price. Currently Loop only works with the Flat Fee pricing modal.
Enter the name of the plan. This plan name will show up as a subscription name in Loop.
Once the plan is created, you can then set your desired pricing in Chargebee. Each price / frequency combination in Chargebee will be pulled into Loop as a unique subscription with its own checkout link.
When you do this, you will see that Chargebee sends a webhook. After the webhook is successfully sent, you can navigate back to Loop’s Subscriptions page and refresh the page. You should now see this newly created subscription in Loop with its accompanying checkout link.
Editing existing plans
You can use the “edit" button on the Subscriptions page of the Loop Company Dashboard to edit the accepted tokens, name, amount, frequency, and price description. These fields are shown to end customers in the cart during checkout.
When using the Chargebee integration, we recommend only updating the accepted tokens list in the Loop dashboard, not other details such as the amount of the subscription. We do not currently push plan information to Chargebee, so changes made on the Loop Subscriptions page will not occur in Chargebee. However, if you make changes in Chargebee, we will pull that information into Loop and update the items in our system.
3. Edit which tokens and networks you want to accept
By default any product brought in from Chargebee will have all the tokens saved in your contract enabled. If you would like to limit the tokens, you will need to edit the subscription item's accepted tokens list. Here are directions.
4. Provide a method for collecting authorization
Companies have two ways to collect authorization for subscriptions, via the hosted checkout page or the checkout modal.
Hosted checkout page
Loop provides a custom hosted checkout page for each item. This URL can be sent directly to the end customer via email, telegram, or it can be added to the Chargebee invoice_notes field, or it can be embedded directly on your site in a "pay with crypto" button.
Checkout widget
For those that prefer, Loop provides a checkout modal that can be integrated in the context of your company's website or application, to enable your customers to pay with crypto. The modal allows end users to give Loop authorization to enable autopay without ever leaving your app.
Existing customers in Chargebee
If you are collecting authorization from an existing customer that is already subscribed to a Chargebee plan and wants to pay in crypto, you can append the subscriptionID to the end of the hosted checkout page. You can find details on appending the ID to the hosted checkout page here and to the modal in the NPM readme here.
5. Provide access to your end-product
Since Loop marks invoices in Chargebee as paid, you can continue to use any integrations you've built off of Chargebee as the method for providing access. No need to change anything.
However, if you want, Loop uses webhooks to notify you of events. The AgreementSignedUp event lets you know that a wallet provided authorization to be billed - it does not mean you have been paid yet, but it does indicate the user has set an allowance for payments. The TransferProcessed event is the payment notification and indicates funds have been sent to the receiving wallet.
You can optionally pass an external reference ID during checkout to map the Loop agreement webhooks to a user ID in your system (details can be found here). You can alternatively use the wallet address or email provided in either of these events to map to users in your system to provide access to your system.
Even with immediate invoicing, there will be a delay between the webhook events, as the transaction must be confirmed on-chain. Companies can decide to grant access based on the AgreementSignedUp event and take action if you do not hear about the TransferProcessed event within a certain amount of time, (e.g. show a warning, etc). We built Loop to be flexible, so companies can decide how "aggressive" they want to be about payment confirmation.
There are a few reasons why the TransferProcessed event would not occur:
The wallet does not have enough balance to cover the payment
The wallet does not have enough token allowance to cover the payment
The transaction is stuck in the mempool
Loop's relay network is down
Wallet amount and balance information can be found on our company dashboard for all active subscribers if you are troubleshooting a late payment.
6. Provide method for cancelation
If an end user cancels their subscription in your app, we recommend canceling the subscription in Chargebee. This will stop Chargebee from creating a new invoice, and thus Loop will have no invoice to pull in, so no additional payments will be processed. Please note, if you have an outstanding invoice in Loop, you will need to go into Loop and on the Transaction page click the “cancel” button for that transaction, so the user isn’t charged, or cancel via API using the PATCH Transfer call.
You can alternatively cancel a customer on the Accounts page in Loop; this will automatically cancel any future invoices. If an invoice is already due, then you will need to manually cancel that transaction on the Transactions page. Please note, this transaction might have been picked up by the network and is currently being processed, so to avoid any issues, we recommend attempting to cancel before an invoice is due, or cancel via API using the PATCH Transfer call.
We are building an feature that allows for cancelations in Chargebee to automatically be reflected in Loop and vis-versa. This will apply to both cancelling the subscription as well as cancelling an invoice that has already been brought into Loop (coming soon).
Last updated
