Terminals, Locations, and Routing
Payments use the authenticated merchant's active location. That location links to a boarded terminal, which identifies the processor configuration and processor credentials used for the payment.
Keep the Identifiers Distinct
| Identifier | Meaning |
|---|---|
account_id |
The merchant account that owns the configuration and payment. |
processor_config_id |
A processor configuration assigned to the account in this environment. |
terminal_id |
The Koard ID returned when boarding a terminal. |
location_id |
The Koard location ID selected in the SDK. |
| MID/TID and other VAR-sheet identifiers | Processor-assigned routing credentials. Preserve their leading zeros. |
The physical phone is the reader device. A boarded Koard terminal contains processor routing data; an Apple reader terminal profile controls reader behavior. These are different concepts.
Provision in Order
- Create the merchant account and select an available processor configuration.
- Board a terminal with
POST /v2/terminals, that merchant'saccount_id, and the processor's required fields. Store the returnedterminal_id. - Create a location with
POST /v1/locationson the same merchant and link the terminal usingterminal_id. Store the returned locationid. - Issue merchant SDK credentials, authenticate in the app, and load that merchant's locations.
- Let the operator choose the active location in settings. Pass its location ID to the SDK, then complete platform readiness.
The Merchant Setup via API provides the complete request sequence. Use the processor boarding contract and Locations API reference for the field details.
Active Location in App Settings
Include an active-location selector in your app's settings and show the selection on the payment screen. Validate that the location belongs to the authenticated merchant and has a usable linked terminal before taking payments.
- On iOS, select it with
setActiveLocationID(location.id), then follow the linking and reader preparation flow. - On Android, use the suspending
setActiveLocation(location.id), complete enrollment when needed, and check readiness before starting a reader session.
Use the full iOS or Android implementation. Do not replace a location ID with a terminal ID, silently choose the first location, or reuse another merchant's saved selection.
Changes and Merchant Switching
To change a location's linked terminal, update terminal_id through PUT /v1/locations/{location_id}. To edit a boarded terminal, follow Terminal Updates and the processor's guide.
After a routing change, reload the location/configuration and complete the SDK readiness flow before accepting another payment. Block new payments during the change.
After switching merchants, clear the app's selected location, authenticate the new merchant, and reload its locations. Android enrollment has a separate lifecycle: changing to a different merchant requires the documented unenrollment flow before enrolling again. See Android SDK Lifecycle.
Verify Routing
Before the first test payment, confirm the environment, merchant, location, linked terminal, and processor configuration in the dashboard. After the payment, reconcile its status, amount, and identifiers with the app's order. See Outcome Recovery if the response is missing.
