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_onboarding 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": "bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk",
    "manufacturerSerialNumber": "SN-SUNMI-00123",
    "manufacturer": "sunmi",
    "model": "p2_se"
  }'

Field	Type	Description
merchantId	string (optional)	The ID of the merchant to which the terminal is allocated.
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
externalReference	string (optional)	A unique reference for the terminal
prefix	string (optional)	An optional prefix for the auto-generated terminal ID (TID)

Registration Only

A terminal can be registered without being allocated to a merchant by omitting the merchantId field from the request. See Terminal Allocation for an example allocation request.

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": "bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk",
  "manufacturerSerialNumber": "SN-SUNMI-00123",
  "manufacturer": "sunmi",
  "model": "p2_se",
  "tid": "EP0001",
  "status": "active"
}

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/dGVybWluYWwvZTY1NjhkZGQtMzY3Ni00NmY1LTgyYWYtOTQ0ZWMxMjQyMTlj' \
  -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.
tid	A unique terminal ID assigned by Stitch
manufacturer	The terminal manufacturer
merchantId	The terminal allocation merchant's resource identifier
model	The terminal model name
serialNumber	The terminal serial number
externalReference	The terminal's unique reference

Query Paging

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

Terminal Allocation

Initiate a PUT request to allocate a terminal to a merchant. Note that a terminal that has an existing allocation must first be deallocated before being re-assigned to a merchant.

curl -X PUT https://api.stitch.money/v2/terminals/dGVybWluYWwvZTY1NjhkZGQtMzY3Ni00NmY1LTgyYWYtOTQ0ZWMxMjQyMTlj/allocate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "merchantId": "bWVyY2hhbnQvNmM3OWVlZGEtY2E3Zi00ZDIwLThhNTgtN2JhYWI3MGY1ZTBk"
  }'

Field	Type	Description
merchantId	string	The ID of the merchant for terminal allocation.

The response object is identical in structure to those returned by the POST and GET operations.

Terminal Deallocation

Initiate a PUT request to deallocate a terminal from a merchant. A terminal that is not allocated has status unallocated.

curl -X PUT https://api.stitch.money/v2/terminals/dGVybWluYWwvZTY1NjhkZGQtMzY3Ni00NmY1LTgyYWYtOTQ0ZWMxMjQyMTlj/deallocate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response object is identical in structure to those returned by the POST and GET operations.

Terminal Management

Initiate a PATCH request to update a terminal, including option to suspend or re-activate a terminal. Note that all fields are optional.

curl -X PATCH https://api.stitch.money/v2/terminals/dGVybWluYWwvZTY1NjhkZGQtMzY3Ni00NmY1LTgyYWYtOTQ0ZWMxMjQyMTlj \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "status": "suspended"
  }'

Field	Type	Description
status	string	Possible values: active, suspended.
statusReason	string	Possible values: damaged, stolen, lost, fraudulent, outstanding_compliance, outstanding_debt, merchant_left, other

The response object is identical in structure to those returned by the POST and GET operations.

Terminal Decommissioning

Initiate a DELETE request to delete a registered terminal by ID:

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

Response Handling

Note that a DELETE request does not return a response body. Use the HTTP status code to determine the result of the operation.

Deletion

Terminal deletion is irrevocable. If a terminal is decommissioned in error, a new terminal must be registered.

Testing

Responses can be simulated using terminal ID dGVybWluYWwvMzI5YzQ3MmMtMjlhMS00OWZiLWJlYzgtMzQ5MzY2ODQzN2Qz for Terminal Retrieval, Allocation, Deallocation, Management and Decommissioning APIs and serial number SNSTITCH for Registration API. Note that this is only applicable to test clients.