TMS APIs
Provides an overview of the EdfaPay Terminal Management System (TMS) APIs, covering terminal creation, assignment, status management, registration, initialization, configuration, binding, and monitoring. Includes authentication requirements, access levels, response structure, error handling, and links to the individual endpoint documentation.
1. Overview
The EdfaPay Terminal Management System (TMS) APIs provide endpoints for managing payment terminals throughout their lifecycle, including creation, assignment, registration, initialization, configuration, status management, and monitoring.
Authorized users can create and manage terminal records, retrieve terminal information, search and filter terminals, manage terminal assignments, and access configuration data required for terminal operations.
2. API Categories
2.1 Terminal Management
Manage terminal records and retrieve terminal information.
- Create Terminal — Create a new terminal record in the TMS.
- Bulk Terminal Creation — Create multiple terminal records by uploading a CSV file.
- Get Terminal Details — Retrieve detailed information for a specific terminal.
- Search and Filter Terminals — Search terminal records using supported criteria and pagination.
- Get Terminals Summary Statistics — Retrieve terminal counts grouped by status and registration state.
2.2 Terminal Assignment
Manage terminal associations with business units and merchants.
- Terminal Assignment — Assign a terminal to a business unit or remove an existing assignment.
- Get Terminal Assignment Details — Retrieve terminal assignment history, including previous and new business unit and merchant information.
2.3 Terminal Status Management
Manage terminal operational status.
- Change Terminal Status — Update a terminal's status to
ACTIVEorDISABLED, subject to the user's access permissions.
2.4 Terminal Registration and Initialization
Initiate terminal initialization and monitor registration progress.
- Terminal Initialization — Start the initialization process for a specified terminal.
- Get Terminal Initialization Status — Retrieve initialization progress, registration status, processing details, and any reported failure message.
2.5 Terminal Configuration
Retrieve and refresh terminal configuration data.
- Refresh Terminal Configuration — Request a refresh of the specified terminal's configuration.
- Get Full Terminal Configuration — Retrieve configuration data, including card schemes, public keys, message texts, AID parameters, retailer information, and device-specific settings.
2.6 Terminal Binding
Manage terminal binding relationships.
- Unbind Terminal — Remove the binding associated with a specified terminal identifier.
3. Access Control
Access to TMS endpoints is controlled by the authenticated user's assigned permissions.
The documented endpoints support the following access levels, depending on the operation:
SUPER_ADMINPARTNERMERCHANT
Access permissions vary by endpoint. Refer to the Access Level section on each API page to determine which roles are authorized to perform the operation.
4. Authentication and Requests
TMS API requests use API key authentication through the X-API-KEY request header.
Production Base URL
https://app-api.edfapay.com
Include the following headers as applicable:
| Header | Value |
|---|---|
X-API-KEY | YOUR_API_KEY |
Accept | */* |
Content-Type | Depends on the request payload |
For each request:
- Use the HTTP method and endpoint path specified in the API reference.
- Provide all required path and query parameters.
- Include the required headers and request body, where applicable.
- For file-upload endpoints, use the documented multipart form-data format.
- Review the endpoint's response schema and HTTP status codes to handle the result appropriately.
5. Response Structure
Many documented TMS endpoints use a standard response envelope containing the following fields:
| Field | Description |
|---|---|
code | API response code. |
message | Response message. |
errorCode | Error identifier, where applicable. |
data | The requested resource, operation result, or response details. |
The structure and data types of data vary by endpoint. Refer to the individual endpoint's response schema for the exact fields and expected values.
6. Error Handling
A documented endpoint may return 400 Bad Request when a request cannot be processed. Other HTTP status codes depend on the specific endpoint and its documented responses.
For reliable error handling:
- Validate required parameters before sending the request.
- Ensure the API key is supplied correctly.
- Check the endpoint's documented response schema.
- Use the returned response code, message, and error details where available.
Do not assume that every endpoint returns identical error fields or supports the same HTTP status codes.
7. API Reference
Use the Terminal Management section in the API documentation navigation menu to browse individual TMS endpoints.
Each endpoint page provides the applicable HTTP method, endpoint path, access level, parameters, request body or upload requirements, response schema, and documented HTTP status codes.
Refer to the individual API page for endpoint-specific requirements and examples.
Updated 25 days ago