Search and Filter Terminals — API

Searches and filters terminals using the required pageProperties and searchCriteria query objects. Returns terminal search results in a paginated format with page metadata and sorting information. Accessible to SUPER_ADMIN, PARTNER, and MERCHANT roles using API Key authentication through the X-API-KEY header. Confirm query-object serialization through Swagger's Try it out feature before integration.

1. Overview

The Search and Filter Terminals API retrieves terminal records based on the supplied search criteria and returns the results in a paginated format. It supports text-based searches and terminal identifier (trsm) searches, along with configurable pagination.

Access Levels: SUPER_ADMIN, PARTNER, MERCHANT

2. Endpoint Details

PropertyValue
API NameSearch and Filter Terminals
HTTP MethodGET
Endpoint/api/v1/tms/terminals/search
Access LevelsSUPER_ADMIN, PARTNER, MERCHANT
Request ParameterspageProperties, searchCriteria
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/search

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. Query Parameters

The provided Swagger definition marks both query objects as required.

5.1 pageProperties

Defines pagination settings for the terminal search results.

Example object:

{
  "pageNumber": 0,
  "pageSize": 10
}
FieldTypeDescription
pageNumberIntegerPage number to retrieve. The example uses 0 for the first page.
pageSizeIntegerNumber of records requested per page.

5.2 searchCriteria

Defines the criteria used to search for terminals.

Example object:

{
  "text": "Samsung",
  "trsm": "4E0001"
}
FieldTypeDescription
textStringGeneral text search. The Swagger example uses Samsung.
trsmStringTerminal identifier or TRSM value to search for.

The provided schema shows these example fields but does not establish the complete set of supported search criteria.

5.3 Query Serialization

Although Swagger represents pageProperties and searchCriteria as query objects, the exact serialization format required by the server is not established by the provided definition.

Use Swagger's Try it out feature to inspect the generated request URL and confirm how both objects must be encoded.

6. Request Headers

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

No JSON request body is defined for this endpoint.

7. cURL Example

The following is a base request example. Add the required query parameters using the serialization format confirmed through Swagger.

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

Before execution:

  • Replace YOUR_API_KEY with a valid API key.
  • Include both required query objects in the format accepted by the API.
  • Verify the generated URL using Swagger's Try it out feature before integrating the request.

This example intentionally omits the query objects because their exact URL encoding cannot be confirmed from the supplied definition.

8. Successful Response — 200 OK

Example Response

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {
    "totalPages": 0,
    "totalElements": 0,
    "size": 0,
    "content": [
      {}
    ],
    "number": 0,
    "pageable": {
      "offset": 0,
      "paged": true,
      "pageNumber": 0,
      "pageSize": 0,
      "sort": [
        {
          "direction": "string",
          "nullHandling": "string",
          "ascending": true,
          "property": "string",
          "ignoreCase": true
        }
      ],
      "unpaged": false
    },
    "sort": [
      {
        "direction": "string",
        "nullHandling": "string",
        "ascending": true,
        "property": "string",
        "ignoreCase": true
      }
    ],
    "numberOfElements": 0,
    "first": true,
    "last": true,
    "empty": true
  }
}

Note: The content item is represented as an empty object ({}) in the supplied schema. The actual terminal fields returned for each item are not visible in the provided definition.

9. Response Fields

9.1 Standard Response Envelope

FieldTypeDescription
codeNumberAPI response code.
messageStringResponse message.
errorCodeStringError identifier, if applicable.
dataObjectPaginated search result.

9.2 Pagination Fields — data

FieldTypeDescription
totalPagesIntegerTotal number of pages available.
totalElementsIntegerTotal number of matching records.
sizeIntegerPage size reported by the response.
contentArrayTerminal records returned for the requested page.
numberIntegerCurrent page number.
pageableObjectPagination configuration and metadata.
sortArraySorting information for the result.
numberOfElementsIntegerNumber of records returned on the current page.
firstBooleanIndicates whether the current page is the first page.
lastBooleanIndicates whether the current page is the last page.
emptyBooleanIndicates whether the current page contains no records.

9.3 data.pageable

FieldTypeDescription
offsetIntegerOffset of the first record for the current page.
pagedBooleanIndicates whether pagination is enabled.
pageNumberIntegerCurrent page number.
pageSizeIntegerConfigured page size.
sortArraySorting metadata associated with pagination.
unpagedBooleanIndicates whether the results are unpaged.

9.4 Sorting Object

Each entry in sort contains the following fields:

FieldTypeDescription
directionStringSort direction.
nullHandlingStringNull-value handling strategy.
ascendingBooleanIndicates whether sorting is ascending.
propertyStringProperty used for sorting.
ignoreCaseBooleanIndicates whether case is ignored during sorting.

The accepted values for direction and nullHandling are not specified in the supplied schema.

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. Prepare the required pageProperties object with the desired page number and page size.
  3. Prepare the searchCriteria object with the supported search fields.
  4. Confirm the query-object serialization using Swagger's Try it out feature.
  5. Submit a GET request to the terminal search endpoint with both required query objects.
  6. Inspect the response and review totalElements, totalPages, and numberOfElements.
  7. Process the terminal records returned in content.
  8. Request additional pages as needed.

12. Error Handling and Troubleshooting

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

  • Confirm that both pageProperties and searchCriteria are included.
  • Verify that the query objects are serialized in the format expected by the API.
  • Check the data types of pageNumber, pageSize, text, and trsm.
  • 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 exact query serialization rules, validation constraints, and error mappings are not specified in the supplied definition.

13. Important Considerations

  • The endpoint uses the GET method.
  • Both pageProperties and searchCriteria are marked as required.
  • The endpoint uses query parameters rather than a JSON request body.
  • Authentication uses the X-API-KEY header.
  • The response follows a paginated structure.
  • The individual terminal record schema within content is not shown in the supplied definition.
  • The exact query-object serialization must be confirmed before production integration.
  • Sorting fields are present in the response schema, but supported sorting inputs are not established by the provided definition.

Did this page help you?