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
| Attribute | Details |
|---|---|
| API Name | Terminal Assignment |
| HTTP Method | PUT |
| Endpoint | /api/v1/tms/terminals/terminal/terminal-assignment |
| Access Level | PARTNER |
| Content-Type | application/json |
| Success Response | 200 OK |
| Error Response | 400 Bad Request |
| Authentication | API Key (X-API-KEY) |
3. Base URL
Production
https://app-api.edfapay.comFull Endpoint
PUT https://app-api.edfapay.com/api/v1/tms/terminals/terminal/terminal-assignment4. 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
| Header | Type | Default | Description |
|---|---|---|---|
X-API-KEY | String | None | API key used to authenticate the request. |
Content-Type | String | application/json | Specifies the request body format. |
Accept | String | — | Specifies the expected response format. |
X-Lang | String | en | Specifies 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
| Parameter | Type | Required | Description |
|---|---|---|---|
terminalId | UUID | Yes | Unique identifier of the terminal to assign or unassign. |
businessUnitId | UUID | Yes | Identifier of the business unit associated with the assignment operation. |
isAssign | Boolean | Yes | Determines 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_KEYwith a valid API key. - Replace
TERMINAL_UUIDandBUSINESS_UNIT_UUIDwith valid UUIDs. - Use the appropriate base URL for the target environment.
- Do not use
Authorization: Bearerfor 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": {}
}| Field | Type | Description |
|---|---|---|
code | Number | Application-level response code. |
message | String | Response message returned by the service. |
errorCode | String | Application error identifier, where applicable. |
data | Object | Additional 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
terminalIdandbusinessUnitIdcontain valid UUIDs. - Ensure that
isAssignis a Boolean (trueorfalse), not a string. - Verify the API key and the caller's access level.
- Inspect
messageanderrorCodefor 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
- Obtain a valid API key with the required
PARTNERaccess. - Obtain the terminal ID and the relevant business unit ID.
- Set
isAssigntotrueto request assignment orfalseto request unassignment. - Send the JSON payload to the terminal assignment endpoint.
- Evaluate the HTTP status and response payload.
- Verify the resulting assignment through the appropriate TMS operation if confirmation is required.
10. Implementation Considerations
- Access control:
PARTNERis the documented access level for this endpoint. - Identifier integrity: Ensure both identifiers refer to the intended records.
- Language handling: Use
X-Lang: enfor 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.
Updated 25 days ago