Use Terminal with Connect

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. You can also register the reader by clicking View as in the Stripe Dashboard for your connected account.

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

curl https://api.stripe.com/v1/terminal/readers \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -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, only readers assigned to that location can use the ConnectionToken. If you dont provide a location, all readers can use the ConnectionToken.

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

If youre using a server-driven integration, you dont need to create a connection token.

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, dont 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 isnt 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_wU7nrJCZspk1NPDxiQgAF05q:" \
  -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

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.

curl https://api.stripe.com/v1/terminal/locations \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -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_wU7nrJCZspk1NPDxiQgAF05q:" \
  -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_wU7nrJCZspk1NPDxiQgAF05q:" \
  -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 accounts PaymentIntent with the platform-owned reader.

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