インストールリンクを使用するベータ

アプリのマニフェストで allowed_redirect_uris を設定します。これは、ユーザーがアプリをインストールした後にリダイレクトされる URL です。すべてのリダイレクト URL をアプリの設定で指定する必要があります。

allowed_redirect_uris を設定した後、アプリの新しいバージョンをアップロードします。

{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "app_backend": {},
  "ui_extension": {},
  "allowed_redirect_uris": [
    "https://example.com/callback/stripe"
  ]
}

以下の手順で外部テストを実施することで、提出して審査を受ける前にインストールリンクをテストすることができます。

1. アプリのマニフェストで定義されている allowed_redirect_uris が指定されたバージョンを使用し、アプリの外部テストを作成します。テストがすでに存在する場合は、テスト用のバージョンを必要なバージョンに更新することができます。
2. 外部テストタブには、テスト用のインストールリンクが示され、許可されたリダイレクトが表に表示されています。
3. 公開する準備ができたら、テスト用の URI と値を本番環境で使用する予定の値に置き換えて新しいバージョンをアップロードします。

テストが完了したら、以下の手順を使用してすべてのユーザーに提供することができます。

1. allowed_redirect_uris を定義するアプリの新しいバージョンを公開します。
2. 設定タブをクリックします。インストールリンクはここに表示され、コピーすることができます。リンクは次のようになります。https://marketplace.stripe.com/apps/install/link/{id}?redirect_uri=https://example.com
3. 推奨 CSRF 攻撃を防止するには、推奨の state パラメーターを追加して、値として一意のトークンを渡すことができます。Stripe は、お客様のサイトにユーザーをリダイレクトするときに、指定された state を含めます。サイトでは state パラメーターが変更されていないことを確認できます。
4. ユーザーがインストールリンクをクリックすると、Stripe は次のページを開きます。このページでは、アカウントを選択して、アプリの詳細を確認し、インストールを先に進めることができます。

インストールリンクのアカウントの選択

ユーザーは、アプリのインストール後に、アプリのマニフェストに記載された allowed_redirect_uris で定義されているリダイレクトと一致する redirect_uri URL パラメーターにリダイレクトされます。

インストールの成功

インストールが成功すると、URL に以下が含まれます。

• user_id の値。インストールを開始した Stripe ユーザーの ID。
• account_id 値。貴社のアプリをインストールした Stripe アカウントの ID。
• state 値 (指定されている場合)
• install_signature 値。これは、上記の値のハッシュであり、アプリの署名シークレットを使用して生成されます。
• アプリがテスト環境にインストールされた場合、livemode=false 値がリダイレクト URL に付加されます。

「本番環境のリダイレクトの一例:」

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}

「テスト環境のリダイレクトの一例:」

https://example.com/callback/stripe?user_id={USER_ID}&account_id={CONNECTED_ACCOUNT_ID}&state={STATE}&install_signature={INSTALL_SIGNATURE}&livemode=false

インストールの失敗

ユーザーがインストールをキャンセルした場合でも、お客様のサイトにリダイレクトされますが、URL にはエラーが含まれます。

https://example.com/callback/stripe?error=access_denied&error_description=The%20user%20denied%20your%20request

これで、ユーザーはアプリに連結されました。stripe_user_id をデータベースに保存します。これは、ユーザーの Stripe アカウント ID です。この値を Stripe-Account ヘッダーでリクエストに渡すことで、連結アカウントとして認証します。

install_signature を使用してアプリのインストールを確認する 推奨

アプリのユーザーがリダイレクト URL に入力したアカウントでアプリのインストールを承認されているかを確認することが重要です。install_signature が含まれているのはこのためです。このシグネチャーはアプリの署名シークレット、およびインストールを実行した user_id と account_id から生成されます。指定されている場合は渡された state もこのシグネチャーに含まれます。署名シークレットにアクセスせずにこのシグネチャーを複製することはできず、実行できるのは、Stripe 内部とアプリのバックエンドのみです。これにより、不正行為者がリダイレクト URL を試したり偽装しようとしても、ハッシュを複製することはできません。アプリのシグネチャーを確認することによって、アカウントがアプリのユーザーに関連付けられていることを確信できます。

シグネチャーを確認するには、以下のステップを使用します。

1. まだ作成していない場合は、アプリの署名シークレットを作成します。
2. アプリのバックエンドを設定して、install_signature を確認します。

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

The order and naming of the payload fields matter when performing signature verification. The state precedes the user_id, which precedes the account_id. The resulting object should be { state, user_id, account_id }.

require 'stripe'
require 'sinatra'
require 'json'

Stripe.api_key = 'API_KEY'

get '/' do
  'Install Links verification example'
end

get '/verify' do
  user_id = params[:user_id]
  account_id = params[:account_id]
  state = params[:state]
  install_signature = params[:install_signature]

  payload = JSON.dump({
    state: state,
    user_id: user_id,
    account_id: account_id
  })

  begin
    Stripe::Webhook::Signature.verify_header(
      payload,
      install_signature,
      'STRIPE_APP_SECRET'
    )
  rescue Stripe::SignatureVerificationError => e
    return e.message, 400
  end

  { success: true }.to_json
end

set :port, 3000

確認後は、インストールしたアカウントの代理として API コールを実行できます。

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

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:"

こちらで認証されたリクエストを行う方法の例をご覧ください。