Here you can read PoS integrator best practice for handling different real life situations. Please let us know if you have some hard earned best practice solution we should add to this section. We will elaborate on 3 best practices:
- Starting the cash register.
- Starting a payment or reservation when previous payment/reservation has not been finalized.
- Handling the PaymentAccepted state
There are different ways to register the PoS. Some PoS systems do an automatic configuration during startup of the cash register, while others use a configuration program/screen. It is the intention that the PoS should “always” be registered, and the PoS unit should “always” be assigned. It is the intention that the customer can do a checkin with the app – regardless of the state of the cash register. Note the following recommendation:
Use one PoS ID per PoS: It is recommended not to register a new PoS ID at each startup of the cash register.
The PoS ID must be globally unique. This can be ensured in one of the following ways:
- Use one of MobilePay methods of getting a unique ID:
RegisterPoswith empty POS ID.
- Use an identifier which is unique within the merchant and prefix with the merchant name.
During the startup of the cash register, the cash register should do the following:
- It should check to see whether its current PoS ID and connected PoS Unit ID are already registered in the MobilePay backend. (using
- If the PoS ID is not registered, the behaviour depends on whether the cash register registers itself automatically:
- Automatic registration: Call RegisterPoS
- Manual registration: Disable MobilePay payments until the PoS has been registered.
- If the PosUnit is not assigned (or the wrong posunitd is assigned to the PosId), the behaviour should be:
- Automatic registration: Call
- Manual registration: Disable MobilePay payments until the PoS unit has been registered.
The cash register may get the PoS unit ID in a number of different ways:
- Read directly from the PoS unit via USB connection
- The PoS unit ID is entered manually in a setup screen/program
- The PoS unit is retrieved by scanning the bar code/QR code on the PoS unit
Some error scenarios may prevent the PoS from clearing a payment or reservation transaction when an error occurs. This may, for example, occur if a payment or reservation has been started, and the PoS crashes or loses Internet connection. When the PoS attempts to start a new payment or reservation, it will receive an error, because the old payment/reservation is still present in the system.
ReservationStart returns http 200 when successful and http 400 with JSON StatusCode = 50 if an unfinished payment already exists. In the latter case, the PoS must clear the payment with
PaymentCancel (or ReservationCancel for reservations) before sending a new
Note that it should also be checked whether the PaymentCancel/ReservationCancel is successful (http 200).
If a payment or reservation is left when the cash register crashes, this should also be handled during startup of the cash register:
|During startup of the cash register, any unfinished payments/reservations (status 20 or 30) must be either paid or cancelled.|
This handling is necessary even though the payment is cleared when
PaymentStart is called. The reason is that a new customer may check in before the
PaymentStart is called and this will result in unexpected situations (depending on whether the status is 20, 30 or 80).
In previous version of the API MobilePay PoS locked the payment (State=80/PaymentAccepted) for 90 seconds when the user slided for payment to be processed. This required the PoS system to implement a counting mechanism in order to prevent attempts on cancelling a payment in status 80 (Accepted). This is no longer needed, and a Payment can be cancelled even in status 80. So if you are upgrading from a previous version of the API, the 90 second handling can be removed.
|20/issued||Can be cancelled|
|30/AwaitCheckin||Can be cancelled|
|80/PaymentAccept||Can be cancelled|
|100/Done||Cancel not possible|