Connect で Terminal を使用

Stripe Terminal は、Connect と全面的に互換性があり、プラットフォームやマーケットプレイスで対面支払いを受け付けられるようにします。

Terminal が API オブジェクトを作成する方法は、ダイレクト支払いとデスティネーション支払いのどちらを使用するかによって異なります。ダイレクト支払いを使用する場合、支払い関連の Terminal API オブジェクトはすべて連結アカウントに属し、リーダーは連結アカウントまたはプラットフォームのいずれかに属します。デスティネーション支払いを使用する場合、Terminal API オブジェクトはすべてプラットフォームアカウントに作成されます。どちらの場合も、Location (場所) を使用してリーダーを最適にグループ化します。

ダイレクト支払い

連結アカウントがリーダーを所有

この導入では、すべての API リソースはプラットフォームではなく連結アカウントに属します。連結アカウントが、Stripe の手数料、返金、チャージバックのコストに責任を負います。

ダッシュボードに連結アカウントとしてログインすると、Terminal データを表示することができます。

場所とリーダーの作成 サーバー側

支払いを所有する同じ連結アカウントに属する Locations や Readers などの Terminal API オブジェクトを作成します。

連結アカウントに属する Location を作成するには、Stripe-Account ヘッダーを使用します。

curl https://api.stripe.com/v1/terminal/locations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d display_name=HQ \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"=CA \
  -d "address[country]"=US \
  -d "address[postal_code]"=94110

アプリケーションをスマートリーダーに接続するには、リーダーを Stripe アカウントに登録する必要があります。連結アカウントにリーダーを登録するには、Stripe-Account ヘッダーを使用します。

curl https://api.stripe.com/v1/terminal/readers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

接続トークンの作成 サーバー側

Terminal SDK の ConnectionToken を作成するときは、Stripe-Account ヘッダーで、支払いを受け付ける連結アカウントを設定します。リーダーのアクセスを制御するために、location パラメーターを指定することもできます。場所を指定すると、ConnectionToken はその場所に割り当てられたリーダーでのみ利用可能になります。場所を指定しないと、ConnectionToken はすべてのリーダーで利用可能になります。

curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d location=
{{LOCATION_ID}}

PaymentIntents を作成する クライアント側 サーバー側

iOS、Android、React Native の SDK を使用すると、クライアントまたはサーバーで PaymentIntent を作成できます。JavaScript SDK は、サーバー側の作成のみに対応しています。

クライアント側

クライアント側でダイレクト支払い用の PaymentIntent を作成するときに、PaymentIntent に追加のパラメーターを指定する必要はありません。その代わり、ConnectionToken を作成するときに、Stripe-Account ヘッダーで決済を受け付ける連結アカウントを設定します。クライアントの SDK では、ConnectionToken が属する同じ連結アカウントで PaymentIntent を作成します。詳細については、PaymentIntents を作成する (クライアント側) をご覧ください。

サーバー側

JavaScript SDK では、サーバー上で PaymentIntent を作成する必要があります。他のクライアントの SDK で、支払いの開始に必要な情報をアプリですぐに利用できない場合には、サーバー上に PaymentIntent を作成することをお勧めします。詳細については、PaymentIntents を作成する (サーバー側) をご覧ください。

サーバー側でダイレクト支払い用の PaymentIntent を作成するときは、Stripe-Account ヘッダーに連結アカウントを設定します。

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_present \
  -d capture_method=manual

プラットフォームがリーダーを所有

この導入では、Locations や Readers などのデバイス管理リソースはプラットフォームアカウントに属し、PaymentIntents などの支払いリソースは連結アカウントに属します。これにより、プラットフォームが管理する単一のリーダーで複数の異なる連結アカウントの支払いを処理できます。連結アカウントは、Stripe 手数料、返金、チャージバックのコストに対して責任を負います。

ダッシュボードでは、プラットフォームアカウントにログインしているときに Terminal デバイス管理データを直接表示できます。連結アカウントとしてログインすることで、支払いデータを表示できます。

場所とリーダーを作成

連結アカウント別に Reader オブジェクトをグループ化するための最適な方法は、オブジェクトを Locations に割り当てることです。プラットフォームアカウントで、アカウントを識別する表示名を使用して、連結アカウントの Location を作成します。

