MobilePay PoS V8
 
NOTICE:
It is no longer possible to onboard this version of the PoS API. All information found on this page may be outdated. Instead please refer to the newest version PoS API v10
 
Step 4 - Best Practice

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: 

  1. Starting the cash register. 
  2. Starting a payment or reservation when previous payment/reservation has not been finalized. 
  3. Handling the PaymentAccepted state
Starting the cash register

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: GetUniquePoSId or RegisterPos with empty POS ID.
  • Use an identifier which is unique within the merchant and prefix with the merchant name.

Start-Up

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 ReadPoSAssignPoSUnitId and/or ReadPosUnitAssignedPoSId)
  • 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 AssignPosUnitIdToPosId
    • 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
Starting a payment or reservation when it has not been finalized

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.

PaymentStart and 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 PaymentStart/ReservationStart.

If PaymentStart/ReservationStart fails with JSON status code 50, clear the unfinished payment with the relevant Cancel method (PaymentCancel or ReservationCancel) and retry upon succesfull cancel- making it transparent to the user of the PoS system.

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).

Handling the PaymentAccepted state

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.

Status Cancel possible?
20/issued Can be cancelled
30/AwaitCheckin Can be cancelled
40/Cancel N/A
50/Error N/A
80/PaymentAccept Can be cancelled
100/Done Cancel not possible

 

FAQ - Point of Sale V8

In this section, you will find the answers to the most common questions about MobilePay Point of Sales API V8