Terminals

Terminals for in-person card payments can be registered and allocated to merchants once onboarding is complete. Each terminal is assigned a unique Terminal ID (TID).

Integration Overview

Follow the steps described in the client token guide to obtain a client token with the client_merchant_manage scope.

The Stitch REST API URL https://api.stitch.money/v2/terminals can be used for all terminal management requests.

Terminal Registration

Initiate a POST request to the https://api.stitch.money/v2/terminals URL to register and allocate a terminal. Set the Content-Type header to application/json. Note that the merchantId references the Stitch resource identifier and not the assigned MID.

Terminal Allocation

Multiple terminals can be allocated to a single registered merchant. A terminal cannot be allocated to multiple merchants. Each payment terminal serial number must be unique.

curl -X POST https://api.stitch.money/v2/terminals \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "merchantId": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM=",
    "manufacturerSerialNumber": "SN-SUNMI-00123",
    "manufacturer": "sunmi",
    "model": "p2_se"
  }'

Field	Type	Description
merchantId	string	The ID of the merchant to whom the terminal is assigned.
manufacturerSerialNumber	string	The serial number assigned to the terminal by the manufacturer. Must be unique per device.
manufacturer	string	The hardware vendor. Possible values: sunmi.
model	string	The payment terminal model

Supported Vendors

Manufacturer	Models
sunmi	p2_se, p2_mini, p2_lite_se

The response contains the generated Terminal ID (TID) in the tid field.

{
  "id": "dGVybWluYWwvZTY1NjhkZGQtMzY3Ni00NmY1LTgyYWYtOTQ0ZWMxMjQyMTlj",
  "merchantId": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM=",
  "manufacturerSerialNumber": "SN-SUNMI-00123",
  "manufacturer": "sunmi",
  "model": "p2_se",
  "tid": "EP0001"
}

Stitch returns an error response in the following format if the terminal is not registered successfully:

{
  "title": "Internal Server Error",
  "code": "INTERNAL_SERVER_ERROR",
  "detail": "Failed to create terminal. Please try again later"
}

Terminal Retrieval

Initiate a GET request to retrieve a specific terminal by ID:

curl -X GET 'https://api.stitch.money/v2/terminals/bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk=' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

The response includes a data field containing an array of terminal objects that match the specified filters.

Retrieval is paginated and supports the offset and limit query parameters to control result size and pagination. The default page size is 2000. A paginated query example is indicated below:

curl -X GET 'https://api.stitch.money/v2/terminals?limit=50&offset=100' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Query Parameters

Parameter	Description
offset	The number of records to skip before starting to return results. Used for pagination.
limit	The maximum number of records to return in the response. Used to control page size.
manufacturer	The terminal manufacturer
model	The terminal model name

Query Paging

The default page size is 2000. Use the limit field to reduce the number of records returned in a single response.