プラットフォーム上のビジネスが支払いを直接受け付けられるようにする

まず、Stripe アカウントが必要です。今すぐ登録してください。

サーバー側

この組み込みは、Stripe API と通信するサーバー上にエンドポイントを必要とします。サーバーから Stripe API にアクセスするには、次のように Stripe の公式ライブラリーを使用します。

# Available as a gem
sudo gem install stripe

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

クライアント側

React Native SDK はオープンソースであり、詳細なドキュメントが提供されています。内部では、ネイティブの iOS および Android の SDK を使用します。Stripe の React Native SDK をインストールするには、プロジェクトのディレクトリーで (使用するパッケージマネージャーによって異なる) 次のいずれかのコマンドを実行します。

yarn add @stripe/stripe-react-native

次に、その他の必要な依存関係をインストールします。

• iOS の場合は、ios ディレクトリーに移動して pod install を実行し、必要なネイティブ依存関係もインストールします。
• Android の場合は、依存関係をインストールする必要はありません。

Stripe の初期化

React Native アプリで Stripe を初期化するには、決済画面を StripeProvider コンポーネントでラップするか、initStripe 初期化メソッドを使用します。publishableKey の API 公開可能キーのみが必要です。次の例は、StripeProvider コンポーネントを使用して Stripe を初期化する方法を示しています。

import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      // Your app code here
    </StripeProvider>
  );
}

ユーザー (売り手またはサービスプロバイダー) がプラットフォームに登録したら、ユーザーの Account (アカウント) (「連結アカウント」と呼ばれる) を作成し、決済を受け付けて売上をユーザーの銀行口座に入金できるようにします。連結アカウントは Stripe の API でユーザーを表し、アカウント登録要件の収集を簡単にして Stripe がユーザーの本人確認を実行できるようにします。ストアビルダーの例では、連結アカウントはオンラインストアを設定するビジネスを表します。

Step 2.1: 連結アカウントを作成し、情報を事前入力するサーバー側

/v1/accounts API を使用して連結アカウントを作成します。デフォルトの連結アカウントのパラメーターを指定するか、アカウントタイプを指定して、連結アカウントを作成できます。

curl -X POST https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

連結アカウントの情報をすでに収集している場合は、Account オブジェクトにその情報を事前入力できます。個人情報や事業情報、外部のアカウント情報など、あらゆるアカウント情報を事前に入力できます。

Connect アカウント登録で、事前入力された情報が要求されることはありません。ただし、アカウント所有者は Connect 利用規約に同意する前に、事前入力された情報を確認するよう求められます。

実装内容をテストする場合、テストデータを使用してアカウント情報を事前入力します。

ステップ 2.2: アカウントリンクを作成する サーバー側

以下のパラメーターを使用して Account Links API を呼び出すことで、アカウントリンクを作成できます。

• account
• refresh_url
• return_url
• type = account_onboarding

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding

ステップ 2.3: ユーザーをアカウントリンク URL にリダイレクトする クライアント側

Account Links リクエストへのレスポンスには、キー url の値が含まれます。Account Links は一時的なものであり、連結アカウントのユーザーの個人情報へのアクセスを許可するため、使用できるのは 1 回限りです。情報の事前入力は、アカウントリンクを生成する前に行う必要があります。Standard アカウントのアカウントリンクを作成した後は、そのアカウントの情報を読み書きできなくなります。この URL をアプリに送信し、ブラウザーで開いて、ユーザーが Connect アカウント登録フローを完了できるようにしてください。

ステップ 2.4: ユーザーがプラットフォームに戻るように処理する クライアント側

Connect アカウント登録では、ユーザーがプラットフォームにリダイレクトされるすべてのケースを処理するために、return_url と refresh_url の両方を渡す必要があります。ユーザーが快適に操作できるようにするには、これらを正しく実装することが重要です。ディープリンクを設定して、Stripe のウェブページからアプリに自動的にリダイレクトするようにできます。

return_url

ユーザーが Connect アカウント登録フローを完了すると、Stripe はこの URL へのリダイレクトを行います。ただしこれは、すべての情報が収集されたことを意味するものでも、アカウントの要件がすべて満たされたことを意味するものでもありません。ユーザーがフローに正常に入り、そこから正常に出たことのみを意味します。

パラメーターの状態がこの URL を通じて渡されることはありません。ユーザーが return_url にリダイレクトされたら、以下のいずれかを行い、アカウントの details_submitted パラメーターの状態を確認します。

• account.updated Webhook をリッスンする
• Accounts API を呼び出して、返されたオブジェクトを調べる

refresh_url

以下のケースでは、ユーザーが refresh_url にリダイレクトされます。

• リンクの期限が切れた (リンク作成後、数分が経過した)
• ユーザーがすでにリンクを使用した (ユーザーがページを更新したか、ブラウザーで戻るボタンまたは進むボタンをクリックした)
• プラットフォームがアカウントにアクセスできなくなった
• アカウントが拒否された

refresh_url はサーバでメソッドをトリガーし、同じパラメータを使用して Account Link (アカウントリンク) を再度呼び出し、シームレスな体験を作成するためにユーザを Connect アカウント登録フローにリダイレクトする必要があります。

ステップ 2.5: アカウント登録を完了していないユーザーを処理する

return_url にリダイレクトされたユーザーは、アカウント登録プロセスを完了していないことがあります。/v1/accounts エンドポイントを使用してユーザーのアカウントを取得し、charges_enabled を確認します。アカウント登録が完全でない場合は、UI プロンプトを表示し、ユーザーが後でアカウント登録を続行できるようにします。ユーザーは、新しいアカウントリンク (システムで生成された) で本番環境利用の申請を完了できます。アカウントの details_submitted パラメーターの状態を確認すると、ユーザーがアカウント登録プロセスを完了したかどうかを調べることができます。

