Use Terminal with Connect

Stripe Terminal is fully compatible with Connect, enabling your platform or marketplace to accept in-person payments.

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.

Direct charges

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.

In the Dashboard, you can view your Terminal data by logging in as the connected account.

Create locations and readers Server-side

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

Before you can connect your application to a smart reader, you must register the reader to a Stripe account. To register a reader to a connected account, use the Stripe-Account header.

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

Create connection tokens Server-side

When creating a ConnectionToken for the Terminal SDK, set the Stripe-Account header to the connected account accepting payments. You can also provide a location parameter to control access to readers. If you provide a location, the ConnectionToken is only usable with readers assigned to that location. If you don’t provide a location, the ConnectionToken is usable with all readers.

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

Create PaymentIntents Client-side Server-side

With the iOS, Android, and React Native SDKs, you can create a PaymentIntent on the client or server. The JavaScript SDK only supports server-side creation.

Client-side

When creating a PaymentIntent client-side for direct charges, you don’t need to specify any additional parameters for the PaymentIntent. Instead, when creating a ConnectionToken, set the Stripe-Account header to the connected account accepting payments. The client SDKs create the PaymentIntent on the same connected account the ConnectionToken belongs to. For more information, see Create PaymentIntents Client-side.

Server-side

The JavaScript SDK requires you to create the PaymentIntent on your server. For the other client SDKs, you might want to create the PaymentIntent on your server if the information required to start a payment isn’t readily available in your app. For more information, see Create PaymentIntents Server-side.

When creating a PaymentIntent server-side 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

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

Before you can connect your application to a smart reader, you must register the reader to your platform account.

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

Destination charges

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.

In the Dashboard, you can view your Terminal data directly when logged into your platform account.

Create locations and readers Server-side

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

Before you can connect your application to a smart reader, you must register the reader to your platform account.

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 connection tokens Server-side

When creating a ConnectionToken for the Terminal SDK, use your platform account’s secret key. Don’t set the Stripe-Account header. Provide a location parameter to control access to readers. If you provide a location, the ConnectionToken is only usable with readers assigned to that location. If you don’t provide a location, the ConnectionToken is usable with all readers.

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

Create PaymentIntents Client-side Server-side

When creating a PaymentIntent using destination charges, provide the on_behalf_of and transfer_data[destination], and application_fee_amount parameters.

The on_behalf_of parameter is the ID of the connected account that becomes the settlement merchant for the payment. For Terminal transactions, this parameter must be set in cases where the platform country isn’t the same as the Connect account country. When on_behalf_of is set, Stripe automatically:

• Settles charges in the country of the specified account, thereby minimizing declines and avoiding currency conversions.
• Uses the fee structure for the connected account’s country.
• Lists the connected account’s address and phone number on the customer’s credit card statement, as opposed to the platform’s address and phone number (only occurs if the account and platform are in different countries).

For transfer_data[destination], set the ID of the connected account that receives the transfer.

Finally, you can withhold an application fee for your platform by providing the application_fee_amount parameter.

Client-side

With the iOS, Android, and React Native SDKs, you can create a PaymentIntent client-side and provide the onBehalfOf, transferDataDestination, and applicationFeeAmount parameters.

Server-side

The JavaScript SDK requires you to create the PaymentIntent on your server. For the other client SDKs, you want to create the PaymentIntent on your server if the information required to start a payment isn’t readily available in your app. For more information, see Create PaymentIntents Server-side.

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