You can manage Subscriptions for Patients and accept Payments for those Subscriptions through Capable Health using our Stripe integration. Below, we walk through how to create Subscription Plan products in Stripe and display them to Patients as well as how create a Subscription for a Patient using the Capable API.

Set up the Stripe integration

First, you’ll need to set up the integration with Stripe. You’ll be taken through the steps of creating a new Stripe account through Capable, which Stripe refers to as a “connected account.” You can’t connect an existing Stripe account to Capable, but you can use an existing Stripe login credentials when creating your new Capable connected account. Using existing login credentials will let you access any existing Stripe accounts you may have and the Capable connected account from the same Stripe dashboard.

Go to your Capable portal and navigate to the “Integrations” page. Find the Stripe integration section and click “Edit”. On the Stripe integration page in the Capable portal, click “Start Integration”. You’ll be taken to Stripe, where you’ll need to answer some questions about your business.

❗️

You should follow this process in both your production and sandbox Capable environments, which will create two separate Stripe connected accounts with Capable. Setting up the integration in your sandbox environment will allow you to perform proper testing of your application. Please note: The integration for your sandbox environment will use Stripe’s “Test Mode”, which will disable any payments from actually being processed. When filling out the forms on Stripe to set up the integration for your sandbox environment, you can use dummy data rather than real info about your business.

Create Subscription Plan products in Stripe

Now you’ll be ready to create Subscription Plan products in Stripe. Go to the Stripe admin portal and click on “Products”.

Click on “Add product” and add the relevant product details: Name, Description, and Price information. Please note: We recommend creating a separate Stripe product for each Subscription you’d like to offer, rather than multiple “prices” for a single product. Click “Save product” when finished.

Offering free trials

You can offer a free trial period for any Stripe Subscription Plan. To include a trial period on a Stripe plan, add a metadata key-value pair to the Stripe price (not the product) with a key of trial_period_in_days, as shown in the screenshot below.

Creating a Subscription for a Patient

After you’ve created products in Stripe that correspond to your Subscription Plans, you can use the Capable Health API to retrieve the Subscription Plans and create and manage Subscriptions for your Patients.

Retrieving the Subscription Plans

After the plans have been created on the Stripe dashboard, you can view them with the Capable /subscription_plans endpoint. Then, you can use the Subscription Plan objects to display info about the plans to your Patients.

In subsequent steps, you’ll need the price IDs from the Subscription Plan objects. Price IDs look like this: price_1KbYRD2R3n1Hr8BquPJk7jKw.

Creating a Subscription

You’ll need to create a Subscription for a Patient before the user can pay for it. (Subscriptions that aren’t paid for retain the status “incomplete”.) To create a Subscription, you simply pass the relevant price_ids and the patient_id to the POST /subscriptions endpoint.

📘

We also support Subscriptions that run for just a single month. If you'd like a Subscription to end after the first billing period, just set the cancel_at_period_end parameter to true , and the Subscription will be cancelled at the end of the given billing period.

Collecting payment for a Subscription

Stripe offers multiple ways to create a checkout experience and collect payment from users. If you’re building a single-page application (SPA), the easiest approach is to use the Stripe Elements widget. If you have a server-side application or a mobile app, Stripe offers other options. We support the use of Strip Coupons + promo codes .

Regardless of the approach you take, you’ll need two pieces of data to collect payment:

• Your Stripe publishable key: You can find this on your Stripe dashboard, in the “Developers” section, under “API keys”. We recommend storing this key in an environment variable in your application.

• The Subscription’s payment intent client_secret: This client secret can be found in the Subscription object returned in the response when creating the Subscription for a Patient. It can be found nested under latest_invoice.payment_intent in the Subscription object, i.e., latest_invoice.payment_intent.client_secret.

Viewing Patient Subscriptions

You can view Subscriptions with the GET /subscriptions endpoint. A Patient can view their own Subscriptions with a Patient token using that endpoint and filtering by patient_id with their Patient ID.

Canceling a Subscription

You can cancel a Patient Subscription with a call to the POST /subscriptions/{id} /cancel endpoint using the relevant Subscription ID.

Testing Stripe Payments

When testing Stripe, start by using “Test mode.” In your Capable Health sandbox environment, the Stripe connected account should only ever be used in “Test mode.”

Use test card values to go through your flow. You can use the US Visa test card number 4242 4242 4242 4242. The expiration date can be any future date, and the CVV can be any three digits, e.g., 123, or any four digits for Amex.

Stripe has a comprehensive list of other card numbers that can be used to simulate different payment methods, countries, and declined cards.

You can test on production only with real cards. To avoid being charged, you can either refund the payment after making it, or use a 100% off coupon and promo code when paying. These are available for both subscriptions and one-time payments. Using promo codes during checkout is possible with the allow_promotion_codes parameter.

We recommend that you test as much as possible in “Test mode” and run a limited number of tests live to avoid needing to create real charges. Use promo codes and refunds instead of changing the price of subscriptions and products for testing.