Get Terminal Details — API

Retrieves detailed information for a specified terminal using its terminalId UUID. Returns card scheme configurations, merchant information, and terminal features with their activation status. Accessible to SUPER_ADMIN, PARTNER, and MERCHANT roles using API Key authentication through the X-API-KEY header.

1. Overview

The Get Terminal Details API retrieves detailed information for a specific terminal using its unique terminal ID. The response includes card scheme configurations, merchant information, and terminal features with their activation status.

Access Levels: SUPER_ADMIN, PARTNER, MERCHANT

2. Endpoint Details

PropertyValue
API NameGet Terminal Details
HTTP MethodGET
Endpoint/api/v1/tms/terminals/terminal-detail/{terminalId}
Access LevelsSUPER_ADMIN, PARTNER, MERCHANT
Request BodyNone
Success Response200 OK
Error Response400 Bad Request

3. Base URL

Production

https://app-api.edfapay.com

Full Endpoint

GET https://app-api.edfapay.com/api/v1/tms/terminals/terminal-detail/{terminalId}

4. Authorization

This endpoint is available to the following access levels:

  • SUPER_ADMIN
  • PARTNER
  • MERCHANT

Authentication uses an API key supplied through the X-API-KEY request header.

5. Path Parameters

ParameterTypeRequiredDescription
terminalIdUUIDYesUnique identifier of the terminal whose details are requested.

Example

/api/v1/tms/terminals/terminal-detail/3fa85f64-5717-4562-b3fc-2c963f66afa6

Replace the example UUID with the actual terminal ID.

6. Request Headers

HeaderValueDescription
X-API-KEYYOUR_API_KEYAuthenticates the API request.
Accept*/*Specifies the response media types accepted by the client.

No request body or query parameters are specified in the provided API definition.

7. cURL Example

curl --request GET \
  --url 'https://app-api.edfapay.com/api/v1/tms/terminals/terminal-detail/TERMINAL_UUID' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Accept: */*'

Implementation notes:

  • Replace TERMINAL_UUID with the actual terminal UUID.
  • Replace YOUR_API_KEY with a valid API key.
  • This endpoint retrieves terminal details and does not modify the terminal configuration.

8. Successful Response — 200 OK

Example Response

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {
    "cardSchemes": [
      {
        "cardSchemeId": "string",
        "cardSchemeNameAr": "string",
        "cardSchemeNameEn": "string",
        "cardSchemeAcquirerId": "string",
        "enableEmv": "string",
        "checkServiceCode": "string",
        "offlineRefundIndicator": "string",
        "transactionAllowed": "string",
        "cardholderAuthentication": "string",
        "supervisorFunctions": "string",
        "manualEntryAllowed": "string",
        "floorLimitIndicator": "string",
        "terminalFloorLimit": "string",
        "terminalFloorLimitFallback": "string",
        "maxCashback": "string",
        "maxTransactionAmountIndicator": "string",
        "maxAmount": "string",
        "luhanCheck": "string",
        "expiryDatePosition": "string",
        "delayCallSetup": "string",
        "cardRanges": "string",
        "cardPrefixSequenceIndicator": "string",
        "terminalCvmRequiredLimit": "string",
        "terminalContactlessTransactionLimit": "string",
        "active": true
      }
    ],
    "merchantDto": {
      "merchantName": "string",
      "merchantAddress": "string",
      "providerMid": "string"
    },
    "terminalFeatures": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "string",
        "active": true
      }
    ]
  }
}

The values shown are Swagger example placeholders and do not represent actual terminal data.

9. Response Fields

9.1 Top-Level Fields

FieldTypeDescription
codeNumberAPI response code.
messageStringResponse message.
errorCodeStringError identifier, if applicable.
dataObjectContains card scheme, merchant, and terminal feature details.

9.2 data.cardSchemes

An array of card scheme configuration records associated with the terminal.

FieldTypeDescription
cardSchemeIdStringCard scheme identifier.
cardSchemeNameArStringCard scheme name in Arabic.
cardSchemeNameEnStringCard scheme name in English.
cardSchemeAcquirerIdStringAcquirer identifier associated with the card scheme.
enableEmvStringEMV configuration setting.
checkServiceCodeStringService-code checking setting.
offlineRefundIndicatorStringOffline refund configuration.
transactionAllowedStringTransaction permission setting.
cardholderAuthenticationStringCardholder authentication configuration.
supervisorFunctionsStringSupervisor function settings.
manualEntryAllowedStringManual card entry setting.
floorLimitIndicatorStringFloor-limit indicator.
terminalFloorLimitStringTerminal floor limit.
terminalFloorLimitFallbackStringFallback floor-limit setting.
maxCashbackStringMaximum cashback configuration.
maxTransactionAmountIndicatorStringMaximum transaction amount indicator.
maxAmountStringMaximum amount setting.
luhanCheckStringConfiguration field returned under this exact name.
expiryDatePositionStringCard expiry-date position setting.
delayCallSetupStringDelay call setup configuration.
cardRangesStringCard range configuration.
cardPrefixSequenceIndicatorStringCard prefix sequence indicator.
terminalCvmRequiredLimitStringTerminal CVM-required limit.
terminalContactlessTransactionLimitStringContactless transaction limit.
activeBooleanIndicates whether the card scheme record is active.

9.3 data.merchantDto

Contains merchant information associated with the terminal.

FieldTypeDescription
merchantNameStringMerchant name.
merchantAddressStringMerchant address.
providerMidStringProvider merchant identifier.

9.4 data.terminalFeatures

An array of terminal feature records.

FieldTypeDescription
idUUIDUnique identifier of the terminal feature record.
typeStringFeature type or name.
activeBooleanIndicates whether the feature is active.

10. Error Response — 400 Bad Request

The endpoint documents 400 Bad Request as a possible response.

Example Response

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {}
}
FieldTypeDescription
codeNumberAPI response code.
messageStringError or response message.
errorCodeStringError identifier.
dataObjectAdditional error details; empty in the documented example.

The values shown are Swagger example placeholders, not confirmed runtime response values.

11. Integration Workflow

  1. Authenticate using a valid API key and an authorized SUPER_ADMIN, PARTNER, or MERCHANT account.
  2. Obtain the UUID of the target terminal.
  3. Submit a GET request to the terminal details endpoint.
  4. Inspect the HTTP status and response payload.
  5. Read the cardSchemes array to review the returned card scheme configurations.
  6. Read merchantDto to access the merchant information returned for the terminal.
  7. Review terminalFeatures and each feature's active status.

12. Error Handling and Troubleshooting

If the API returns 400 Bad Request, consider checking the following:

  • Confirm that terminalId is supplied in the URL.
  • Verify that terminalId is a valid UUID.
  • Ensure that the request targets the intended environment.
  • Confirm that the X-API-KEY header contains a valid API key.
  • Inspect message and errorCode for additional diagnostic information.

These are general troubleshooting recommendations. The endpoint's exact validation rules and error mappings are not specified in the provided schema.

13. Important Considerations

  • The endpoint uses the GET method.
  • The required terminalId path parameter must be a UUID.
  • The documented access levels are SUPER_ADMIN, PARTNER, and MERCHANT.
  • Authentication uses the X-API-KEY header.
  • No request body or query parameters are defined.
  • The response contains card scheme configurations, merchant details, and terminal feature activation statuses.
  • The complete set of possible card scheme values and terminal feature types is not specified in the provided schema.

Did this page help you?