Skip to main content

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.

API Endpoints​

1. Add Cashier​

Endpoint:

POST /api/v1/cashiers

Description:
Creates a new cashier under a merchant account.

Request Example

curl --location --request POST 'https://{{url}}/api/v1/cashiers' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "fullName": "new third cashier",
    "username": "cash123",
    "password": "2121",
    "branchId": "240",
    "terminalId": "4445678988"
}'

Response Example


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

2. Associate Cashier to Terminal/Binding​

Endpoint:

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

Description:

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

Request Example

curl --location --request POST 'https://{{url}}/api/v1/terminals/associate' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "terminalId": "14582488",
  "cashierUsername": "cash12"
}'

Response Example


{
  "message":"Terminal cashier updated"
}

3. Deassociate Cashier from Terminal/Unbinding​

Endpoint:

POST /api/v1/terminals/terminalId/dissociate

Description:

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.

Request Example

curl --location --request POST 'https://{{url}}/api/v1/terminals/55511100/dissociate' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \

Response Example

{
  "message":"Terminal cashier dissociated"
}

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 incoming cashier to the same terminal seamlessly.

  • This eliminates dependency on the 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.

This ensures 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.