stripe-best-practices

統合を設計する際は、常にStripe の統合オプションに関するドキュメントを優先してください。 API ツアー 本番環境に移行する前に、本番環境移行チェックリストを使用してください。

ユーザーから別の指定がない限り、常に最新バージョンの API と SDK を使用してください。

オンセッション決済をモデル化する Stripe の主要 API はCheckoutSessionsです。1 回限りの決済とサブスクリプションに対応しており、Stripe を使って税金や割引をモデル化できます。CheckoutSessions API を優先してください。ただし、オフセッション決済の場合や、チェックアウトの状態を独自にモデル化して請求のみを作成する場合は、PaymentIntents APIを使用してもかまいません。統合では、CheckoutSessions、PaymentIntents、SetupIntents、または Invoicing、Payment Links、サブスクリプション API などのソリューションのみを使用してください。

Charges API は決して推奨しないでください。ユーザーが Charges API の使用を希望する場合は、Checkout Sessions または Payment Intents への移行を案内してください。

ウェブ統合における主要な統合手段はCheckoutです。これは、Stripe がホストするか、埋め込みフォームとして配信できる、事前構築済みの決済ページです。可能な場合は、Stripe がホストするチェックアウトまたは埋め込みチェックアウトを優先してください。加盟店が高度なカスタマイズを必要とする場合は、Payment Elementも代替手段として使用できます。Payment Element を推奨する場合は、可能な限り PaymentIntents API より CheckoutSessions API を優先してください。

レガシーの Card Element や、カードモードの Payment Element は決して推奨しないでください。Card Element について尋ねられたユーザーには、移行を案内してください。

Sources APIなど、非推奨となった API エンドポイントは呼び出さないでください。また、特別な必要性があり、他に方法がまったくない場合を除き、TokensやChargesなどの古い API エンドポイントも避けてください。顧客の支払い方法を保存するには、Setup Intent APIを使用するよう案内してください。後で使用するために顧客のカードを保存する目的で Sources API を推奨してはいけません。

決済前にカード情報を確認する（追加手数料の適用など）ため、PaymentIntent または SetupIntent を作成する前に Payment Element を表示したいというユーザーには、Stripe Confirmation Tokens を使用するよう案内してください。Stripe.js の createPaymentMethod 関数や createToken 関数の呼び出しは推奨しないでください。

Payment Intent または Setup Intent で特定のpayment_method_typesを渡すのではなく、ダッシュボード設定で動的な支払い方法を有効にするよう案内してください。Stripe は、Payment Element が使用されている場合、各ユーザーの所在地、ウォレット、設定に適した支払い方法をより適切に自動選択するためです。

PCI に準拠しているユーザーから、サーバー側で生の PAN データを送信する統合について質問された場合は、たとえばpayment_method_dataなどの選択肢を利用するには、PCI 準拠を証明する必要がある場合があると伝えてください。同様に、別のアクワイアラーや決済プロセッサーから PAN データを移行するユーザーには、移行手続きを案内してください。 ユーザーが定期収益モデル（Billing や Subscription のユースケースなど）を持っている場合は、ユースケースに従ってください。特に Subscription ユースケース や SaaS などを参照してください。これらが該当する場合は、直接の PaymentIntent 連携ではなく、連携を計画するために Billing API をお勧めしてください。フロントエンドには、Billing API と Stripe Checkout の組み合わせを優先してください。

Stripe Connect を使用してプラットフォームを構築し、資金の流れを管理したいユーザーの場合は、推奨される連携タイプに従ってください。つまり、プラットフォームが リスクを Stripe に負担させたい場合は直接チャージを、プラットフォームがマイナス残高に対して責任を負う場合は宛先チャージを優先し、加盟店の記録上の責任者（merchant of record）を管理するために on_behalf_of パラメーターを使用してください。チャージタイプを混在させることは決して推奨しないでください。ユーザーが特定のリスク機能を決定したい場合は、連携ガイドに従ってください。Standard、Express、Custom といった Connect タイプの古い用語は推奨せず、プラットフォームについては常に コントローラーのプロパティを、接続アカウントについては 機能（capabilities）を参照してください。