サーバー側のロジックを追加する

Stripe Apps を使用すると、サーバー側のロジックにセルフホスト型のバックエンドを追加できます。セルフホスト型のバックエンドサービスでは、次の実行が可能です。

• サーバー側の組み込みを必要とするサードパーティーのシステムと安全に連携します。
• Stripe からの Webhook イベントに登録し、Stripe を他のシステムと同期します。
• ユーザーがブラウザーを閉じたときに実行する、存続期間の長いアプリロジックを使用します。
• cron ジョブのような機能を提供するアプリを構築して、特定の操作をスケジュールします。

セルフホスト型のバックエンドとアプリの関連性

UI からアプリのバックエンドに対してユーザーを認証する

ダッシュボードからユーザーを認証するには、バックエンドに、共有シークレット付きのシグネチャーと、現在サインインしているダッシュボードユーザーのアカウントとユーザー ID が必要です。ユーザーに API を呼び出す権限がない場合は、権限エラーが返されます。

はじめに

1. バックエンドサービスが、HTTP リクエストを送受信できることを確認します。これまでに API サーバーを構築したことがない場合は、インタラクティブな Webhook エンドポイントビルダーを使用してみることを検討してください。

2. アプリをアップロードして共有シークレットを作成します。

   Command Line

   stripe apps upload

   アプリの最新バージョンの開発を完了していなくても問題ありません。アップロードしても、本番環境のアプリは更新されません。

3. バックエンドで署名を確認するため、アプリのシークレットを取得します。

   a. アプリからアプリを選択し、Stripe アプリの詳細ページに移動します。

   b. アプリケーション ID にあるオーバーフローメニュー () をクリックし、署名シークレットをクリックして署名シークレットダイアログを開きます。

   c. クリップボード をクリックし、署名シークレットダイアログからアプリのシークレットをコピーします。

署名付きのリクエストを送信する

署名付きのリクエストをアプリのバックエンドに送信するには、次のようにします。

1. fetchStripeSignature 非同期関数を使用して、現在のシグネチャーを取得します。
2. Stripe-Signature ヘッダーに署名を追加します。
3. リクエストに user_id オブジェクトと account_id オブジェクトを含めます。
4. アプリのバックエンドで、リクエストに署名、アプリのシークレット、user_id、および account_id が含まれていることを確認します。

追加データを指定して署名付きのリクエストを送信する例をご覧ください。

Stripe-Signature ヘッダーがある Stripe アプリからのリクエストの例:

import {fetchStripeSignature} from '@stripe/ui-extension-sdk/utils';

const App = ({ userContext, environment }: ExtensionContextValue) => {
  const makeRequestToMyBackend = async (endpoint, requestData) => {
    // By default the signature is signed with user id and account id.
    const signaturePayload = {
      user_id: userContext?.id,
      account_id: userContext?.account.id,
    };
    return fetch(`https://example.com/${endpoint}/`, {
      method: 'POST',
      headers: {
        'Stripe-Signature': await fetchStripeSignature(),
        'Content-Type': 'application/json',
      },
      // Include the account ID and user ID in the body to verify on backend.
      body: JSON.stringify({
        ...requestData,
        ...signaturePayload,
      }),
    });
  };
  ...
}

リクエストを確認するサンプルバックエンド:

署名確認を実行する際は、ペイロードのフィールドの順序と名前が重要であることに注意してください。user_id は account_id の前にあり、結果のオブジェクトは次のようになります。{ user_id, account_id }

// 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')(process.env.STRIPE_API_KEY);
const express = require('express');

// Find your app's secret in your app settings page in the Developers Dashboard.
const appSecret = 'absec_...';

// This example uses Express.
const app = require('express')();
app.use(express.json());

