サブスクリプションの実装を構築する

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

アプリの起動時に Stripe 公開可能キーを使用して SDK を設定します。これにより、アプリが Stripe API にリクエストを送信できるようになります。

import UIKit
import StripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        StripeAPI.defaultPublishableKey = 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
        // do any other necessary launch configuration
        return true
    }
}

次に Stripe CLI をインストールします。CLI は Webhook のテストを提供します。これを実行すると Stripe への API コールを実行できます。このガイドの後続セクションでは、CLI を使った料金体系モデルの設定方法を紹介します。

# 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 CLI で商品とその価格を作成します。

この例では、「基本」と「プレミアム」という 2 つのサービスレベルオプションがある固定価格のサービスを使用しています。サービスレベルオプションごとに、1 つの商品と 1 つの継続価格を作成する必要があります (初期費用のような 1 回限りの支払いを追加する場合は、1 回限りの価格で 3 つ目の商品を作成します。わかりやすくするために、この例には 1 回限りの支払いを含めていません)。

この例では、各商品が 1 カ月間隔で請求されます。基本商品の価格は 5 USD で、プレミアム商品の価格は 15 USD です。

Stripe では、各サブスクリプションに顧客が必要です。アプリケーションのフロントエンドでユーザーから必要な情報を収集し、それをバックエンドに渡します。

住所の詳細を収集する必要がある場合、Address Element を使用すると顧客の配送先住所または請求先住所を収集できます。Address Element についての詳細は、Address Element のページをご覧ください。

struct RegisterView: View {
    @State var email = ""
    var body: some View {
        VStack {
            TextField(text: $email) {
                Text("Email")
            }
            Button {
                Task {
                    var request = URLRequest(url: URL(string: "http://localhost:4242/create-customer")!)
                    request.httpMethod = "POST"
                    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
                    request.httpBody = try! JSONEncoder().encode(["email": email])
                    let (data, _) = try! await URLSession.shared.data(for: request)
                    let responseJSON = try! JSONSerialization.jsonObject(with: data)
                    // Return the customer ID here
                    print(responseJSON["customer"])
                }
            } label: {
                Text("Submit")
            }
        }
    }
}

サーバーで、Stripe の Customer オブジェクトを作成します。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

新しい顧客がプランを選択してからサブスクリプションを作成できるようにします。このガイドでは、顧客は基本またはプレミアムから選択します。

アプリで、選択した価格 ID と顧客レコードの ID をバックエンドに渡します。

func createSubscription(priceId: String, customerId: String) async -> SubscriptionsResponse {
    var request = URLRequest(url: URL(string: "http://localhost:4242/create-subscription")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try! JSONEncoder().encode(["customerId": customerId, "priceId": priceId])
    let (responseData, _) = try! await URLSession.shared.data(for: request)
    // SubscriptionsResponse is a Decodable struct conforming to the expected response from your backend.
    // It should include the client_secret, as discussed below.
    let subscriptionsResponse = try! JSONDecoder().decode(SubscriptionsResponse.self, from: responseData)
    return subscriptionsResponse
}

バックエンドで、payment_behavior=default_incomplete を使用して、ステータスが incomplete のサブスクリプションを作成します。次に、サブスクリプションの最初の Payment Intent の client_secret をフロントエンドに返し、サブスクリプションの最新の請求書の confirmation_secret を展開して支払いを完了します。

To enable improved subscription behavior, set billing_mode[type] to flexible. You must use Stripe API version 2025-06-30.basil or later.

支払いが完了したときに決済手段をデフォルトとして保存する場合は、save_default_payment_method を on_subscription に設定します。デフォルトの決済手段を保存すると、その後のサブスクリプションの決済の成功率が高くなります。

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

この時点でサブスクリプションは inactive であり、支払いを待っています。次に示すのはレスポンスの例です。強調表示されているのは保存が必要な最小限のフィールドですが、アプリケーションが頻繁にアクセスするフィールドをすべて保存します。

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Mobile Payment Element を使用して決済情報を収集し、サブスクリプションを有効にします。Elements は、アプリケーションのデザインに合わせてカスタマイズできます。

Mobile Payment Element は、多様な決済手段に必要な決決済情報をすべて安全に収集します。Mobile Payment Element とサブスクリプションで対応可能な決済手段について、詳細をご確認ください。

アプリに Payment Element を追加する

PaymentSheet クラスを使用して、Mobile Payment Element を初期化して表示します。

struct SubscribeView: View {
    let paymentSheet: PaymentSheet
    @State var isPaymentSheetPresented = false
    init(clientSecret: String) {
        var config = PaymentSheet.Configuration()
        // Set `allowsDelayedPaymentMethods` to true if your business handles
        // delayed notification payment methods like US bank accounts.
        config.allowsDelayedPaymentMethods = true
        config.primaryButtonLabel = "Subscribe for $15/month"
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret: clientSecret, configuration: config)
    }
    var body: some View {
        Button {
            isPaymentSheetPresented = true
        } label: {
            Text("Subscribe")
        }.paymentSheet(isPresented: $isPaymentSheetPresented, paymentSheet: paymentSheet) { result in
            switch result {
            case .completed:
                // Handle completion
            case .canceled:
                break
            case .failed(let error):
                // Handle error
            }
        }
    }
}

Mobile Payment Element によって支払い画面が表示され、顧客はここで支払い方法を選択できます。このフォームでは、顧客が選択した支払い方法で必要な支払い詳細のすべてが自動的に収集されます。

