"Order N Pay" Examples

Summary

This method is used by the POS to request an access to token which it will then use when connecting to the websocket server

For secure communications to occur, the 3rd party integrator must also provide a rest api endpoint that can be called. The rest endpoint must be at the same host address as the websocket server. So for a websocket server address of wss://websocket.provider.com the authentication rest uri would be https://websocket.provider.com/api/powerepos/v1/auth

The POS will submit an auth token request (OrderNPayAuthTokenRequest) to that endpoint to request an access token for the websocket service. The rest endpoint must return a OrderNPayAuthTokenResponse model containing the access token, or an error message in the event of failure.

There are three pieces of information required for an authentication request.

  • ProviderOutletID (string) - This is the unique ID of the outlet in the 3rd party integrators system. The 3rd party integrator will provide this to PowerEPOS when an integration is being enabled for a customer.
  • POSRemoteID (string) - This is the unique ID from PowerEPOS representing a specific outlet within an organisation. PowerEPOS will provide this to the 3rd party integrator when an integration is being enabled for a customer.
  • AuthSecret (string) - This is a shared secret between PowerEPOS and the 3rd party integrator for this specific integration connection. Both parties need to know this value. This value should be unique per organisation and outlet.

The 3rd party implementation of the auth endpoint will need to verify the 3 values provided in the auth request are as expected. This provides a sanity check that both parties are referring to the same outlet in their configuration of the interface.

The access token returned in the auth response will be used during the websocket connection phase. The pos will connect to the websocket uri with the token as a query parameter. For example, wss://websocket.provider.com?token=abcdef123456

Request/Response Payload Models

Authentication (REST API)

Eg The POSServer submits a POST request to https://websocket.provider.com/api/powerepos/v1/auth

OrderNPayAuthTokenRequest

{
    "ProviderOutletID": "3f49efe7-ea42-4f21-8718-7e6ce9a33512",
    "POSRemoteID": "TestOrg-7ab4da81-d75b-4239-9aac-bdc0d2fb8f9a",
    "AuthSecret": "sharedS3cr3t!"
}

On success, the 3rd party provider responds with

OrderNPayAuthTokenResponse

{
    "AccessToken": "VGhpcyBpcyBteSBhY2Nlc3MgdG9rZW4=",
}

On failure, the 3rd party provider responds with

OrderNPayAuthTokenResponse

{
    "ErrorMessage": "The auth secret was not valid!",
}