Skip to main content

Terminal Management

The Stitch platform provides comprehensive terminal management capabilities that enable you to register payment terminals, associate them with merchants, and configure payment processing routes.

This section guides you through the complete terminal lifecycle: from registering a new terminal in the system, to allocating it to a merchant, to configuring which payment methods it can process.

Terminal Registration​

note

Usually the terminal manufacturer will notify Stitch when new terminals are shipped, and these terminals will already be loaded on the platform. However, you can create terminals manually for testing purposes.

Before registering a terminal, you need to identify the appropriate terminal model. The Stitch system maintains a catalog of supported terminal models from various manufacturers.

Step 1: Find the Terminal Model ID​

Use the terminal manufacturer and terminal model lookup APIs to find the appropriate terminalModelId for your device.

Step 2: Register the Terminal​

POST /v/1/terminals
{
   "manufacturerSerialNumber": "T000001",
   "externalSerialNumber": "(optional) test-terminal-1",
   "tenantId": "{{system_account_id}}",
   "terminalModelId": "{{terminal_model_id}}",
   "rkiRequired": true
}
  • manufacturerSerialNumber: The unique serial number assigned by the terminal manufacturer to the terminal.
  • externalSerialNumber: An optional identifier you can assign for your own reference.
  • tenantId: The ID of the tenant that owns this terminal.
  • terminalModelId: The ID of the terminal model (obtained from the lookup API).
  • rkiRequired: Indicates whether Remote Key Injection is required for this terminal (should be true for secure payment processing).

Terminal Allocation​

After registering a terminal, you need to allocate it to a specific merchant to enable payment processing.

Step 1: Allocate Terminal to Merchant​

POST /v/1/terminal-allocations
{
  "terminalId" : "{{terminal_id}}",
  "merchantId" : "{{merchant_id}}",
  "autoAllocateRoute" : true,
  "routeAllocationTid" : "L0000001"
}
  • terminalId: The ID of the terminal you want to allocate.
  • merchantId: The ID of the merchant who will use this terminal.
  • autoAllocateRoute: When set to true, Stitch will automatically configure the payment routes, and simplifies the setup process.
  • routeAllocationTid: The Terminal Identifier (TID) that will be used in payment processing.
tip

Setting autoAllocateRoute to true simplifies the setup process by automatically configuring the payment routes for this terminal.

note

The routeAllocationTid (Terminal Identifier) must be unique per route. If you don't provide a TID, Stitch can automatically generate one if your tenant has this feature enabled.

Step 2: Manual Route Configuration (if not using autoAllocateRoute)​

If you set autoAllocateRoute to false, you'll need to manually configure which payment methods the terminal can process. This is useful in scenarios where different payment methods (e.g., Visa vs. American Express) need to be processed through different routes.

POST /v/1/terminal-allocations-routes
{
  "terminalAllocationId": "{{terminalAllocationId}}",
  "merchantPaymentMethodRouteId": "{{merchantPaymentMethodRouteId}}",
  "tid": "{{tid}}"
}
  • terminalAllocationId: The ID returned from the terminal allocation request.
  • merchantPaymentMethodRouteId: Identifies which payment method route this terminal should use.
  • tid: The Terminal Identifier for this specific route.
note

To find the appropriate merchantPaymentMethodRouteId, you can search the available merchant payment methods using the API call listed below.