Terminal Status — API
Allows authorized users to activate or deactivate a terminal by setting its status to ACTIVE or DISABLED. Requires API Key authentication through the X-API-KEY header and supports SUPER_ADMIN, PARTNER, and MERCHANT access levels.
1. Overview
The Change Terminal Status API allows authorized users to activate or deactivate a terminal through the Terminal Management System (TMS).
2. Endpoint Summary
| Attribute | Details |
|---|---|
| API Name | Change Terminal Status |
| HTTP Method | PUT |
| Endpoint | /api/v1/tms/terminals/change-terminal-status |
| Access Levels | SUPER_ADMIN, PARTNER, MERCHANT |
| Content-Type | application/json |
| Authentication | API Key (X-API-KEY) |
| Success Response | 200 OK |
| Error Response | 400 Bad Request |
3. Base URL
Production
https://app-api.edfapay.comFull Endpoint
PUT https://app-api.edfapay.com/api/v1/tms/terminals/change-terminal-status4. Authorization
This endpoint supports the following access levels:
SUPER_ADMINPARTNERMERCHANT
Authentication is provided through the X-API-KEY request header. The API key must be valid and authorized to access the requested operation.
5. Request Headers
| Header | Type | Required | Description |
|---|---|---|---|
X-API-KEY | String | Yes | API key used to authenticate the request. |
Content-Type | String | Yes | application/json |
Accept | String | Recommended | */*, as shown in the Swagger response configuration. |
6. Request Body
The endpoint requires a JSON payload containing the terminal identifier and the requested status.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
trsm | String | Yes | Terminal identifier used to identify the terminal whose status will be changed. |
terminalStatus | String | Yes | Target status of the terminal. Allowed values are ACTIVE and DISABLED. |
Allowed Status Values
| Value | Description |
|---|---|
ACTIVE | Requests activation of the terminal. |
DISABLED | Requests deactivation of the terminal. |
Example Request — Activate Terminal
{
"trsm": "TERMINAL_IDENTIFIER",
"terminalStatus": "ACTIVE"
}Example Request — Deactivate Terminal
{
"trsm": "TERMINAL_IDENTIFIER",
"terminalStatus": "DISABLED"
}Replace TERMINAL_IDENTIFIER with the actual terminal identifier.
7. cURL Examples
7.1 Activate Terminal
curl --request PUT \
--url 'https://app-api.edfapay.com/api/v1/tms/terminals/change-terminal-status' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
"trsm": "TERMINAL_IDENTIFIER",
"terminalStatus": "ACTIVE"
}'7.2 Deactivate Terminal
curl --request PUT \
--url 'https://app-api.edfapay.com/api/v1/tms/terminals/change-terminal-status' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
"trsm": "TERMINAL_IDENTIFIER",
"terminalStatus": "DISABLED"
}'Implementation Notes
- Replace
YOUR_API_KEYwith a valid API key. - Replace
TERMINAL_IDENTIFIERwith the actual terminal identifier. - Use the appropriate base URL for the target environment.
- Do not use
Authorization: Bearerfor this endpoint unless a separate security configuration explicitly requires it.
8. Response Specification
8.1 HTTP 200 — OK
A successful HTTP response returns the standard application response structure along with terminal information in the data object.
Example Response
{
"code": 0,
"message": "string",
"errorCode": "string",
"data": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"trsm": "string",
"providerTid": "string",
"providerMid": "string",
"deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"deviceModel": "string",
"status": "ACTIVE",
"displayStatus": "string",
"businessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"deleted": true,
"terminalType": "SDK",
"latitude": 0,
"longitude": 0,
"terminalSerialNumber": "string",
"registered": true,
"active": true,
"tmsVersion": "string",
"merchantName": "string",
"merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tmsUpdateRequired": true,
"createdBy": "string",
"createdAt": "2026-10-28T11:54:22.177Z",
"updatedBy": "string",
"updatedAt": "2026-10-28T11:54:22.177Z",
"lastTransactionCreatedAt": "2026-10-28T11:54:22.177Z",
"lastDownloadParametersUpdatedAt": "2026-10-28T11:54:22.177Z",
"reconciliationTime": "string",
"holderAccount": "string"
}
}The response values are illustrative Swagger examples, not verified production values.
Response Fields
| Field | Type | Description |
|---|---|---|
code | Number | Application-level response code. |
message | String | Response message. |
errorCode | String | Application error identifier, where applicable. |
data | Object | Terminal information returned by the API. |
data.id | UUID | Unique terminal record identifier. |
data.trsm | String | Terminal identifier. |
data.providerTid | String | Terminal identifier associated with the payment provider. |
data.providerMid | String | Merchant identifier associated with the payment provider. |
data.deviceId | UUID | Device identifier. |
data.deviceModel | String | Device model. |
data.status | String | Terminal status. |
data.displayStatus | String | Display-oriented terminal status. |
data.businessUnitId | UUID | Associated business unit identifier. |
data.deleted | Boolean | Indicates whether the terminal record is marked as deleted. |
data.terminalType | String | Terminal type, such as SDK. |
data.latitude | Number | Terminal latitude. |
data.longitude | Number | Terminal longitude. |
data.terminalSerialNumber | String | Terminal serial number. |
data.registered | Boolean | Indicates whether the terminal is registered. |
data.active | Boolean | Indicates whether the terminal is active. |
data.tmsVersion | String | Terminal Management System version. |
data.merchantName | String | Associated merchant name. |
data.merchantId | UUID | Associated merchant identifier. |
data.tmsUpdateRequired | Boolean | Indicates whether a TMS update is required. |
data.createdBy | String | Record creator. |
data.createdAt | Date-time | Record creation timestamp. |
data.updatedBy | String | Last record updater. |
data.updatedAt | Date-time | Last record update timestamp. |
data.lastTransactionCreatedAt | Date-time | Timestamp of the last transaction creation. |
data.lastDownloadParametersUpdatedAt | Date-time | Timestamp of the last download-parameter update. |
data.reconciliationTime | String | Reconciliation time information. |
data.holderAccount | String | Holder account information. |
9. Error Handling
HTTP 400 — Bad Request
The API documents 400 Bad Request as a possible response.
{
"code": 0,
"message": "string",
"errorCode": "string",
"data": {}
}Troubleshooting Checklist
- Verify that
trsmis provided and identifies the intended terminal. - Ensure
terminalStatusis eitherACTIVEorDISABLED. - Confirm that the request body contains valid JSON.
- Verify that the API key is valid and the caller has the required access level.
- Inspect the returned
messageanderrorCodefor details of the failure.
The Swagger documentation does not specify the complete set of application-level error codes.
10. Integration Workflow
- Obtain a valid API key for the target environment.
- Retrieve the terminal's
trsmidentifier. - Set
terminalStatustoACTIVEorDISABLED. - Submit the
PUTrequest with the required JSON payload andX-API-KEYheader. - Inspect the HTTP status and response body.
- Verify the resulting terminal status when required by the integration.
11. Important Considerations
- Access control: The documented access levels are
SUPER_ADMIN,PARTNER, andMERCHANT. - Allowed statuses: Only
ACTIVEandDISABLEDare documented as accepted values. - Terminal identifier: The request body must contain the
trsmfield. - Operational impact: Deactivating a terminal may affect its availability; confirm the expected impact before changing its status.
- Response verification: Review the returned terminal data rather than relying on the HTTP status alone.
- Error handling: Capture the HTTP status, application code, message, and error identifier.
- API key security: Store API keys securely and avoid exposing them in logs or public documentation.
12. API Specification Notes
The supplied documentation establishes the endpoint, HTTP method, access levels, request fields, allowed status values, and response schema.
The following details are not established by the displayed endpoint schema:
- Additional validation rules and application-level error mappings.
- Any prerequisites or side effects of changing terminal status.
- Retry and idempotency guarantees.
- Whether downstream systems apply the status change immediately.
Updated 25 days ago