Configuring A Billing Provider

A Billing Provider is needed to facilitate the checkout process and invoice customers for usage. When APIs are used, Moesif will aggregate the API usage and send the usage to the billing provider to be invoiced. Currently, the Moesif Developer Portal supports Stripe as a Billing Provider.

Setting up Billing Provider

Stripe

In order to use Stripe as a billing provider for the Moesif Developer Portal, you’ll need to set up products and prices within Stripe. You’ll then need to use the Stripe-Moesif integration to connect the two platforms.

Creating a Product in Stripe

To create a product and price, log into Stripe and proceed to the Products page from the header menu in the Stripe UI. Once on the Products page, click on the Add Product button in the top right corner.

In the Add a Product modal that appears, you’ll be able to add the details for your product and the price(s) for it. The form for your product will have a few fields to fill out. Some of these fields include:

  • Name
    • This is the name of your product. In the example below, we use the name “My API”.
  • Description
    • This field is optional but you could put a brief description of the product here. In the example below, we use a description of “This is a monetized API”.
  • Pricing model

    • A few different pricing models can be set up in Stripe. These pricing models include:

      • Standard pricing
        • use this if you want to charge the same price for each API call.
      • Package
        • use this if you charge for API usage by the package or a group of units. For example, you could set it up to charge $10 for every 1000 API calls. Every time the user goes over the 1000 API call threshold, they are charged another $10.
      • Graduated
        • use graduated pricing tiers that may result in a different price for some units in an order. For example, you might charge $10.00 per unit for the first 100 units and then $5.00 per unit for the next 50. Today, this is only available for recurring prices.
      • Volume
        • use if you charge the same price for each unit based on the total number of units sold. For example, you might charge $10.00 per unit for 50 units, and $7.00 per unit for 100 units.
  • Price
    • Depending on the pricing model selected, prices can be set in this field.
  • Billing period

    • The billing period can be set as:

      • Daily
      • Weekly
      • Monthly
      • Every 3 months
      • Every 6 months
      • Yearly
      • Customer

    • For your configuration with Moesif, we recommend setting the billing period as Monthly. You’ll also need to check the Usage is metered box as well.

  • Charge for metered usage by

    • Once the Usage is metered checkbox is selected, the option for charge for metered usage by will appear. This field lets you choose how metered usage will be calculated and charged for. Values available for this field are:

      • Sum of usage values during period
        • Users are charged for their usage recorded throughout the billing cycle
      • Most recent usage value during period
        • Users are charged based on the last usage recorded before the billing period ended
      • Most recent usage value
        • Users are charged for the last usage recorded throughout the subscription’s life at the end of each billing cycle
      • Maximum usage value during period
        • Users are charged for the highest amount recorded during the billing cycle

    • The optimal setup for a Moesif Billing Meter is to set this value as Sum of usage values during period since usage is reported hourly by Moesif to Stripe

  • Price description
    • This is an optional field but recommended. Here you can put a brief description of your price. This will allow you to more easily decipher which price you are selecting in the billing meter in Moesif, especially if you have multiple prices for a single product.

Once you’ve input all of the details for your product and price, you can click Save product in the top right corner of the screen. This product and price will now be saved. Follow this same procedure to create more products as needed. As you create products, you will be able to view and edit them on the products screen.

Creating the Stripe Pricing Table

During the sign-up flow in the Developer Portal, the user will be prompted for which subscription/product they would like to subscribe to. In order to make this easy to manage, the Moesif Developer Portal uses a Stripe Pricing Table to display the available options and handle the checkout.

To set up the Pricing Table, navigate to the Products page within Stripe. Once on the Products page, in the tabs available below the main menu, select Pricing tables. Once on the Pricing tables tab, click on the Create pricing table button in the top-right.

For the next steps, follow the Stripe documentation on how to create a pricing table. For each of the entries added to the Pricing Table, on the Payment settings page under the Confirmation page section, select Don’t show confirmation page and fill in the URL with http://127.0.0.1:4000/dashboard?checkout-session={CHECKOUT_SESSION_ID}. By doing this, when payments are completed, the user will be redirected back to the developer portal, and the CHECKOUT_SESSION_ID will be used to retrieve Stripe account details upon redirect.

After the pricing table is created, you’ll get an embeddable snippet of code. This code will look similar to this:

<script async src="https://js.stripe.com/v3/pricing-table.js"></script>
<stripe-pricing-table pricing-table-id="prctbl_123abc" publishable-key="pk_test_abc123">
</stripe-pricing-table>

In the my-dev-portal/.env file, we will add the values from the code including the pricing-table-id and publishable-key values. To do this, take these values and add them to the values in the .env file.

REACT_APP_STRIPE_PRICING_TABLE_ID="prctbl_123abc"
REACT_APP_STRIPE_PUBLISHABLE_KEY="pk_test_123abc"

Once added, save the .env file and move to the next step of adding the other Stripe configuration details to the Moesif Developer Portal.

Adding Stripe to the Moesif Developer Portal

Adding Stripe to the Moesif Developer Portal will require adding some details to the .env file in the Developer Portal API project.