// Match the raw body to content type application/json.
app.post('/do_secret_stuff', (request, response) => {
  const sig = request.headers['stripe-signature'];
  // Retrieve user id and account id from the request body
  const payload = JSON.stringify({
    user_id: request.body['user_id'],
    account_id: request.body['account_id']
  });
  try {
    // Verify the payload and signature from the request with the app secret.
    stripe.webhooks.signature.verifyHeader(payload, sig, appSecret);
  } catch (error) {
    response.status(400).send(error.message);
  }
  // Handle the request by returning a response
  // to acknowledge receipt of the event.
  response.json({ success: true });
});

app.listen(3000, () => console.log('Running on port 3000'));

追加データを指定して署名付きのリクエストを送信する

ユーザーを認証するには、ペイロード (追加データ) を指定して署名付きリクエストを送信します。追加のペイロードリクエストを指定して fetchStripeSignature 関数を呼び出すと、user_id、account_id、およびこの関数に渡した追加ペイロードを使用して署名が作成されます。デフォルトでは、Stripe アプリは user_id と account_id を使用して署名文字列を生成します。

追加ペイロードを使用してシークレットを生成する例:

// A valid payload object has keys of type string
// and values of type string, number, or boolean.
const payload = {
  "transaction_id": 'ipi_1KRmFUFRwUQjTSJEjRnCCPyV',
  "amount": 100,
  "livemode": false,
};

fetch(`https://example.com/do_more_secret_stuff/`, {
  method: 'POST',
  headers: {
    'Stripe-Signature': await fetchStripeSignature(payload),
    'Content-Type': 'application/json',
  },
  // Append the account ID and user ID in the body to verify on backend.
  body: JSON.stringify({
    ...payload,
    user_id: 'usr_K6yd2CbXLO9A5G',
    account_id: 'acct_1JSkf6FRwUQjTSJE',
  }),
});

追加ペイロードを使用して生成された署名を検証するサンプルバックエンド

// Match the raw body to content type application/json.
app.post('/do_more_secret_stuff', (request, response) => {
  try {
    // Verify the signature from the header and the request body that
    // contains the additional data, user ID, and account ID with the app secret.
    stripe.webhooks.signature.verifyHeader(request.body, sig, appSecret);
  } catch (error) {
    response.status(400).send(error.message);
  }
  // Handle the request by returning a response
  // to acknowledge receipt of the event.
  response.json({ success: true });
});

ユーザーの役割を確認する (オプション)

特定の user_id に割り当てられたユーザーの役割を確認するには、ペイロードに stripe_roles キーを含めます。これを userContext?.roles で指定すると、RoleDefinitions のリストが返されます。ペイロードの役割が指定された user_id に割り当てられていない場合、fetchStripeSignature が無効なリクエストエラー (400) を返します。

// Provide this special key in the same way you'd
// provide any other key to the additional payload.
const payload = {
  "stripe_roles": userContext?.roles,
};

fetch(`https://example.com/do_more_secret_stuff/`, {
  method: 'POST',
  headers: {
    'Stripe-Signature': await fetchStripeSignature(payload),
    'Content-Type': 'application/json',
  },
  // Append the account ID and user ID in the body to verify on backend.
  body: JSON.stringify({
    ...payload,
    user_id: 'usr_K6yd2CbXLO9A5G',
    account_id: 'acct_1JSkf6FRwUQjTSJE',
  }),
});

シークレットを期限切れにして作成する

シークレットが漏洩した場合、現在のアプリのシークレットは、すぐに失効させるか、最大 24 時間後に失効させることができます。後者の場合、バックエンドでアプリのシークレットを更新する時間が確保され、この間は、漏洩したシークレットと新たに生成されたシークレットの両方がエンドポイントで有効になります。Stripe は、有効期限が切れるまで、シークレットごとに署名を 1 つ生成します。

アプリのシークレットを期限切れにして作成するには、以下を手順に従います。

1. アプリでアプリを選択し、Stripe アプリの詳細ページに移動します。
2. ページヘッダーで、オーバーフローメニュー () をクリックし、署名シークレットをクリックして署名シークレットのダイアログを開きます。
3. 署名シークレットダイアログからシークレットを期限切れにするをクリックして、「シークレットを期限切れにする」ダイアログを開きます。
4. 現在のアプリのシークレットの有効期限を選択します。
5. シークレットを期限切れにするをクリックします。

