Terminal Assignment — API

Allows authorized partners to assign a terminal to a business unit or request its unassignment using the terminalId, businessUnitId, and isAssign fields. Uses API Key authentication through the X-API-KEY header.

1. Overview

The Terminal Assignment API allows an authorized partner to assign a terminal to a business unit or request its unassignment using the isAssign field.

2. Endpoint Summary

AttributeDetails
API NameTerminal Assignment
HTTP MethodPUT
Endpoint/api/v1/tms/terminals/terminal/terminal-assignment
Access LevelPARTNER
Content-Typeapplication/json
Success Response200 OK
Error Response400 Bad Request
AuthenticationAPI Key (X-API-KEY)

3. Base URL

Production

https://app-api.edfapay.com

Full Endpoint

PUT https://app-api.edfapay.com/api/v1/tms/terminals/terminal/terminal-assignment

4. Authorization

This endpoint requires the PARTNER access level and uses API Key authentication through the X-API-KEY request header.

The API key must be valid and authorized to access this operation.

5. Request Headers

HeaderTypeDefaultDescription
X-API-KEYStringNoneAPI key used to authenticate the request.
Content-TypeStringapplication/jsonSpecifies the request body format.
AcceptString—Specifies the expected response format.
X-LangStringenSpecifies the language used for API messages.

The Swagger specification displays en as the default value for X-Lang.

6. Request Body

The endpoint requires a JSON request body containing three fields.

Parameters

ParameterTypeRequiredDescription
terminalIdUUIDYesUnique identifier of the terminal to assign or unassign.
businessUnitIdUUIDYesIdentifier of the business unit associated with the assignment operation.
isAssignBooleanYesDetermines whether to assign or unassign the terminal.

Assignment Behavior

  • isAssign: true — Requests terminal assignment.
  • isAssign: false — Requests terminal unassignment.

The exact relationship between the business unit and merchant ownership is not established by the endpoint schema.

Example Request

{
  "terminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isAssign": true
}

The UUIDs are illustrative Swagger example values, not verified production identifiers.

7. cURL Examples

7.1 Assign a Terminal

curl --request PUT \
  --url 'https://app-api.edfapay.com/api/v1/tms/terminals/terminal/terminal-assignment' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: */*' \
  --header 'X-Lang: en' \
  --data '{
    "terminalId": "TERMINAL_UUID",
    "businessUnitId": "BUSINESS_UNIT_UUID",
    "isAssign": true
  }'

7.2 Unassign a Terminal

curl --request PUT \
  --url 'https://app-api.edfapay.com/api/v1/tms/terminals/terminal/terminal-assignment' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: */*' \
  --header 'X-Lang: en' \
  --data '{
    "terminalId": "TERMINAL_UUID",
    "businessUnitId": "BUSINESS_UNIT_UUID",
    "isAssign": false
  }'

Implementation Notes

  • Replace YOUR_API_KEY with a valid API key.
  • Replace TERMINAL_UUID and BUSINESS_UNIT_UUID with valid UUIDs.
  • Use the appropriate base URL for the target environment.
  • Do not use Authorization: Bearer for this endpoint unless a separate security configuration explicitly requires it.

8. Response Specification

8.1 HTTP 200 — OK

The Swagger definition documents a successful HTTP response with the following schema:

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {}
}
FieldTypeDescription
codeNumberApplication-level response code.
messageStringResponse message returned by the service.
errorCodeStringApplication error identifier, where applicable.
dataObjectAdditional response data.

The actual success message and data structure are not specified in the displayed schema.

8.2 HTTP 400 — Bad Request

The endpoint documents 400 Bad Request as a possible response.

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {}
}

Troubleshooting checks:

  • Verify that all three required request fields are present.
  • Confirm that terminalId and businessUnitId contain valid UUIDs.
  • Ensure that isAssign is a Boolean (true or false), not a string.
  • Verify the API key and the caller's access level.
  • Inspect message and errorCode for details of the rejection.

These are general troubleshooting checks; the exact validation rules and error mappings are not defined in the displayed schema.

9. Integration Workflow

  1. Obtain a valid API key with the required PARTNER access.
  2. Obtain the terminal ID and the relevant business unit ID.
  3. Set isAssign to true to request assignment or false to request unassignment.
  4. Send the JSON payload to the terminal assignment endpoint.
  5. Evaluate the HTTP status and response payload.
  6. Verify the resulting assignment through the appropriate TMS operation if confirmation is required.

10. Implementation Considerations

  • Access control: PARTNER is the documented access level for this endpoint.
  • Identifier integrity: Ensure both identifiers refer to the intended records.
  • Language handling: Use X-Lang: en for English messages.
  • Error handling: Capture the HTTP status, application response code, message, and error identifier.
  • Retries: Do not assume repeated requests are idempotent without confirming backend behavior.
  • API key security: Store the key securely and avoid exposing it in logs or public documentation.

11. API Specification Notes

The available Swagger documentation confirms the endpoint, HTTP method, access level, language header, request fields, and documented response statuses.

The following details are not established by the displayed schema:

  • Additional validation rules and application-level response mappings.
  • The exact business-unit and merchant ownership relationship.
  • Any additional side effects of assignment changes.
  • Retry and idempotency guarantees.



Did this page help you?