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

AttributeDetails
API NameCreate Terminal
HTTP MethodPOST
Endpoint/api/v1/tms/terminals
Access LevelsSUPER_ADMIN, PARTNER
AuthenticationAPI Key (X-API-KEY)
Content-Typeapplication/json
Success Response200 OK
Error Response400 Bad Request

3. Base URL

Production

https://app-api.edfapay.com

Full Endpoint

POST https://app-api.edfapay.com/api/v1/tms/terminals

4. Authorization

This endpoint is available to the following access levels:

  • SUPER_ADMIN
  • PARTNER

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

HeaderTypeRequiredDescription
X-API-KEYStringYesAPI key used to authenticate the request.
Content-TypeStringYesapplication/json
AcceptStringRecommended*/*, as shown in the Swagger response configuration.
X-LangStringNoLanguage for API messages. Defaults to en.

6. Request Body

The endpoint requires a JSON payload containing the terminal and business unit information.

Parameters

ParameterTypeRequiredDescription
businessUnitIdUUIDYesIdentifier of the business unit associated with the terminal.
tmsVersionStringYesTMS version associated with the terminal configuration.
trsmStringYesTerminal identifier used by the TMS.
providerTidStringYesTerminal 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_KEY with 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: Bearer unless 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

FieldTypeDescription
codeNumberApplication-level response code.
messageStringResponse message.
errorCodeStringApplication error identifier, where applicable.
dataObjectTerminal information returned by the API.
data.idUUIDUnique terminal record identifier.
data.trsmStringTMS terminal identifier.
data.providerTidStringPayment provider terminal identifier.
data.providerMidStringPayment provider merchant identifier.
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.tmsVersionStringTMS version associated with the terminal.
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. Ensure all required request fields are supplied.
  2. Verify that businessUnitId is a valid UUID.
  3. Confirm that trsm and providerTid contain valid identifiers.
  4. Check that tmsVersion matches a supported version.
  5. Verify the API key and the caller's access level.
  6. Inspect the response's message and errorCode for 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

  1. Obtain a valid API key for the target environment.
  2. Obtain the target business unit ID.
  3. Prepare the terminal identifier, provider terminal ID, and TMS version.
  4. Submit the POST request with the required JSON body and X-API-KEY header.
  5. Evaluate the HTTP status and application response.
  6. 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_ADMIN and PARTNER.
  • 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.

Did this page help you?