Using Terminal with Connect Beta

    Integrate Stripe Terminal with your Connect platform.

    Stripe Terminal is built to work well with Stripe Connect, the payments platform for marketplaces. Some of Terminal’s features are specifically for Connect users.

    As a platform, you can order and distribute readers to all of your connected accounts but manage them from a single platform account. Empower your connected accounts to take in-person payments on your platform, using the same underlying Connect data model you already know.

    If you want to reuse readers, you can switch between Stripe accounts on the same reader. Switching accounts can be useful—for example, if one connected account no longer needs a reader but another wants to try taking in-person payments, just connect the reader to the new connected account instead.

    Finally, the way Terminal creates Connect charges depends on whether you use direct charges or destination charges. If you use direct charges, all Terminal API objects are tied to connected accounts from the start. If you use destination charges, all Terminal API objects are tied to your platform account, and you can use locations to group readers as you see fit.

    Direct charges

    With direct charges, API objects are associated with the connected account rather than the platform. The connected account creates the charge objects, and it’s responsible for the cost of Stripe fees, refunds, and chargebacks.

    If you use direct charges in your Connect integration, use this section to learn how to create connection tokens, create locations, and register readers for connected accounts.

    By default, your Terminal integration with Connect follows the direct charge model. The reader and location objects are tied to connected accounts. In the Dashboard, this model makes it easy to view your Terminal data by connected account—which ones have which readers, their locations, and more.

    Creating PaymentIntents

    To perform a direct charge, provide the connected account’s ID while creating the PaymentIntent:

    curl https://api.stripe.com/v1/payment_intents \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d amount=1099 \
      -d currency=usd \
      -d payment_method_types[]=card_present \
      -d capture_method=manual \
      -H "Stripe-Account: {CONNECTED_ACCOUNT_ID}"
    

    Creating connection tokens

    When creating a connection token for the Terminal SDK, set Stripe-Account header to the connected account using the SDK.

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

    Adding locations

    To create a location for a connected account, use the Stripe-Account header.

    curl https://api.stripe.com/v1/terminal/locations \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d display_name=HQ \
      -H "Stripe-Account: {CONNECTED_ACCOUNT_ID}"
    

    Registering readers

    To register a reader to a connected account, use Stripe-Account header. If a location is not specified, Stripe assigns the reader to the connected account’s default location.

    curl https://api.stripe.com/v1/terminal/readers \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d registration_code="{REGISTRATION_CODE}" \
      -d label="Test Reader" \
      -d location="{LOCATION_ID}" \
      -H "Stripe-Account: {CONNECTED_ACCOUNT_ID}"
    

    Destination charges

    Another approach is a destination charge, where objects belonging to your connected accounts are created on your platform account. Each payment creates a transfer to a connected account automatically, setting the connected account as the settlement merchant.

    If you use destination charges in your Connect integration, use this section to learn how to group API objects by connected account, create connection tokens, create locations, and register readers.

    Creating PaymentIntents

    To use destination charges, provide on_behalf_of and transfer_data[destination] while creating the PaymentIntent:

    curl https://api.stripe.com/v1/payment_intents \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d amount=1099 \
      -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}"
    

    For transfer_data[destination], put the ID of the connected account that should receive the transfer.

    The on_behalf_of parameter is the ID of the connected account that will become the settlement merchant for the payment. 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)

    Finally, you may withhold an application fee by providing the application_fee_amount parameter.

    Grouping objects by connected account

    With destination charges, payment objects get created on your platform account, and then funds get transferred to the correct connected account. Similarly, Terminal API objects get created on your platform account, even though they belong to connected accounts.

    Because the Terminal API objects live on the platform, the best way to group reader objects is by assigning them to locations.

    To assign a reader to a location, specify the location parameter when registering the reader. If not specified, Stripe assigns the reader to your platform’s default location.

    curl https://api.stripe.com/v1/terminal/readers \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d registration_code="{REGISTRATION_CODE" \
      -d label="Test Reader" \
      -d location="{LOCATION_ID}"
    

    Next steps

    Congratulations! Your Connect platform is now set up to accept in-person payments with Terminal. Next, configure the customer-facing checkout experience in your app, or test your current integration with a physical reader.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page