Skip to main content

Migrating Point of Sale to new common platform

As part of the transition to a joint Vipps MobilePay platform, MobilePay PoS will be replaced by the Vipps MobilePay ePayment API. Read more about the transition to one platform transition to one platform.

On this page, you will find a comparison between the existing MobilePay PoS API and the ePayment API.

Different solutions for different setups

Depending on the merchant setup, there can be multiple ways to implement the payment flow. This section tries to sketch an overview of what is possible, and what might be the best approach depending on the merchant setup today.

In all cases, the ePayment API will be used for integrating payments. The main differences are with pairing the customer that wants to pay, with the given checkout that wants to issue the payment.

The next sections will contain the recommended approaches based on what capabilities the merchant has available at their checkouts.

Please Note: The developer documentation in Vipps MobilePay describes using webhooks instead of polling for payment statuses in the ePayment API. Polling however, is still possible and a valid way to follow the payment status just as it is today in MobilePay PoS. However, it will not be possible to detect user check-in with polling.

Checkout has QR scanning capabilities

This is our recommended flow. If the merchant has the possibility to scan a QR code at their checkouts, they can use the 'Merchant Scan' approach. Before the payment is initiated the merchant scans a QR on the customer phone which will contain the customer info needed to initiate the payment. The payment is then initiated with the userFlow parameter set to "PUSH_MESSAGE" together with the personalQr parameter set to the full content of the QR scanned. This solution removes the need for merchant QR codes as MobilePay PoS solutions uses today. See the In-store payments example.

Checkout has customer facing screens

In this scenario, there is one solution simpler than all others. Here, the merchant doesn't need the customer information before they initiate the payment. They simply initiate the payment where the userFlow parameter is set to QR. Then, the response will contain a link to a dynamic QR code, which the checkout then downloads and shows on their customer facing screen. The user scans the QR and completes the payment flow. This flow is described in more detail in the ePayment API guide, where it also is shown how to specify the image format and size of the QR being created.

Checkout neither has QR scanners nor customer facing screens

In these scenarios, the PoS merchants must use static QR codes as stickers, as they do today. These QRs can work in two different ways.

The first option is where the QR code contains a link to a merchant website where the merchant will then ask for the customer info needed. This QR is referred to as a Merchant Redirect QR. See the Static QR directing to the merchant site for payment example.

The second option is called Merchant Callback QRs, and it resembles the way of using QRs in MobilePay PoS solutions today. When the QR is scanned by a customer, Vipps MobilePay will send a callback to an endpoint that is hosted by the merchant. The callback will contain a customerToken that is used to initiate the payment towards the customer. This is identical to the notification service solution offered for vending machines and similar unmanned checkouts in MobilePay PoS today. Polling for user check-in will not be an option as in MobilePay PoS today, and hence it is required to support callbacks. See the In-store using Merchant Callback QR example.

Please note: It will be possible to migrate all the existing QRs to the new solution such that the merchants do not have to replace the QRs they already have.

Migration guide to Merchant Callback QRs

To make the transition from MobilePay PoS to the ePayment API with Merchant Callback QRs, the merchant must do the following:

  • Host an API with an endpoint that Vipps MobilePay can send callbacks to.
  • Migrate existing QRs. There exists an endpoint specifically for migrating MobilePay QRs. This endpoint will take the beaconId and posName of the current QR, and register it as a Merchant Callback QR. This will make the old QRs work after the switch to the common platform. The endpoint is: Create callback QR code.
  • Subscribe to the user.checkin.v1 event for all merchant serial numbers (i.e., stores). This will trigger Vipps MobilePay to send these events whenever a customer has scanned one of your QRs. The callback contains the merchant-serial-number; as well as, the merchantQrId (equal to the beaconId in MobilePay PoS). This information will distill down to what checkout the customer has checked in to. See documentation on how to implement webhooks
  • Implement the ePayment API integration to initiate and handle the payment flow. The next sections of this page will help sketch out the differences from the current MobilePay PoS API and the ePayment API.

PoS and ePayment endpoints

OperationMobilePay PoSePayment
PoS managementPOST/GET/DELETE /v10/pointofsalesN/A
Initiate PaymentPOST:/v10/paymentsPOST:/epayments/v1/payments
Initiate Prepared paymentPOST:/v10/payments/prepareN/A (For loyalty, see Loyalty at POS)
Query PaymentGET:/v10/payments/{paymentid}GET:/epayments/v1/payments/{reference}
Query Active PaymentsGET /v10/paymentsN/A
Query payment logN/AGET:/epayments/v1/payments/{reference}/events
Capture PaymentPOST:/v10/payments/{paymentid}/capturePOST:/epayments/v1/payments/{reference}/capture
Cancel PaymentPOST:/v10/payments/{paymentid}/cancelPOST:/epayments/v1/payments/{reference}/cancel
Refund PaymentPOST:/v10/refundsPOST:/epayments/v1/payments/{reference}/refund
Lookup a refundGET:/v10/refunds/{refundid}GET:/epayments/v1/payments/{reference}

Authentication and headers

See:

MobilePay PoSePayment
Authorization (POST:/connect/token)Authorization (POST:/accesstoken/get)
X-MobilePay-Client-System-VersionVipps-System-Version (see HTTP headers)
N/AVipps-System-Name (see HTTP headers)
N/AVipps-System-Plugin-Name (see HTTP headers)
N/AVipps-System-Plugin-Version (see HTTP headers)
X-MobilePay-Merchant-VAT-NumberN/A
X-MobilePay-Idempotency-KeyIdempotency-Key (see Idempotency)
N/AOcp-Apim-Subscription-Key
N/AMerchant-Serial-Number

Initiate Payment

See:

MobilePay PoSePayment
amountamount (currency, value)
currencyCodeApplied in amount
orderIdpaymentDescription​
plannedCaptureDelayN/A
posIdN/A
restrictions (debitCardDisallowed, creditCardDisallowed)N/A
merchantPaymentLabelN/A
N/Acustomer (phoneNumber)
N/AcustomerInteraction ("CUSTOMER_PRESENT")
N/ApaymentMethod (type "WALLET")
N/Areference
N/AuserFlow ("PUSH_MESSAGE" "QR")
N/AqrFormat (format, size)
Response
paymentIdreference (set in paymentInitiation)

Query Payment

See:

MobilePay PoSePayment
paymentIdreference
Response
orderIdreference
amountamount (currency, value)
currencyCodeApplied in amount
statusstate
N/Aaggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
N/ApaymentMethod (type)
loyaltyIdsprofile (sub) (see What is the sub?)
N/ApspReference

N/A: posId, restrictions (debitCardDisallowed, creditCardDisallowed), merchantPaymentLabel, plannedCaptureDelay, customerToken, customerReceiptToken, paymentExpiresAt, partialCapturePossible, pollDelayInMs

Capture, Cancel and Refund Payment

See:

MobilePay PoSePayment
paymentIdreference
amountmodificationAmount (currency, value) not applicable for cancel
Response
N/Aamount (currency, value)
N/Astate
N/Aaggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount)
refundId only applicable for refundpspReference
N/Areference

Test environment

The test environment is called Merchant Test (MT) and is now open for test. MT currently only allows Norwegian phone numbers and merchants, but you can test the API and payment flow. Please see the details of limitations of the test environment.

You need credentials to get access to MT. In order to receive those, you just need to sign up as partner, and we'll e-mail you the information you need to get started. This is also needed even though you are an existing MobilePay integrator, since we need your information registered on our new joint platform.

Help us improve our documentation

Did you find what you were looking for?