Integrating with Stripe

This page assumes that you already have a Stripe account created and are able to create plans. To sign-up and create a Stripe account, visit the Stripe website.

How it works

A billing meter is created via the Moesif UI for a specific metric and filter criteria that you want to charge for.

• The filter criteria defines what the meter should include such as specific endpoints, certain customers, or other filter criteria.
• The metric is what is metered. It could be number of API calls, unique users, an aggregation on a header or body field, or any other metric trackable by Moesif.

Once the meter is created, Moesif will automatically meter the usage for each company and charge your customers via Stripe. Moesif billing meters support a variety of billing models including prepaid, postpaid, Pay As You Go (PAYG) and more. If you have different features or metrics you need to charge on, you can create multiple meters in Moesif, each linked to a different Product and Price in Stripe. The integration also syncs subscription and revenue data from Stripe to Moesif so you can understand how API usage translates to revenue.

Prerequisites

In order to integrate Stripe with Moesif, there are a few prerequisites which must be completed. These include:

1. Creating an account with Stripe
2. Creating a plan in Stripe

The plan must be set with price details set to be recurring and usage is metered must be set to true. It is also recommended that the charge for metered usage by field be set to sum of usage values during period and each price have a price description filled out.

Here is an example configuration for a pricing item in Stripe:

Configuring the Stripe integration

Moesif’s connection with Stripe involves 2-way communication. Moesif has created a simple way to get all the info you need and to configure certain variables for Stripe in a single screen.The Stripe setup details screen can be accessed a few ways, including:

Through Settings > Extensions

and then selecting install on the Stripe extension

Through the Billing Meters screen Edit Billing Providers dropdown

And through the Create New Billing Meter screen

Once you’ve opened the configuration screen through one of the routes above, you can get the info needed to add the Moesif Webhook to Stripe, inputs to plug the Stripe API into Moesif, and customize your Customer ID source in a single place.

Adding the Moesif Webhook to Stripe

In Stripe, a Webhook needs to be added so that Stripe can send subscription updates to Moesif. To do this you’ll need to make sure you are logged into your Stripe account. Once logged in, use the left-side menu to navigate to the Developer button in the top menu.

Once you’re on the Developers page click on Webhooks in the left-side menu. Then, Click on the Add an endpoint button near the bottom of the screen.

On the Listen to Stripe events screen that appears after clicking the Add an endpoint button, paste in the Webhook URL into the Endpoint URL field. Optionally, add a description for the endpoint.

These details can be found in Moesif by clicking the Edit Billing Provider dropdown on the Billing Meters screen or by going to Settings > Extensions > Stripe and clicking install.

The Endpoint URL value you add to Stripe should also contain your Moesif Application ID. The generated URL in the Moesif installation page will already contain the correct Application ID and have it appended to the URL.

You’ll also need to configure the endpoint to listen to all events. To do this, you’ll click on the Select events button.

Then select all events for the Customer and Invoice event types and then select Add events at the bottom of the page.

Lastly, click Add endpoint at the bottom of the screen (again, you’ll likely need to scroll to the bottom of the page). The Webhook should then be created and display on the Webhooks screen in Stripe.

Now, your added Webhook should then be created and display on the Webhooks screen in Stripe.

Configuring the Stripe extension in Moesif

In Moesif, you will need to plug in the Stripe API details so that Moesif can post usage details to Stripe to bill upon. These details can be entered into the Stripe API Version and Stripe API Key fields on the Stripe Setup Details screen.

Currently, Moesif only supports v3 of the Stripe API.

The Stripe Private API Key can be found in Stripe by navigating to the Developers screen and clicking on API Keys from the left-side menu.

Next, you can either use the Secret key or create a Restricted key if you need more fine-tuned control over access.

To reveal the Secret key, click the Reveal key button.

This will then display your key.

You may also be prompted to enter your password if the account has been inactive for a while

