If your Terminal deployment uses many readers across multiple physical locations, keeping track of them all can get overwhelming. Locations help you manage readers and their activity by associating them with a physical operating site. They also ensure your readers download the proper regional configurations.
Use the Terminal Locations object to group readers, view their connectivity status, and customize their settings by physical location. This can be especially helpful for marketplaces with many connected accounts.
After creating Locations, you can use them to help you group readers, improve reader discovery flows, customize their settings by physical location, and more.
Create a location Server-side Dashboard
Create a Location for each physical location that your readers operate at. If your business requires you to move your readers frequently, your locations may use addresses that represent a primary place of business.
To create a new location using the API, use the create location request.
A Location’s required address properties differ based on country:
|Countries||Required Address Properties|
Create a location with Standard Connect
In order to create a location for a Standard Connect Account, use the
Stripe-Account header in your request. These locations are only accessible by the Connect account you authenticate as. You can create multiple locations for any individual Standard Connect account, if the merchant operates in multiple physical sites.
Create a location with Custom Connect
For Custom Connect integrations, locations belong to the platform account and are not mapped strictly to Connect accounts. If your platform needs to associate Custom Connect accounts with locations, you can store a reference to the relevant account(s) in the location’s metadata property.
You can also create locations from the Stripe Dashboard, under Locations.
When you register your reader to a location, the specified location groups the reader and defines its country settings.
Scope connection tokens Server-side Smart readers
When creating a ConnectionToken for the Terminal SDK, you may provide a
location parameter to control access to smart readers. If you provide a location, the ConnectionToken is only usable with smart readers assigned to that location. If you don’t provide a location, the ConnectionToken is usable with all readers.
For Bluetooth readers, the
location of a ConnectionToken has no effect. This ensures that Bluetooth readers near you are always discoverable.
Register a reader to a location
You must register your reader to a location in order to accept payments. The process for registering your reader to a location differs based on whether it’s an smart reader or a Bluetooth reader.
Smart readers Server-side
Register smart readers (Verifone P400 and BBPOS WisePOS E) to a location during reader registration.
You can also register readers in the Dashboard, under Locations.
Bluetooth readers Client-side
Register Bluetooth readers (Stripe Reader M2, BBPOS Chipper 2X BT, and BBPOS WisePad 3) to a location while connecting to the reader by specifying the
locationId in your
BluetoothConnectionConfiguration. If you’d like, you can register the reader to the last used location by passing in the
reader.locationId from a discovered reader.
Terminal SDK versions prior to v2.0.0 don’t support registering BBPOS Chipper 2X BT or WisePad 3 readers to locations.
Filter discovered readers
Smart readers Client-side
Your application uses the SDK’s
discoverReaders method to look for readers it can connect to. When discovering a smart reader like the Verifone P400 or BBPOS WisePOS E, you can discover the intended reader more easily by filtering results by location.
With the code below, only readers in a given location are returned to your app’s callback. You can find the location’s ID in the Dashboard, under Locations.
Bluetooth readers Client Side
Because mobile readers use Bluetooth for connection,
discoverReaders returns all nearby readers. No additional filtering is applied by default. However, you can use the returned
registeredLocation parameter on the Reader object to optionally apply additional filtering in your application.