Overview

It's possible to use Stripe Elements directly to create custom payment experiences and flows while delegating the subscription lifecycle management to Stigg.

To do that, instead of using Stigg's native Stripe Checkout integration via the server SDK, this approach will require calling Stigg to create a subscription after the customer's payment details have been stored in Stripe and attached to the customer in Stripe.

Before we begin

In order to complete this guide in your application code, please make sure that you have:

• Access to Stripe account
• An active Stripe integration
• Modeled your pricing in Stigg
• Know how to provision customers in Stigg
• Know how to create subscriptions in Stigg

How it works

It's typical to build the checkout form using Stripe.js elements and leverage the Setup Intents API to confirm the payment method and save it for future use.
If you need help in setting this up, you can refer to this article to learn how setup intents work.
In case you have a different setup in place, let us know and we'll assist you with the integration to suit your needs.

Once your checkout form is built, the journey of the customer should look similar to this one:

Provisioning a customer

On a new user sign up, create a customer in Stigg to represent an individual or an organization:

await stiggClient.provisionCustomer({ 
  customerId: 'CUSTOMER-ID', 
  subscriptionParams: null, 
  shouldSyncFree: true,
  ... 
});

This will also create a customer record in Stripe, and link the Stigg customer to the Stripe one.

Rendering the paywall

To render a paywall within your app, you can use Stigg's embeddable widget or render your own pricing plans component based on the data fetched from Stigg:

const plans = await stiggClient.getPaywall();

The response contains an array of published Plan objects that should be rendered in the paywall.

Adding a payment method to the customer in Stripe

When a user selects a plan, present the custom checkout form to add the new payment method. According to official Stripe documentation, you should create the SetupIntent for the customer on your backend, and then propagate the returned intent client_secret to the frontend.
Then it can be used to initialize the stripe.elements form in a secured manner.

🚧

The provided payment method will be set as default and will be used to pay for all future subscriptions.

In order to create the Setup Intent in Stripe, you can get Stripe's customer ID by getting the customer from Stigg. The getCustomer function returns the Customer object that has the customer.billingId property which holds the ID of the customer in Stripe:

const customer = await stiggClient.getCustomer('CUSTOMER-ID');
console.log(customer.billingId);
// OUTPUT: cus_MGJZNu894GQKI6

The checkout form should handle the validation of the card prior creating subscription in Stigg, and once its valid and attached to a customer, Stigg will be notified by a payment_method.attached event from Stripe and it will be available for future use by Stigg.

Provisioning a subscription

After adding the payment method, provision a subscription in Stigg:

const subscription = await stiggClient.provisionSubscription({
    customerId: 'CUSTOMER-ID',
    planId: 'PLAN-ID',
    ...
})

At this point, Stigg will attempt to create a subscription in Stripe and use the default payment method to be charged for the generated invoice in the case of a paid plan.

If the payment was not successful, the subscription status will remain as PAYMENT_PENDING
and no entitlement access will be provisioned.

You can notify customers about failed payments by listening to Stigg's customer.payment_failed webhook. The customer should be instructed to replace the payment method with a different one and to try again.

Once the payment is successful, the subscription will become active in Stigg and the customer will be granted access to the associated entitlements. Stigg will send an entitlements.updated event to configured webhooks and will update the server SDKs in real-time by pushing the updates over a web-socket connection.

On the front-end, you should call the refresh function to re-fetch the current customer data and the new entitlements.

await stiggClient.refresh();

🚧

Stripe creates a time frame (default of 24 hours) for the outstanding invoice to be settled. If the invoice is not settled within that time frame, the subscription is canceled both in Stripe and Stigg.