クロスオリジンリソース共有 (CORS) を処理する

クロスオリジンリソース共有 (CORS) は、クロスサイトスクリプティング攻撃(XSS)からアプリを安全に保つための重要なメカニズムです。Stripe App UI 拡張機能は、必然的にオリジン間およびサンドボックス化された iframe 内で使用されるため、クロスオリジンリクエストヘッダーの処理には特定のアプローチを採用する必要があります。

UI 拡張機能でバックエンドサービスのデータを取得するには、以下が行われるようにバックエンドサービスを設定する必要があります。

• Options メソッドを使用するリクエストを許可する。
• null オリジンからのリクエストを許可するには、Access-Control-Allow-Origin を * に設定します。

多くのバックエンドフレームワークには、CORS の処理に役立つライブラリとガイダンスが用意されています。より詳細なガイダンスについては、フレームワークのドキュメントをご確認ください。

特定のユーザーまたはアカウントの代わりに Stripe からのリクエストを認証するには、UI からバックエンドに対してユーザーを認証するを参照してください。

Stripe API を使用する

Stripe と対話するために、Stripe API を使用して、リクエストを認証できます。

リクエストを認証する

リクエストを認証するには、既存の加盟店アカウント API キーを使用して Stripe と対話し、ユーザーの stripeAccountId を指定します。

サーバー側での API コールでは、プラットフォームユーザーの Stripe アカウント ID (プレフィックスは acct_) とともに特殊なヘッダー Stripe-Account を使用することで、連結アカウントとしてリクエストを作成できます。下記は、プラットフォームの API シークレットキーとユーザーのアカウント ID を使用して PaymentIntent を作成する方法を示す例です。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]"=card

URL に Stripe アカウント ID を含む API リクエストのすべてで、Stripe-Account ヘッダーによる方法が必要になります。下記は、URL 内のユーザーのアカウント ID を使用してアカウントを取得する方法を示す例です。

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

また、Stripe のすべてのサーバー側ライブラリは、リクエストごとにこの方法に対応します。次に例を示します。

Stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
Stripe::Customer.create(
  {email: 'person@example.edu'},
  {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
)

# Fetching an account just needs the ID as a parameter
Stripe::Account.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}')

UI 拡張機能からセルフホスト型のバックエンドを呼び出す

UI 拡張機能からバックエンドへのリクエストを実行するときは、リクエストとともに署名を送信して、リクエストの正当性を証明します。UI 拡張機能から、現在のユーザーの stripeAccountId を渡して、ユーザーの代わりにバックエンドリクエストを実行できるようにします。

// 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');
const express = require("express");
const app = express();

app.use(express.static("public"));
app.use(express.json());

app.post("/api/data", async (req, res) => {
  const { stripeAccountId } = req.body;

  const customer = await stripe.customers.create({
    description: 'My First Test Customer (created for API docs)',
  }, {
    stripeAccount: stripeAccountId,
  });

  res.send({
    data: []
  });
});

app.listen(3000, () => console.log("Node server listening on port 3000!"));

他の API を呼び出す

セルフホスト型のバックエンドから、独自の API や他の開発者または会社が作成した API など、すべての API を呼び出すことができます。

詳細については、アプリにシークレット認証情報やトークンを保存する方法をご覧ください。

Stripe から別のサービスにユーザー情報を渡す必要がある場合は、UI 拡張機能から渡された stripeAccountId を使用します。

const express = require('express');
const fetch = require('isomorphic-fetch');
const app = express();

app.use(express.static('public'));
app.use(express.json());

app.get('/api/time', async (req, res) => {
  fetch('http://worldclockapi.com/api/json/est/now')
    .then((response) => response.json())
    .then((data) => {
      res.send({
        data: data,
      });
    });
});

app.listen(3000, () => console.log('Node server listening on port 3000!'));

