Provide subscription management on iOS with a customer portal page

First, you need to register for a Stripe account.

Before you integrate the customer portal, use the Dashboard to define what your users can do with the portal. Choose your settings for sandboxes and live mode, based on your product and price catalog.

If you want to create multiple portal configurations for different sets of customers (or if you’re a Connect platform and want to manage configurations for your connected accounts), you can do so using the API:

curl https://api.stripe.com/v1/billing_portal/configurations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "features[invoice_history][enabled]"=true

Set a product catalog

If you allow customers to upgrade, downgrade, or change the quantities of their subscriptions, you must also set a product catalog. This includes the products and prices that your customers can upgrade or downgrade to, and the subscriptions they can update quantities on. See how to create a product for more details about creating products and prices. If you’re using the customer portal for invoicing only, you don’t need to set a product catalog.

The portal displays the following attributes of your product catalog:

• Product name and description—These attributes are editable in the Dashboard and API.
• Quantity restrictions per product—These attributes are editable in the Dashboard.
• Price amount, currency, and billing interval—These attributes are fixed, and you can only set them when you create them in the Dashboard and API.

Enable tax ID collection

If you use Stripe Tax to automatically collect taxes for subscriptions or invoices, you can let customers set and update their tax IDs in the customer portal. Stripe Billing adds the tax IDs to the customers’ invoices. To allow customers to set their tax IDs, go to the Customer portal settings and toggle on Tax ID. For more information, see how customer tax IDs work with subscriptions and invoices.

Learn how to set up Stripe Tax, collect taxes for recurring payments, collect taxes in your custom payment flows and set tax rates for line items and invoices.

Preview and test

As you configure your settings, click Preview to preview the portal. This launches a read-only version of the portal that lets you see how your customers might manage their subscriptions and billing details.

After saving your settings, you can launch the portal and test it by using a customer in a sandbox. Navigate to a customer in the Dashboard, click Actions, and then select Open customer portal.

You can only preview the portal as a read-only version when your Dashboard is in a sandbox. If you can’t preview and test the portal, check your settings to make sure that your configuration is saved in a sandbox. For previewing and testing to work, you also need to have edit permissions in the Dashboard.

Server-side

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Next, install the Stripe CLI. The CLI provides the webhook testing that you need.

# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

For additional install options, see Get started with the Stripe CLI.

Client-side

The Stripe iOS SDK is open source, fully documented, and compatible with apps supporting iOS 13 or above.

You also need to set your publishable key so that the SDK can make API calls to Stripe. To get started quickly, you can hardcode this on the client while you’re integrating, but fetch the publishable key from your server in production.

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
STPAPIClient.shared.publishableKey = 
"pk_test_TYooMQauvdEDq54NiTphI7jx"

When a customer wants to make changes to their subscription, generate a URL for the portal page using their Stripe customer ID through the portal session API.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2');

app.get('/customer_portal_url', async (req, res) => {

  // Replace this with your actual customer lookup logic
  const customerId = 'cus_...'; // Get this from your database

  const billingSession = await stripe.billingPortal.sessions.create({
    customer: customerId,
    return_url: 'https://example.com/portal_redirect',
  });

  res.json({
    url: billingSession.url
  });
})

Universal links allow the customer portal to deep link into your app. To configure a universal link:

1. Add an apple-app-site-association file to your domain.
2. Add an Associated Domains entitlement to your app.
3. Add a fallback page for your portal redirect URLs.

Define the associated domains

Add a file to your domain at .well-known/apple-app-site-association to define the URLs your app handles. Prepend your App ID with your Team ID, which you can find on the Membership page of the Apple Developer Portal.

{
  "applinks": {

      "apps": [],
      "details": [
           {
             "appIDs": [ "A28BC3DEF9.com.example.MyApp1",
                         "A28BC3DEF9.com.example.MyApp1-Debug" ],
             "components": [
               {
                  "/": "/checkout_redirect*",
                  "comment": "Matches any URL whose path starts with /checkout_redirect"
               }
             ]
           }
       ]
   }
}

curl -I https://example.com/.well-known/apple-app-site-association

See Apple’s page on supporting associated domains for more details.

Add an Associated Domains entitlement to your app

1. Open the Signing & Capabilities pane of your app’s target.
2. Click + Capability, then select Associated Domains.
3. Add an entry for applinks:example.com to the Associated Domains list.

For more information on universal links, see Apple’s Universal Links for Developers page.

Although iOS intercepts links to the URLs defined in your apple-app-site-association file, you might encounter situations where the redirect fails to open your app.

Make sure to create a fallback page at your return_url. For example, you can define a custom URL scheme for your app and use it to link back in case the universal link fails.

Add a button to open the customer portal in your app. This button:

1. Calls your server-side endpoint to create a portal session.
2. Returns the portal page URL to the client.
3. Opens the URL in Safari.

import Foundation
import SwiftUI
import StoreKit

struct SubscriptionManagementView: View {

    @EnvironmentObject var myBackend: MyServer

    var body: some View {
        // Check if payments are blocked by Parental Controls on this device.
        if !SKPaymentQueue.canMakePayments() {
            Text("Payments are disabled on this device.")
        } else {
            Button {
                myBackend.createCustomerPortalSession { url in
                    UIApplication.shared.open(url, options: [:], completionHandler: nil)
                }
            } label: {
                Text("Manage subscriptions")
            }.onOpenURL { url in
                // Handle the universal link from the customer portal.
                // Implement any necessary behavior, such as refreshing the customer's subscription status.
            }
        }
    }
}

When customers make changes to their subscription status through the customer portal, Stripe sends you webhooks, such as customer.subscription.created, customer.subscription.deleted, and customer.subscription.updated. For a full list of events and information about them, see Using webhooks with subscriptions. Make sure you handle all events necessary to accurately monitor the statuses of the subscriptions you’ve configured.

For testing purposes, you can monitor events in the Dashboard or using the Stripe CLI. For production, set up a webhook endpoint and subscribe to appropriate event types. If you don’t know your STRIPE_WEBHOOK_SECRET key, click the webhook link in the Dashboard to view it.

const express = require('express');
const app = express();
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')('<secret key>')

app.post('/webhook', async (req, res) => {
  let data;
  let eventType;
  // Check if webhook signing is configured.
  const webhookSecret = 
"{{STRIPE_WEBHOOK_SECRET}}"
  if (webhookSecret) {
    // Retrieve the event by verifying the signature using the raw body and secret.
    let event;
    let signature = req.headers["stripe-signature"];

    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        signature,
        webhookSecret
      );
    } catch (err) {
      console.log(`⚠️  Webhook signature verification failed.`);
      return res.sendStatus(400);
    }
    // Extract the object from the event.
    data = event.data;
    eventType = event.type;
  } else {
    // Webhook signing is recommended, but if the secret is not configured in `config.js`,
    // retrieve the event data directly from the request body.
    data = req.body.data;
    eventType = req.body.type;
  }
  switch (eventType) {
    case 'customer.subscription.created': {
      const subscription = event.data.object;
      const customerId = subscription.customer;
      myUserDB.setUserSubscriptionIsActive(customerId, true);
      break;
    }
    case 'customer.subscription.deleted': {
      const subscription = event.data.object;
      const customerId = subscription.customer;
      myUserDB.setUserSubscriptionIsActive(customerId, false);
      break;
    }
    // Add other relevant event types as needed
  }

  res.sendStatus(200); // Acknowledge receipt of the webhook
})