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

商品カタログを設定する

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.

ポータルには、商品カタログの以下の属性が表示されます。

• 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.

納税者番号の収集を有効にする

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.

Stripe Tax の設定、継続支払いの税金の徴収、カスタムの決済フローでの税金の徴収、およびラインアイテムと請求書の税率の設定の方法についてご紹介します。

プレビューしてテストする

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.

設定を保存したらポータルを起動し、サンドボックスで顧客を使用してテストすることができます。ダッシュボードで顧客に移動し、アクションをクリックして、カスタマーポータルを開くを選択します。

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.

サーバー側

# 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

その他のインストールオプションについては、Stripe CLI を使ってみるをご覧ください。

クライアント側

Stripe iOS SDK はオープンソースです。詳細なドキュメントが提供されており、iOS 13 以降をサポートするアプリと互換性があります。

また、SDK が Stripe への API コールを実行できるように、公開可能キーを設定する必要もあります。すぐに開始するには、導入中にクライアント側でこれをハードコード化できますが、本番環境ではサーバーから公開可能キーを取得します。

// 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. ドメインに apple-app-site-association ファイルを追加します。
2. アプリに Associated Domains エンタイトルメントを追加します。
3. Add a fallback page for your portal redirect URLs.

関連ドメインを定義する

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

詳細については、関連ドメインのサポートに関する Apple のページを参照してください。

アプリに Associated Domains エンタイトルメントを追加する

1. アプリのターゲットの、Signing & Capabilities (署名とケイパビリティ) ウィンドウを開きます。
2. + ケイパビリティ をクリックし、関連ドメイン を選択します。
3. Add an entry for applinks:example.com to the Associated Domains list.

ユニバーサルリンクの詳細については、Apple の Universal Links for Developers (開発者のためのユニバーサルリンク) (英語) ページをご覧ください。

iOS は、apple-app-site-association ファイルで定義された URL へのリンクをインターセプトしますが、リダイレクトでアプリを開くことができないケースが発生することがあります。

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
})