Notification service

The normal POS API is pull-based, requiring the POS system to pull updates from the API at regular intervals for processing. In addition to this functionality, the notification service offers a call-back functionality, which can notify a server endpoint, via a HTTP REST call, when a check-in or checkout occours.

The notification feature can be used for scenarios where you want to know if a user has checked in to the unit before issuing a payment. This can be useful for loyalty programmes, promotions or automatic discount calculations etc.

Endpoint scheme
Endpoints follow the standard HTTP URI scheme as specified in RFC7230. The MobilePay POS API will set a HTTP Authorization header based on the same HMAC authentication scheme as the MobilePay POS API uses. It is expected that the endpoint validates this if required. No other security mechanisms are supported

Registration
It is possible to register a notification endpoint on a location or for an entire merchant. Merchants can register up to one endpoint per location or merchant. It is currently not possible to register notification endpoint for the different POS systems.
To register endpoint(s) you send a mail to MobilePay Developer support mailbox (developer@mobilepay.dk) with the Merchantid and/or Locationid for each endpoint.
The same endpoint can be used for multiple Merchants/Locations. The endpoint(s) has to be functional when you send the registration mail.

When we receive the link to the end-point, we forward it to our security department. They will test and evaluate the endpoint. If approved the endpoint will be added to our database, and notifications will start to be sent to the endpoints. If not approved you will be notified with the reason for failing approval

Sequence
First, the MobilePay POS API will check if a notification endpoint has been registered for the location in question and if not, check if a registration exists for the merchant in question:
If the MobilePay API finds a registered endpoint on the location, it will use this for notifications. Otherwise, it falls back to the one registered on the merchant level, if any.

A notification is sent when a customer checks in and checks out again during the payment flow:
Notification service flow

Expected return code
The MobilePay POS API will expect the notification endpoint to return HTTP 200 acknowledging that the notification has been received. The MobilePay POS API will try to resend the notification up to three times if a HTTP 200 response is not received. After this, no more delivery attempts for the notification in question will be made.

Message format
Notifications are carried out as a HTTP POST to the registered endpoint with this body payload:

{
“MerchantId”:“POSDK99999”,
“LocationId”:”88888”,
“PoSId”: “a123456-b123-c123-d123-e12345678901”,
“PoSUnitId”:”123456789012345”,
“AppId”:” ab3911f7-6a91-43c1-bb0f-4a73fe25773f”,
“Timestamp”:”2016-05-15T00:00:00Z”,
“NotifyType”:”Checkin”,
“CustomerToken”:”4ae54eb7-fe66-4214-901c-7f102050ab45”
}
MerchantId String Merchant ID related to current PoS ID.
LocationId String Location ID related to current Merchant ID and PoS ID.
PoSId String Current Point of Sale ID (cash register/terminal).
PoSUnitId String PoSUnit Id identifies a PoSUnit - Box combining SmartBeacon / NFC-chip / QR-label / MobilePay terminal.
AppId String A unique identifier that helps identify the current app checking in or out. This identifier identifies the app, so if the customer has multiple apps/devices, each of these will have its own identifier.
Timestamp String The time and date for the notification formatted as an ISO 8601 date.
NotifyType String Either “Checkin” or “Checkout” at the moment.
CustomerToken String CustomerToken from merchant's Loyalty program, to be used to recalculate Payment Amount.

Message security
Each HTTP POST request has an HMAC-based authentication header set that can be validated on the receiving server. The authorization header is constructed in the same way as it is used in the MobilePay POS API.

The format of the HTTP authorization header is the following:
Authorization: {BASE64HMAC}˽{TimeStampUtc}.
The TimeStampUtc is the current UTC unix timestamp in seconds.
The BASE64HMAC is calculated as the following: Base64 (with padding) encoded HMAC SHA256:

HMAC = Base64(
          hmacSha256(
            UTF8Bytes(“[request url]˽[content body]˽[TimeStampUtc]”),
            UTF8Bytes(APIKey)
          )
       );