Cashier Management API

The Cashier Management APIs enable merchants and ECR partners to manage cashiers directly via API, without requiring access to the NeoPaaS Merchant Portal.

These APIs streamline operations for environments where terminals are shared, cashiers work in shifts, or new terminals are being provisioned dynamically.

---

Overview

In traditional setups, adding or updating a cashier required manual actions on the Merchant Portal. With our Cashier Management APIs, this process can now be automated directly from the ECR system through our API.

These APIs allow:

• Adding a new cashier.
• Associating/Binding a cashier to a terminal.
• Deassociating/Unbinding a cashier from a terminal.

Each cashier account is securely linked to a merchant and terminal within NeoPaaS, ensuring that transactions and access control remain traceable.

---

Add Cashier

Creates a new cashier under a merchant account.

POST{{url}}/api/v1/cashiers

Parameters

Field	Type	Required	Description
fullName	string	Yes	Full name of the cashier being created.
username	string	Yes	Unique username the cashier will log in with.
password	string	Yes	Password for the cashier account.
branchId	string	Yes	Branch the cashier belongs to.
terminalId	string	No	Terminal to associate the cashier with immediately.

Example Request

{
    "fullName": "new third cashier",
    "username": "cash123",
    "password": "2121",
    "branchId": "240",
    "terminalId": "4445678988"
}

Response

Example Response

{
  "success": true,
  "message": "Cashier created successfully"
}

Associate Cashier to Terminal (Binding)

Associates/binds an existing cashier with a terminal. A cashier must be associated before initiating any transactions via the client app.

PUT{{url}}/api/v1/terminals/associate

Parameters

Field	Type	Required	Description
terminalId	string	Yes	Terminal to associate the cashier with.
cashierUsername	string	Yes	Username of the cashier to bind.

Example Request

{
  "terminalId": "14582488",
  "cashierUsername": "cash12"
}

Response

Example Response

{
  "message": "Terminal cashier updated"
}

Deassociate Cashier from Terminal (Unbinding)

Removes the current cashier assigned to a terminal, allowing a new cashier to take over. This can be done using the merchant credential. Useful for shift-based operations or reassigning terminals to new staff.

POST{{url}}/api/v1/terminals/{terminalId}/dissociate

Parameters

Parameter	Type	Required	Description
terminalId	string	Yes	The terminal to remove the current cashier from, in the URL path.

Response

Example Response

{
  "message": "Terminal cashier dissociated"
}

Error Handling

The Cashier Management APIs return standardized error codes to help identify and troubleshoot request failures. Refer to the appropriate table below based on the API being called.

Add Cashier

Error Code	Error Scenario	API Response Message	Action Required
1000	Merchant Not Found	Merchant record was not found for the requested assignment flow.	Verify the merchantId exists before submitting the request.
1001	Terminal Not Found	Terminal record was not found.	Verify the terminalId is correct and exists in the system.
1002	Branch Not Found	Branch record was not found.	Ensure a valid, existing branchId is provided.
1003	Terminal Already Assigned	The terminal is already assigned and cannot be assigned again.	Unassign the terminal from its current cashier, or select an unassigned terminal.
1004	Branch Deactivated	The branch is deactivated and cannot be used in the workflow.	Use an active branch, or reactivate the branch before proceeding.
1005	Internal Server Error	A server-side error occurred during the cashier onboarding process.	Retry the request. If the issue persists, contact support and provide the request reference or transaction details.

---

Associate / Dissociate Cashier

Error Code	Error Scenario	API Response Message	Action Required
1006	Forbidden Terminal Update	The operation is forbidden for the requested terminal update.	Verify the terminal's current state permits this update, or use an authorized terminal.
1007	Cashier Already Linked	The cashier is already linked to a different terminal.	Unlink the cashier from its current terminal before assigning it to another.
1008	Terminal Server Error	A terminal server-side error occurred while processing the request.	Retry the request. If the issue persists, contact support with the request reference.
1009	Missing Required Identifier	The request is missing the terminal or cashier identifier required to continue.	Include both terminalId and cashierId in the request.
1010	Terminal Not Found	The terminal could not be found.	Verify the terminalId is correct and exists in the system.
1011	Invalid Cashier ID Format	The cashier ID format is invalid.	Ensure the cashierId is provided in the correct format.
1012	Cashier Already Linked	The cashier is already linked to a different terminal.	Select a cashier that is not currently associated with another terminal.
1013	Validation Error	A validation error occurred while processing the request.	Review the request payload and correct any invalid or missing fields.
1014	Terminal Not Found (Dissociation)	The terminal could not be found for dissociation.	Verify the terminalId exists before attempting dissociation.
1015	Dissociation Forbidden	Dissociation is not permitted for the current terminal state.	Ensure the terminal is not locked or in a state that prevents cashier removal.
1016	No Cashier Associated	No cashier is associated with the specified terminal.	Confirm a cashier is currently linked to the terminal before attempting dissociation.
1017	Dissociation Server Error	A server-side error occurred while dissociating the terminal.	Retry the request. If the issue persists, contact support and provide the request reference.

Example Error Response

{
  "errorCode": 1003,
  "message": "The terminal is already assigned and cannot be assigned again."
}

Use Cases

1. Shift-Based Cashier Replacement

In retail or restaurant environments, multiple cashiers may operate on the same terminal during different shifts. The Deassociate and Associate APIs allow:

• The merchant to deassociate the outgoing cashier at shift end.
• The merchant to associate the incoming cashier to the same terminal seamlessly.
• This eliminates dependency on Merchant Portal access and ensures that each transaction is logged under the correct cashier.

2. New Cashier Onboarding

When a new employee joins, the Add Cashier API can be triggered automatically from the ECR or HR system to create their account under the merchant. The system can then associate them to a terminal immediately using the Associate API — reducing manual configuration time.

3. Terminal Replacement / Device Migration

The merchant (via merchant API credentials) can deassociate the cashier from the old terminal. The same cashier can then be re-associated to a new terminal without impacting permissions or historical transaction data, ensuring business continuity with minimal operational disruption.

4. Multi-Terminal Merchants

Merchants with several terminals can use these APIs to dynamically assign cashiers to different terminals based on demand — e.g., during busy hours, cashiers can log in to new terminals quickly.

Security and Access Control

• All Add, Associate, and Deassociate Cashier APIs must be invoked using merchant account API credentials or tokens.
• Cashier accounts/credentials themselves cannot invoke these APIs.
• Role-based access control is enforced to ensure only authorized merchant-level entities can manage cashier–terminal associations.

Usage Tips

• Ensure that each terminal has exactly one active cashier association at a time.
• A deassociated terminal cannot perform transactions until a new cashier is associated.