Connect で Terminal を使用

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

The way Terminal creates API objects depends on whether you use direct charges or destination charges. If you use direct charges, all payment-related Terminal API objects belong to connected accounts while readers might belong to either the connected account or the platform. If you use destination charges, all Terminal API objects are created on your platform account. In both cases, use Locations to group readers as you see fit.

ダイレクト支払い

Connected accounts own readers

With this integration, all API resources belong to the connected account rather than the platform. The connected account is responsible for the cost of Stripe fees, refunds, and chargebacks.

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

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

Create Terminal API objects like Locations and Readers that belong to the same connected account which owns the payment.

To create a Location belonging to a connected account, use the Stripe-Account header.

curl https://api.stripe.com/v1/terminal/locations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d amount=1000 \
  -d currency=usd \
  -d "payment_method_types[]"=card_present \
  -d capture_method=manual

Platform owns readers

With this integration, device management resources like Locations and Readers belong to the platform account while payment resources like PaymentIntents belong to the connected account. This allows a single reader managed by the platform to process payments for multiple different connected accounts. The connected account is responsible for the cost of Stripe fees, refunds, and chargebacks.

In the Dashboard, you can view your Terminal device management data directly when logged into your platform account. You can view payment data by logging in as the connected account.

Create locations and readers

The best way to group Reader objects by connected account is by assigning them to Locations. On your platform account, create a Location for a connected account using a display name that identifies the account.

curl https://api.stripe.com/v1/terminal/locations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

Create PaymentIntents

When creating a PaymentIntent for direct charges, set the Stripe-Account header to the connected account.

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

Process PaymentIntents

The platform can process the connected account’s PaymentIntent with the platform-owned reader.

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

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

When using destination charges, API resources like PaymentIntents and Locations belong to your platform account. Each payment creates a transfer to a connected account automatically.

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

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

The best way to group Reader objects by connected account is by assigning them to Locations. On your platform account, create a Location for a connected account using a display name that identifies the account.

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