UI 拡張機能からサードパーティーの API を呼び出すこともできます。

アプリに関するイベント通知を受け取る

Webhook を使用して Stripe アプリのイベント (ユーザーによるインストールやアンインストールなど) をリッスンし、次のリアクションを組み込みのバックエンドで自動的にトリガーできるようにします。

• ユーザーアカウントの作成
• 権限の更新
• ユーザーアカウントの無効化およびデータの削除

イベントを受信

アカウントのみに提供されている非公開アプリ、または App Marketplace に掲載されているアプリに関するイベントを Stripe から受け取ることができます。

加盟店がイベントをトリガーすると、Stripe によって以下のEvent (イベント) オブジェクトが提供されます。このイベントには、イベントをトリガーした加盟店のアカウント ID を指定する account プロパティーが含まれます。

{
  "id": "evt_LExHU4gZCwuHbM",
  "livemode": true,
  "object": "event",
  "type": "account.application.authorized",
  "account": "acct_eYr2yL3EVqHWqE",
  "pending_webhooks": 2,
  "created": 1349654313,
  "data": {...}
}

account 属性を使用すると、次の操作が可能になります。

• アプリをインストールした加盟店とアンインストールした加盟店の数を監視する。
• Stripe Connect を使用してユーザーの代わりに API コールを実行します。

Stripe アプリのイベント

Stripe Apps では、Stripe がサポートするイベントタイプに加えて次のイベントもサポートされます。

Event behavior depends on install mode

Your users can install apps in live mode, test mode, both modes, or a sandbox environment. Set webhooks according to the following guidelines:

• If the app is installed in a sandbox environment, events are only sent to the sandbox environment.
• If the app is installed in live mode only, live mode events are sent to the live mode endpoint.
• If the app is installed in test mode only, test mode events are sent to the test mode endpoint.
• If the app is installed in both modes, test mode events are sent to both the test mode and live mode endpoints, and live mode events are sent to the live mode endpoint.

Configure the Connect /webhook for live and test modes, then use the following snippet for both modes of the app. See the webhooks doc for a full endpoint example.

require 'sinatra'
require 'json'

post '/webhook' do
  event = JSON.parse(request.body.read)

  if event['livemode']
    puts "Handling live event: #{event}"
    # Handle live events
    handle_live_event(event)
  else
    puts "Handling test event: #{event}"
    # Handle test events
    handle_test_event(event)
  end

  status 200
  body 'Event received'
end

Troubleshooting

If you don’t receive expected events, review your configuration for the following common oversights:

• Make sure live mode webhooks use live mode keys and test mode webhooks use test mode keys.
• For live mode events, make sure the installing account is activated.
• Make sure that your app can handle both live mode & test mode events.
• Triggering test events doesn’t replicate live event behavior unless explicitly set up in the app configuration.

Webhook をローカルでテストする

次を対象に、Webhook をローカルでテストできます。

• 貴社のアカウントのすべてのユーザーのみが入手でき、そのアカウント自体のイベントをリッスンするアプリ
• Stripe App Marketplace で入手でき、貴社のアプリをインストールしたアカウントのイベントをリッスンするアプリ

Webhook をローカルでテストするには次のようにします。

1. Stripe CLI をインストールします。

2. 次のようにアカウントを認証します。

   Command Line

   stripe login

3. 端末ウィンドウを 2 つ開きます。

   • ある端末ウィンドウで、イベント転送を設定します。

     貴社のアカウントのみの非公開アプリ

     App Marketplace でのリスト公開

     Command Line

     stripe listen --forward-to localhost:{{PORT}}/webhook

   • 別の端末ウィンドウで、イベントをトリガーして Webhook との連携をテストします。

     貴社のアカウントのみの非公開アプリ

     App Marketplace でのリスト公開

     Command Line

     stripe trigger {{EVENT_NAME}}

詳細については、Webhook エンドポイントのテストに関する Stripe ドキュメントをご覧ください。