allowsDelayedPaymentMethods を true に設定すると、アメリカの銀行口座などの 遅延通知型の支払い方法を使用できます。これらの支払い方法では、PaymentSheet が完了した時点では最終的な支払いステータスが判明せず、後になって成功または失敗が確定します。このようなタイプの支払い方法に対応する場合は、注文が確定済みであることを顧客に通知し、支払いが成功した場合にのみ注文のフルフィルメント (商品の発送など) を実行するようにします。

PaymentSheet.Configuration オブジェクトで appearance プロパティを使用して、アプリのデザインに合わせて Payment Element をカスタマイズできます。

支払いを確定する

Mobile Payment Element によって PaymentMethod が作成され、未完了のサブスクリプションの最初の PaymentIntent が確定され、その結果支払いが実行されます。支払いに強力な顧客認証 (SCA) が必要とされる場合は、PaymentIntent の確定前に Payment Element で認証プロセスが処理されます。

顧客はお客様のアプリから離れて、(Safari やバンキングアプリなどで) 認証する場合があります。ユーザーが認証後にアプリに自動的に戻れるようにするには、カスタム URL スキームを構成し、URL を SDK に転送するようにアプリのデリゲートを設定します。Stripe はユニバーサルリンクには対応していません。

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

さらに、PaymentSheet.Configuration オブジェクトの returnURL をアプリの URL に設定します。

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

導入を完了するには、Stripe から送信される Webhook を処理する必要があります。Webhook は、サブスクリプションによって新しい請求書が作成されるなど、Stripe 内の状態が変化するたびにトリガーされるイベントです。アプリケーションで、Webhook イベントを含む POST リクエストを受け取る HTTP ハンドラを設定し、イベントの署名を検証します。

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

開発中は、Stripe CLI を使用して Webhook を監視し、アプリケーションに転送します。開発アプリの実行中に、新しい端末で以下を実行します。

stripe listen --forward-to localhost:4242/webhook

本番環境では、ダッシュボードで Webhook エンドポイント URL を設定するか、Webhook Endpoints API を使用します。

いくつかのイベントをリッスンして、このガイドの残りのステップを完了します。サブスクリプション固有の Webhook については、サブスクリプションのイベントで詳細をご覧ください。

ここまでのステップでサブスクリプションが有効になりました。次は、ユーザーがサービスにアクセスできるようにします。これを行うには、customer.subscription.created、customer.subscription.updated、customer.subscription.deleted の各イベントをリッスンします。これらのイベントは、Subscription オブジェクトを渡します。このオブジェクトには、サブスクリプションが有効か、期日経過か、キャンセルされたかを示す status フィールドが含まれます。ステータスの一覧については、サブスクリプションのライフサイクルをご覧ください。

Webhook ハンドラで、以下を実行します。

1. サブスクリプションのステータスを確認します。active の場合、ユーザーは商品の支払いを実行しています。
2. 顧客が登録している商品を確認し、サービスへのアクセス権を付与します。価格ではなく商品を確認することにより、料金体系や請求期間の変更が必要になった場合に、柔軟に対応できます。
3. product.id、subscription.id および subscription.status を、すでに保存されている customer.id とともにデータベースに保存します。アプリケーションでユーザーに対して有効にする機能を決定する際に、このレコードを確認します。

サブスクリプションのステータスは、存続期間のどの時点でも変化する可能性があります。アプリケーションが Stripe への直接の呼び出しを行っていない場合でも同様です。たとえば、クレジットカードの有効期限が切れて更新が失敗した場合、サブスクリプションは期日経過の状態になります。また、カスタマーポータルを実装している場合、ユーザーが直接アプリケーションを開かずにサブスクリプションをキャンセルすることがあります。ハンドラを正しく実装することで、いつでもアプリケーションを Stripe と同期した状態に維持できます。

顧客にサブスクリプションのキャンセルを許可するのは一般的です。この例では、アカウントの設定ページにキャンセルオプションを追加します。

このサンプルではフロントエンドでサブスクリプション ID を収集していますが、アプリケーションではこの情報をデータベース内のログインユーザーに関する情報から取得できます。

サブスクリプションのキャンセル機能が設定されたアカウント設定

func cancelSubscription() {
    var request = URLRequest(url: URL(string: "http://localhost:4242/cancel-subscription")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try! JSONEncoder().encode(["subscriptionId": subscription.id])
    let (subscriptionResponse, _) = try! await URLSession.shared.data(for: request)
    // Update the state to show the subscription has been cancelled
}

バックエンドで、アプリから呼び出すエンドポイントを定義します。

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

バックエンドが customer.subscription.deleted イベントを受信します。

サブスクリプションがキャンセルされたら、データベースを更新して以前に保存された Stripe サブスクリプション ID を削除し、サービスへのアクセスを制限します。

キャンセルされたサブスクリプションを、再びアクティブにすることはできません。代わりに、顧客から更新された請求先情報を収集し、顧客のデフォルトの支払い方法を更新して、既存の顧客レコードから新しいサブスクリプションを作成します。

支払い方法をテストする

次の表を使用して、さまざまな支払い方法とシナリオをテストします。

イベントをモニタリングする

Webhook を設定して、アップグレードやキャンセルなどのサブスクリプションの変更イベントをリッスンします。サブスクリプションでの Webhook で詳細をご確認ください。イベントは、ダッシュボードまたは Stripe CLI で表示できます。

詳しくは、Billing の実装のテストをご覧ください。