Skip to main content

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": "ZmlsZS83ZDRiMGNmYi0xMDBhLTRkMjUtYWViYy0zN2YyOWEwZDA3NTM=",
"manufacturerSerialNumber": "SN-SUNMI-00123",
"manufacturer": "sunmi",
"model": "p2_se"
}'
FieldTypeDescription
merchantIdstringThe ID of the merchant to whom the terminal is assigned.
manufacturerSerialNumberstringThe serial number assigned to the terminal by the manufacturer. Must be unique per device.
manufacturerstringThe hardware vendor. Possible values: sunmi.
modelstringThe payment terminal model
externalReferencestring (optional)A unique reference for the terminal
prefixstring (optional)An optional prefix for the auto-generated terminal ID (TID)

Supported Vendors

ManufacturerModels
sunmip2_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",
"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

ParameterDescription
offsetThe number of records to skip before starting to return results. Used for pagination.
limitThe maximum number of records to return in the response. Used to control page size.
tidA unique terminal ID assigned by Stitch
manufacturerThe terminal manufacturer
merchantIdThe terminal allocation merchant's resource identifier
modelThe terminal model name
serialNumberThe terminal serial number
Query Paging

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

Terminal Management

Initiate a PATCH request to suspend or re-activate a terminal.

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

FieldTypeDescription
statusstringPossible values: active, suspended.

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.