In the my-dev-portal-api/.env file, you’ll also need to add the same value to the STRIPE_API_KEY entry.

STRIPE_API_KEY="sk_test_123abc"

Once the values are added, save the .env files.

Integrating Moesif and Stripe

Once your products and prices are created, you can integrate Stripe with Moesif. To configuring Stripe in Moesif, go to the Billing Meters screen by clicking on Billing Meters in the left-side menu. On the Billing Meters screen, click the Edit Billing Provider dropdown in the top right corner of the screen and select Stripe.

This will bring up the Stripe configuration screen to walk you through the integration. From this screen, you can get all of the info needed to plug Stripe into Moesif. Each step for configuration is covered within the modal. The below sections go into more detail, if required.

Adding the Moesif Webhook to Stripe

The first step in the integration is to add the Moesif webhook into the Moesif configuration for Stripe. Adding this allows Stripe to send subscription updates to Moesif.

To add the Moesif webhook to Stripe, in the Stripe dashboard, click on Developers in the upper right-hand side, and then Webhooks in the left-side menu. This will bring you to the Webhooks page where you can view existing webhooks and add new ones. To add a new webhook we will click the Add an endpoint button at the bottom of the screen.

From here, plug in the Moesif API endpoint URL and configure the events to listen to. You’ll want to copy your Moesif Webhook URL, shown in the Stripe Settings modal displayed in Moesif, into the Endpoint URL field. After this, click the Select Events button.

On the Select events to send screen, Scroll to the Customer section and select the option for Select all Customer events. After this, click the Add events button at the bottom of the screen. After this, you’ll be returned to the original screen where you added the endpoint details. Scroll to the bottom of the screen and click Add endpoint to save the webhook endpoint to Stripe.

Plug the Stripe API Details into Moesif

For Moesif to add usage quantities to subscriptions in Stripe, we need to add the Stripe API details into Moesif. This is done in the Stripe configuration screen in Moesif. Currently, Moesif only supports version 2020-08-27 of the Stripe API so that field defaults for the Stripe API Version field.

For the Stripe API Key field in Stripe, you’ll need to retrieve the API key from Stripe to plug it in. In Stripe, from the Developers screen click on API Keys in the left-side menu. You’ll then be able to see the private key for your API in either the Secret key or a generated Restricted keys field on the screen. Either key can be copied and used.

After copying the key from Stripe, paste the key into the Stripe API Key field on the Stripe Configuration screen in Moesif. After setting the API key value, scroll down to the bottom of the screen and click Save to save the configuration in Moesif. At this point, your Stripe integration is complete in Moesif and you can begin to use it.

Setting up a Billing Meter in Moesif

For API monetization with Moesif, a Moesif Billing Meter is required. Billing meters created in Moesif do two things:

  • track usage based on specific criteria
  • report that usage to the billing provider

Moesif allows you to set up very simple and very complex billing meters with relative ease. To create the Billing Meter, in Moesif you will navigate to the Billing Meter screen. You can do this from the left-side menu by clicking the Billing Meters menu item. Once on the Billing Meters screen, you’ll then click Add Billing Meter in the top-right corner of the screen.

The next screen to appear will be the Create Billing Meter screen where you can create and input the criteria for your Billing Meter.

Fields on this screen include:

  • Billing Meter Name
    • This is the Moesif internal name of your new Billing Meter
  • Billing Provider
    • In this dropdown, you can choose the billing provider you want to send your usage metrics.
  • Product
    • Here you can choose which product that you’ve set up in Stripe your usage metrics should be tied to.
  • Price
    • In the last field in the Billing Provider settings for the Billing Meter, you will choose which price you want to tie your usage metrics to.
  • Filters
    • Under the Filters configuration, you will configure your billing criteria to only include requests that fit certain criteria.
  • Metrics

    • Here you can choose which metric you would like to bill on. Available options include:

      • Volume > Event Count
        • This will increment usage for every event that fits the criteria outlined in the Filter criteria.
      • Uniques > Users
        • This will increment usage whenever a unique user sends a request that fits the Filter criteria. For every unique user, the count will be incremented by 1 regardless of the event count for that user.
      • Uniques > Sessions/API Keys
        • This will increment usage whenever a unique session or API key is used to send a request that fits the Filter criteria. For every unique session or API key, the count will be incremented by 1 regardless of the event count for that particular session or API key.

There are other options under Metrics, including customer metrics, as well but the above 4 tend to be the most applicable to usage-based billing.

As an example, you can create a Billing Meter that will filter traffic for a single endpoint and where requests receive a successful HTTP 200 response. We will use the Event Count metric to make sure that every request is added to the tally and sent to the billing provider.

Once your meter is set, click Create. This will create and activate the Billing Meter. After the meter is created, you will be prompted to do a Meter Test. The Meter Test will check connectivity with Stripe and that the meter is reporting usage as expected to the correct subscription. For ease, You can forego the Meter Test and run it manually when your Developer Portal setup is complete and you can create subscriptions and API keys.

Updated: