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.
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 |
externalReference | string (optional) | A unique reference for the terminal |
prefix | string (optional) | An optional prefix for the auto-generated terminal ID (TID) |
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",
"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 |
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"
}'
Field | Type | Description |
---|---|---|
status | string | Possible 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" \
Note that a DELETE
request does not return a response body. Use the HTTP status code to determine the result of the operation.
Terminal deletion is irrevocable. If a terminal is decommissioned in error, a new terminal must be registered.