支払い方法の設定を表示し、サポートする支払い方法を有効にします。カード支払いはデフォルトで有効化されていますが、支払い方法は必要に応じて有効か無効かを設定できます。

この接続方法では、以下の 3 つの Stripe API オブジェクトを使用します。

1. PaymentIntent (支払いインテント): Stripe はこれを使用して、顧客から支払いを回収する意図を示し、プロセス全体を通して支払いの試行と支払い状態の変化を追跡します。

2. (オプション) Customer (顧客): 今後の支払いに備えて決済手段を設定するには、決済手段をCustomer に関連付ける必要があります。Customer オブジェクトは、顧客がビジネスでアカウントを作成するときに作成します。顧客がゲストとして支払いを行う場合は、支払いの前に Customer オブジェクトを作成し、後でこのオブジェクトを顧客のアカウントを表す内部表現に関連付けることができます。

3. (オプション) Customer Ephemeral Key (顧客の一時キー): Customer オブジェクトの情報は機密情報であるため、アプリから直接取得することはできません。Ephemeral Key により、SDK に Customer への一時的なアクセス権が付与されます。

セキュリティ上の理由により、アプリでこれらのオブジェクトを作成することはできません。代わりに、サーバー側で以下を行うエンドポイントを追加します。

1. Customer を取得するか、新規作成する。
2. Customer の一時キーを作成する。
3. amount、currency、customer、 を指定して PaymentIntent を作成します。オプションで、automatic_payment_methods パラメーターを含めることもできます。Stripe は、最新バージョンの API ではこの機能をデフォルトで有効にしています。
4. PaymentIntent の client secret、一時キーの secret、顧客の id、および貴社の公開可能キーをアプリに返します。

決済プロセス中に顧客に表示される支払い方法は、PaymentIntent にも含まれています。Stripe にダッシュボードの設定から支払い方法を取得するよう指定することも、手動でリストに表示することもできます。選択したオプションにかかわらず、顧客に表示される支払い方法は、PaymentIntent で渡す通貨によって絞り込まれることにご注意ください。たとえば、PaymentIntent で eur を渡し、ダッシュボードで OXXO が有効になっている場合、OXXO は eur による決済に対応していないため、顧客に表示されません。

構築済みのシステムで、支払い方法を提供するためにコードベースのオプションが必要になる場合を除き、自動化されたオプションを使用することをお勧めします。これは、Stripe が通貨、支払い方法の制約、その他のパラメーターを評価して、対応可能な支払い方法を決定するためです。自動化されたオプションでは、購入完了率の向上につながり、使用通貨と顧客の所在地に最適な支払い方法が優先的に表示されます。

# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-04-30.basil" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d application_fee_amount="123" \

決済ページでは、モバイル決済 Element を表示する前に以下を実行する必要があります。

• 購入商品と合計金額を表示する
• 必要な配送先情報を収集する
• Stripe の UI を表示する決済ボタンを含める

アプリの決済フローで、前のステップで作成したバックエンドのエンドポイントにネットワークリクエストを送信し、useStripe フックから initPaymentSheet を呼び出します。

export default function CheckoutScreen() {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const fetchPaymentSheetParams = async () => {
    const response = await fetch(`${API_URL}/payment-sheet`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { paymentIntent, ephemeralKey, customer } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer,
    };
  };

  const initializePaymentSheet = async () => {
    const {
      paymentIntent,
      ephemeralKey,
      customer,
    } = await fetchPaymentSheetParams();

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerId: customer,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment
      //methods that complete payment after a delay, like SEPA Debit and Sofort.
      allowsDelayedPaymentMethods: true,
      defaultBillingDetails: {
        name: 'Jane Doe',
      }
    });
    if (!error) {
      setLoading(true);
    }
  };

  const openPaymentSheet = async () => {
    // see below
  };

  useEffect(() => {
    initializePaymentSheet();
  }, []);

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

顧客が決済ボタンをタップしたら、presentPaymentSheet() を呼び出して画面を表示します。顧客が支払いを完了すると、この画面は閉じ、オプションの StripeError<PaymentSheetError> とともに promise が解決されます。

export default function CheckoutScreen() {
  // continued from above

  const openPaymentSheet = async () => {
    const { error } = await presentPaymentSheet();

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else {
      Alert.alert('Success', 'Your order is confirmed!');
    }
  };

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

エラーがない場合は、ユーザーに完了したことを伝えます (注文確認画面を表示するなど)。

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

The customer might navigate away from your app to authenticate (for example, in Safari or their banking app). To allow them to automatically return to your app after authenticating, configure a custom URL scheme and set up your app delegate to forward the URL to the SDK. Stripe doesn’t support universal links.

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

Additionally, set the returnURL on your PaymentSheet.Configuration object to the URL for your app.

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

支払いが完了すると、Stripe は payment_intent.succeeded イベントを送信します。ダッシュボードの Webhook ツールを使用するか Webhook のガイドに従ってこれらのイベントを受信し、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行します。

クライアントからのコールバックを待つのではなく、これらのイベントをリッスンします。クライアントでは、コールバックが実行される前に顧客がブラウザーのウィンドウを閉じたり、アプリを終了する場合、また悪意を持つクライアントがレスポンスを不正操作する場合もあります。非同期型のイベントをリッスンするよう組み込みを設定すると、単一の組み込みで複数の異なるタイプの支払い方法を受け付けることができます。

Payment Element を使用して支払いを回収する場合は、payment_intent.succeeded イベントのほかにこれらのイベントを処理することをお勧めします。

実装内容をテストするためのその他の情報については、テストをご覧ください。