Create Terminal — API
Creates a new terminal record in the Terminal Management System and associates it with a specified business unit. Requires businessUnitId, tmsVersion, trsm, and providerTid, and is accessible to SUPER_ADMIN and PARTNER roles using API Key authentication through the X-API-KEY header.
1. Overview
The Create Terminal API allows authorized users to create a terminal record in the Terminal Management System (TMS) and associate it with a business unit.
2. Endpoint Summary
| Attribute | Details |
|---|---|
| API Name | Create Terminal |
| HTTP Method | POST |
| Endpoint | /api/v1/tms/terminals |
| Access Levels | SUPER_ADMIN, PARTNER |
| Authentication | API Key (X-API-KEY) |
| Content-Type | application/json |
| Success Response | 200 OK |
| Error Response | 400 Bad Request |
3. Base URL
Production
https://app-api.edfapay.comFull Endpoint
POST https://app-api.edfapay.com/api/v1/tms/terminals4. Authorization
This endpoint is available to the following access levels:
SUPER_ADMINPARTNER
Authentication uses an API key supplied through the X-API-KEY request header. The key must be valid and authorized for 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. |
X-Lang | String | No | Language for API messages. Defaults to en. |
6. Request Body
The endpoint requires a JSON payload containing the terminal and business unit information.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
businessUnitId | UUID | Yes | Identifier of the business unit associated with the terminal. |
tmsVersion | String | Yes | TMS version associated with the terminal configuration. |
trsm | String | Yes | Terminal identifier used by the TMS. |
providerTid | String | Yes | Terminal identifier assigned by the payment provider. |
Example Request
{
"businessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tmsVersion": "TMS1",
"trsm": "d24dE8",
"providerTid": "0082142902344782"
}The values follow the Swagger example and are provided for illustration only.
7. cURL Example
curl --request POST \
--url 'https://app-api.edfapay.com/api/v1/tms/terminals' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'X-Lang: en' \
--data '{
"businessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tmsVersion": "TMS1",
"trsm": "d24dE8",
"providerTid": "0082142902344782"
}'Implementation Notes
- Replace
YOUR_API_KEYwith a valid API key. - Replace the example identifiers with valid values for your environment.
- Use the appropriate base URL for the target environment.
- Do not use
Authorization: Bearerunless a separate security configuration explicitly requires it.
8. Response Specification
8.1 HTTP 200 — OK
The API returns a standard response envelope containing terminal information.
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:56:12.674Z",
"updatedBy": "string",
"updatedAt": "2026-10-28T11:56:12.674Z",
"lastTransactionCreatedAt": "2026-10-28T11:56:12.674Z",
"lastDownloadParametersUpdatedAt": "2026-10-28T11:56:12.674Z",
"reconciliationTime": "string",
"holderAccount": "string"
}
}The response values follow the Swagger example schema and are 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 | TMS terminal identifier. |
data.providerTid | String | Payment provider terminal identifier. |
data.providerMid | String | Payment provider merchant identifier. |
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 | TMS version associated with the terminal. |
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
- Ensure all required request fields are supplied.
- Verify that
businessUnitIdis a valid UUID. - Confirm that
trsmandproviderTidcontain valid identifiers. - Check that
tmsVersionmatches a supported version. - Verify the API key and the caller's access level.
- Inspect the response's
messageanderrorCodefor failure details.
These are general troubleshooting recommendations. The endpoint's exact validation rules and error codes are not fully specified in the displayed schema.
10. Integration Workflow
- Obtain a valid API key for the target environment.
- Obtain the target business unit ID.
- Prepare the terminal identifier, provider terminal ID, and TMS version.
- Submit the
POSTrequest with the required JSON body andX-API-KEYheader. - Evaluate the HTTP status and application response.
- Verify that the terminal was created and associated with the intended business unit.
11. Important Considerations
- This endpoint creates a single terminal.
- The request body must use
application/json. - The documented access levels are
SUPER_ADMINandPARTNER. - Ensure terminal identifiers correspond to the correct provider and business unit.
- Do not assume that terminal creation automatically completes device registration or provider-side configuration; this behavior is not established by the supplied documentation.
- Confirm identifier constraints and duplicate-terminal handling before production integration.
- Store API keys securely and avoid exposing them in logs or public documentation.
Updated 25 days ago