Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseUse Managed Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Terminal
Beyond payments

Use Terminal with Connect

Integrate Stripe Terminal with your Connect platform.

Stripe Terminal is compatible with Connect, allowing your platform and connected accounts to accept in-person payments.

Integrate Terminal with Connect according to how your platform processes payments for your connected accounts.

  • If you use direct charges, you submit Terminal API requests to configure readers and accept payments using the connected account’s API key. Your platform can use the Stripe-Account header to identify the connected account and use its API key.
  • If you use destination charges, you submit Terminal API requests to configure readers and accept payments using your platform API key and identify the connected account using metadata.

In both cases, use Locations to group readers applicably.

Note

Terminal connected accounts must have the card_payments capability to perform transactions.

Direct charges

Connected accounts own readers

With this integration, all API resources belong to the connected account rather than your 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 Locations and Readers for connected accounts by including the Stripe-Account header in the API requests.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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}}"

Create connection tokens Server-side

Note

When using Connect OAuth authentication, you must authorize the connected account separately for live mode and sandboxes using each mode’s respective application Client ID.

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, only readers assigned to that location can use the ConnectionToken. If you don’t provide a location, all readers can use the ConnectionToken.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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, don’t specify any additional parameters for the PaymentIntent. Instead, create a ConnectionToken with the Stripe-Account header for 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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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

Then follow the steps to collect a payment to process the PaymentIntent.

Platform-owned readers Private preview

Private preview

Contact us if you’re interested in letting the platform own and manage readers with direct charges. This private preview feature is currently available for smart readers leveraging a server-driven integration. This integration works only with connected accounts that you control through a single platform.

With this integration, your platform owns device resources like Locations and Readers, and your connected accounts own payment resources like PaymentIntents. This allows your platform to manage a single reader that processes payments for multiple connected accounts. The connected accounts are 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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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}}"

Create PaymentIntents

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

Note

The platform can only process PaymentIntents later if you create them for connected accounts that you control through a single platform.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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

Process PaymentIntents

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

Note

The PaymentIntent can only be processed if you create it using the Stripe-Account header.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/terminal/readers/
{{READER_ID}}
/process_payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=
"{{PAYMENT_INTENT_ID}}"

Destination charges

When using destination charges, your platform owns API resources like PaymentIntents and Locations. 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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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}}"

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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, you must set this parameter if the platform country isn’t the same as the connected account country. When you set on_behalf_of, Stripe automatically:

  • Settles charges in the country of the specified account, 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 instead of your platform’s address and phone number on the customer’s credit card statement. (Only 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.

Note

Client-side PaymentIntent creation is possible with the other SDKs. If you’re using the JavaScript SDK for Stripe Terminal, create a PaymentIntent server-side.

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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}}"

Then follow the steps to collect a payment to process the PaymentIntent.

See also

Was this page helpful?
YesNo