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

AttributeDetails
API NameChange Terminal Status
HTTP MethodPUT
Endpoint/api/v1/tms/terminals/change-terminal-status
Access LevelsSUPER_ADMIN, PARTNER, MERCHANT
Content-Typeapplication/json
AuthenticationAPI Key (X-API-KEY)
Success Response200 OK
Error Response400 Bad Request

3. Base URL

Production

https://app-api.edfapay.com

Full Endpoint

PUT https://app-api.edfapay.com/api/v1/tms/terminals/change-terminal-status

4. Authorization

This endpoint supports the following access levels:

  • SUPER_ADMIN
  • PARTNER
  • MERCHANT

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

HeaderTypeRequiredDescription
X-API-KEYStringYesAPI key used to authenticate the request.
Content-TypeStringYesapplication/json
AcceptStringRecommended*/*, 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

ParameterTypeRequiredDescription
trsmStringYesTerminal identifier used to identify the terminal whose status will be changed.
terminalStatusStringYesTarget status of the terminal. Allowed values are ACTIVE and DISABLED.

Allowed Status Values

ValueDescription
ACTIVERequests activation of the terminal.
DISABLEDRequests 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_KEY with a valid API key.
  • Replace TERMINAL_IDENTIFIER with the actual terminal identifier.
  • Use the appropriate base URL for the target environment.
  • Do not use Authorization: Bearer for 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

FieldTypeDescription
codeNumberApplication-level response code.
messageStringResponse message.
errorCodeStringApplication error identifier, where applicable.
dataObjectTerminal information returned by the API.
data.idUUIDUnique terminal record identifier.
data.trsmStringTerminal identifier.
data.providerTidStringTerminal identifier associated with the payment provider.
data.providerMidStringMerchant identifier associated with the payment provider.
data.deviceIdUUIDDevice identifier.
data.deviceModelStringDevice model.
data.statusStringTerminal status.
data.displayStatusStringDisplay-oriented terminal status.
data.businessUnitIdUUIDAssociated business unit identifier.
data.deletedBooleanIndicates whether the terminal record is marked as deleted.
data.terminalTypeStringTerminal type, such as SDK.
data.latitudeNumberTerminal latitude.
data.longitudeNumberTerminal longitude.
data.terminalSerialNumberStringTerminal serial number.
data.registeredBooleanIndicates whether the terminal is registered.
data.activeBooleanIndicates whether the terminal is active.
data.tmsVersionStringTerminal Management System version.
data.merchantNameStringAssociated merchant name.
data.merchantIdUUIDAssociated merchant identifier.
data.tmsUpdateRequiredBooleanIndicates whether a TMS update is required.
data.createdByStringRecord creator.
data.createdAtDate-timeRecord creation timestamp.
data.updatedByStringLast record updater.
data.updatedAtDate-timeLast record update timestamp.
data.lastTransactionCreatedAtDate-timeTimestamp of the last transaction creation.
data.lastDownloadParametersUpdatedAtDate-timeTimestamp of the last download-parameter update.
data.reconciliationTimeStringReconciliation time information.
data.holderAccountStringHolder 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

  1. Verify that trsm is provided and identifies the intended terminal.
  2. Ensure terminalStatus is either ACTIVE or DISABLED.
  3. Confirm that the request body contains valid JSON.
  4. Verify that the API key is valid and the caller has the required access level.
  5. Inspect the returned message and errorCode for details of the failure.

The Swagger documentation does not specify the complete set of application-level error codes.

10. Integration Workflow

  1. Obtain a valid API key for the target environment.
  2. Retrieve the terminal's trsm identifier.
  3. Set terminalStatus to ACTIVE or DISABLED.
  4. Submit the PUT request with the required JSON payload and X-API-KEY header.
  5. Inspect the HTTP status and response body.
  6. Verify the resulting terminal status when required by the integration.

11. Important Considerations

  • Access control: The documented access levels are SUPER_ADMIN, PARTNER, and MERCHANT.
  • Allowed statuses: Only ACTIVE and DISABLED are documented as accepted values.
  • Terminal identifier: The request body must contain the trsm field.
  • 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.

Did this page help you?