Note: this example is done using test keys. To get a production key, toggle View testing data to switch over to production-mode to view production keys.

Copy the value listed under Secret key or your Restricted key and paste it into the Stripe API Key field on the Stripe Setup Details screen.

Once completed, be sure to click Save.

Set the Id Mapping

Moesif always uses Stripe’s subscription id for mapping subscriptions and is not editable. However, using the Id Mapping Configuration enables you to specify the correct Stripe customer field that contains the Moesif Company Id. Moesif will use this to link your customers in Stripe with Companies in Moesif. By default this is customer.id, but you’ll likely need to modify this unless you use Stripe’s default customer ids to identify customers on your API. Typically, this is a metadata field added to the Stripe customer object like company_id or tenant_id.

An example of how to do this is via Stripe metadata fields. For instance, both the Customer and Subscription objects have a metadata object that enable you to save custom fields in Stripe. To add metadata to the Customer object you can do it programmatically through the Stripe APIs or through the Stripe UI, like so.

The same can be done for the Subscription object as well.

Now, you’d want to make sure that the data you enter into the metadata fields match whatever value you have in the Moesif company_id field. Based on the metadata above, we could map the value into Moesif by going to the Stripe configuration screen and changing the values in the Set Id Mapping fields to match.

It’s important to remember that the values you see under the Moesif CompanyId and UserId should be what you are mapping to in Stripe through this configuration. This is how usage is synced for the user/company.

Linking a plan in Stripe to a billing meter

When creating a new billing meter, in the Link To section you can specify Stripe as the Billing Provider and then select the Product and Price you’d like the usage to be linked to.

Permission needed For Stripe Restricted API key

If you decide to create a Restricted Stripe API key, the minimum permission scope you need when creating the Stripe API Key are below:

{
  "permissions": [
    {
      "permission": "customer_read",
      "purpose": "Need to read customer details to report usage."
    },
    {
      "permission": "customer_write",
      "purpose": "Need to create customer balance transactions to support prepaid credits."
    },
    {
      "permission": "invoice_read",
      "purpose": "Needed for usage reporting and credit consumption."
    },
    {
      "permission": "plan_read",
      "purpose": "Need to get plan and price details to report usage."
    },
    {
      "permission": "plan_write",
      "purpose": "Enable creating plan and price using Moesif Product Catalogue tool."
    },
    {
      "permission": "product_read",
      "purpose": "Enable creating plan and price using Moesif Product Catalogue tool."
    },
    {
      "permission": "product_write",
      "purpose": "Enable creating plan and price using Moesif Product Catalogue tool."
    },
    {
      "permission": "subscription_read",
      "purpose": "Need to get subscription details to report usage."
    },
    {
      "permission": "usage_record_read",
      "purpose": "Need to see previous usage reported."
    },
    {
      "permission": "usage_record_write",
      "purpose": "Enabled report usage."
    }
  ]
}

Subscribing to a Product and Price

See Provider Mapping to understand how Stripe concepts like Products map to Moesif.

If you want to sell your product through a subscription model, you must set up Stripe Subscriptions. You can create and manage Stripe subscriptions in different ways.

You may have already integrated Stripe with Moesif. When you create products and prices in Stripe, Moesif automatically creates the corresponding Plans and Prices. You can access them in Product Catalog any time. Whenever a customer confirms a Stripe Subscription, Moesif automatically tracks and captures the subscription data including the associated products and prices. For example, you may have built a subscription page for your product or services with Stripe Checkout. At the end of a successful checkout session, you have a customer who’ve subscribed to pay a recurring price to use your product. Moesif starts tracking the subscription usage according to the Billing Meter you’ve created.

Moesif automatically syncs all the subscription data without any manual supervision.

Create Subscriptions

You can create subscriptions in different ways:

• Create and edit a subscription manually in your Stripe Dashboard.
• Use the Stripe API to create or update subscriptions.

See Create a Subscription in Stripe API Reference for more information about the Stripe Subscriptions API.