Setting Up Subscriptions with Stripe

Introduction

Webvanta allows you to create subscriptions that integrate with your Stripe account and update automatically via a webhook. You'll need some basic JavaScript knowledge, understanding of the Stripe API, and site configuration to get this working.

Setup

There are a few configuration steps you must follow to ensure the process is automated correctly. Configuration settings in bold are required to contain a value.

Name   Description
service.stripe.api_secret_key   Your Stripe API secret key, found here
service.stripe.webhook_secret   The signing secret to your webhook, found here
service.stripe.subscription.customer_id_field   The name of the text field in which to store the Stripe customer ID
service.stripe.subscription.id_field   The name of the text field to use for storing the Stripe subscription ID
service.stripe.subscription.active_subscription_field   The name of the checkbox field to display whether a subscription is currently active
service.stripe.subscription.user_id_field   The name of the text field to identify the user a subscription item belongs to. Providing a value is optional.

The API secret key and webhook secret allow us to create customers, subscriptions, and invoices in your Stripe account on your behalf and respond to events such as payment success and failure.

Important note: the field specified by service.stripe.subscription.customer_id_field MUST be added to the user profile definition, which can be edited at /admin/dy_schemas/edit_user_profile.

The subscription ID field and the active subscription field may be added to any custom item type, including the user profile definition. For per-user subscriptions, including these fields in the user profile definition is the simplest choice.

Please do not add any of the required subscription fields to frontend forms - these fields are managed automatically and do not require any manual submission.

Webhook

Create a webhook endpoint in your Stripe dashboard here that points to /admin/api/v2/stripe/webhook. Webvanta will now update the active subscription field automatically based on successful or failed payments for a given subscription, and respond appropriately to customer deletion and subscription deletion events.

Multiple Subscriptions

If you would like to manage multiple subscriptions for each user using a custom item type, then include the subscription ID field, active subscription field, and the user ID field in the custom item type definition. The user ID field should contain the value given by <w:user key="id" />.

For example, I might want to store Stripe subscription information in a custom item type called 'membership'. The item definition for 'membership' must then contain fields to store the subscription ID, whether the subscription is active, and the user ID of the person the membership item belongs to. I might name these fields 'subscription', 'is_active', and 'user', respectively. The names of those fields are the values of their respective configuration options listed above. You can name the fields anything you like, as long as you list them correctly in the configuration.

API Endpoints

Each site gets its own API endpoints to interact with Stripe, which you can access using some JavaScript code. The endpoints along with their HTTP methods and parameters are listed in the table below.

HTTP Method Endpoint Path Parameters
POST /admin/api/v2/stripe/create_subscription (customer), subscription, item_id
GET /admin/api/v2/stripe/get_subscription item_id
DELETE /admin/api/v2/stripe/delete_subscription item_id, at_period_end
GET /admin/api/v2/stripe/get_customer  
PUT /admin/api/v2/stripe/update_customer customer

Here are detailed descriptions of each parameter listed above:

  • The 'customer' parameter is a hash describing a Stripe customer object.
    • For the create_subscription endpoint, you only need to send this parameter once per user, as the newly created customer ID will be stored in the Webvanta user profile of that customer. If the user is already associated with a Stripe customer, this parameter will be ignored.
    • For the update_customer endpoint, this parameter will contain the values used to update the current user's Stripe customer.
  • The 'subscription' parameter is a hash describing a Stripe subscription object. You don't need to include the customer ID here, since it will already be stored in the current user's profile.
  • The 'item_id' parameter indicates the ID the specific database item in which to access information for a single subscription. The desired item type must include the fields discussed in the setup section.
  • The 'at_period_end' parameter is a value of '0' (false) or '1' (true) indicating whether or not to cancel a subscription at the end of the current period. See here for more information.

Please note that some fields passed to the API will be ignored, so as to limit the client's effect on the payment process:

  • In the 'customer' parameter: the 'account_balance' field has been restricted.
  • In the 'subscription' parameter, the fields 'tax_percent', 'trial_end', and 'trial_period_days' have been restricted.

And here are descriptions of the response behavior of the above endpoints:

  • The create_subscription endpoint will return a 201 reponse upon success, with the resulting subscription object as JSON in the response body.
  • The get_subscription endpoint will return a 200 response upon success, with the subscription object as JSON in the response body.
  • The delete_subscription endpoint will return an empty 200 response upon successful deletion of the subscription. Note that the subscription information in your site's database will not be cleared until Webvanta receives a webhook request from Stripe indicating the subscription has been deleted.
  • The get_customer endpoint will return a 200 response upon success, with the current user's associated customer object as JSON in the response body.
  • The update_customer endpoint will return a 200 response upon success, with the updated customer object as JSON in the response body.
  • Endpoints will return a 400 response if Stripe refuses to accept the data provided in the request.
  • Endpoints will return a 401 unauthorized response if the user is not logged in or does not have access to edit the desired item.
  • Endpoints will return a 500 reponse if any other errors occur.

A user has access to the item referred to by 'item_id' if one of the following conditions are met:

  • The item ID is their user profile ID.
  • The item's user ID field (named by the configuration option service.stripe.subscription.user_id_field) contains the ID of the user performing the request.