curl https://api.stripe.com/v1/terminal/locations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d display_name=HQ \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"=CA \
  -d "address[country]"=US \
  -d "address[postal_code]"=94110

アプリケーションをスマートリーダーに接続するには、事前にリーダーをプラットフォームアカウントに登録しておく必要があります。

curl https://api.stripe.com/v1/terminal/readers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

PaymentIntent を作成する

ダイレクト支払い用の PaymentIntent を作成するときは、Stripe-Account ヘッダーに連結アカウントを設定します。

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_present \
  -d capture_method=manual

PaymentIntents を処理する

プラットフォームは、プラットフォームが所有するリーダーを使用して、連結アカウントの PaymentIntent を処理できます。

curl https://api.stripe.com/v1/terminal/readers/
{{READER_ID}}
/process_payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=
{{PAYMENT_INTENT_ID}}

デスティネーション支払い

デスティネーション支払いを使用すると、PaymentIntents や Locations などの API リソースは、プラットフォームアカウントに属します。支払いごとに、連結アカウントへの送金の作成が自動的に行われます。

ダッシュボードにプラットフォームアカウントでログインすると、Terminal データを直接表示することができます。

場所とリーダーの作成 サーバー側

連結アカウント別に Reader オブジェクトをグループ化するための最適な方法は、オブジェクトを Locations に割り当てることです。プラットフォームアカウントで、アカウントを識別する表示名を使用して、連結アカウントの Location を作成します。

curl https://api.stripe.com/v1/terminal/locations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d display_name=HQ \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"=CA \
  -d "address[country]"=US \
  -d "address[postal_code]"=94110

アプリケーションをスマートリーダーに接続するには、事前にリーダーをプラットフォームアカウントに登録しておく必要があります。

curl https://api.stripe.com/v1/terminal/readers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

接続トークンの作成 サーバー側

Terminal SDK の ConnectionToken を作成するときは、プラットフォームアカウントのシークレットキーを使用します。Stripe-Account ヘッダーは設定しないでください。リーダーへのアクセスを制御するには、location パラメーターを指定します。場所を指定すると、ConnectionToken はその場所に割り当てられたリーダーでのみ利用可能になります。場所を指定しないと、ConnectionToken はすべてのリーダーで利用可能になります。

curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d location=
{{LOCATION_ID}}

PaymentIntents を作成する クライアント側 サーバー側

デスティネーション支払いを使用して PaymentIntent を作成するときは、on_behalf_of、transfer_data[destination]、application_fee_amount の各パラメーターを指定します。

on_behalf_of パラメーターは、支払いの売上処理加盟店となる連結アカウントの ID です。Terminal の取引では、プラットフォームの国と Connect アカウントの国が異なる場合、このパラメーターは必ず設定する必要があります。on_behalf_of が設定されていると、Stripe は自動的に次のように動作します。

• 指定されたアカウントの国で売上を処理することで、支払い拒否を最小限に抑え、通貨換算を回避します。
• 連結アカウントの国の手数料体系を使用します。
• 顧客のクレジットカード明細書に、プラットフォームの住所と電話番号ではなく、連結アカウントの住所と電話番号を記載します (アカウントとプラットフォームの国が異なる場合のみ)。

transfer_data[destination] には、送金を受け取る連結アカウントの ID を設定します。

最後に、application_fee_amount パラメーターを指定することによって、プラットフォーム手数料を差し引くことができます。

クライアント側

iOS、Android、React Native の SDK では、クライアント側で PaymentIntent を作成して、onBehalfOf、transferDataDestination、applicationFeeAmount の各パラメーターを指定できます。

サーバー側

JavaScript SDK では、サーバー上で PaymentIntent を作成する必要があります。他のクライアントの SDK で、支払いの開始に必要な情報をアプリですぐに利用できない場合には、サーバー上に PaymentIntent を作成することをお勧めします。詳細については、PaymentIntents を作成する (サーバー側) をご覧ください。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]"=card_present \
  -d capture_method=manual \
  -d application_fee_amount=200 \
  -d on_behalf_of=
{{CONNECTED_ACCOUNT_ID}} \
  -d "transfer_data[destination]"=
{{CONNECTED_ACCOUNT_ID}}