Migrating Point of Sale to new common platform
Disse sider er for udviklere, der migrerer til den nye API-platform. Kontakt din kasse- eller systemleverandør for at tjekke at de er klar til den nye integration.
As part of the transition to a joint Vipps MobilePay platform, MobilePay PoS will be replaced by the Vipps MobilePay ePayment API.
On this page, you will find a comparison between the existing MobilePay PoS API and the ePayment API.
Authentication and management
We will have a joint authentication solution across our API platform and introduce a Management API to retrieve merchant data. For more details, see the Authentication, Management and Test page.
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.
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.
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
beaconIdandposNameof 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.checked-in.v1event 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 themerchant-serial-number; as well as, themerchantQrId(equal to thebeaconIdin MobilePay PoS). This information will distill down to what checkout the customer has checked in to. See more information in the QR API Webhooks section - 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
| Operation | MobilePay PoS | ePayment |
|---|---|---|
| PoS management | POST/GET/DELETE /v10/pointofsales | N/A |
| Initiate Payment | POST:/v10/payments | POST:/epayment/v1/payments |
| Initiate Prepared payment | POST:/v10/payments/prepare | N/A (For loyalty, see Loyalty at POS) |
| Query Payment | GET:/v10/payments/{paymentid} | GET:/epayment/v1/payments/{reference} |
| Query Active Payments | GET /v10/payments | N/A |
| Query payment log | N/A | GET:/epayment/v1/payments/{reference}/events |
| Capture Payment | POST:/v10/payments/{paymentid}/capture | POST:/epayment/v1/payments/{reference}/capture |
| Cancel Payment | POST:/v10/payments/{paymentid}/cancel | POST:/epayment/v1/payments/{reference}/cancel |
| Refund Payment | POST:/v10/refunds | POST:/epayment/v1/payments/{reference}/refund |
| Lookup a refund | GET:/v10/refunds/{refundid} | GET:/epayment/v1/payments/{reference} |
Authentication and headers
See:
| MobilePay PoS | ePayment |
|---|---|
Authorization (POST:/connect/token) | Authorization (POST:/accesstoken/get) |
X-MobilePay-Client-System-Version | Vipps-System-Version (see HTTP headers) |
| N/A | Vipps-System-Name (see HTTP headers) |
| N/A | Vipps-System-Plugin-Name (see HTTP headers) |
| N/A | Vipps-System-Plugin-Version (see HTTP headers) |
X-MobilePay-Merchant-VAT-Number | N/A |
X-MobilePay-Idempotency-Key | Idempotency-Key (see Idempotency) |
| N/A | Ocp-Apim-Subscription-Key |
| N/A | Merchant-Serial-Number |
Initiate Payment
See:
| MobilePay PoS | ePayment |
|---|---|
amount | amount (currency, value) |
currencyCode | Applied in amount |
orderId | paymentDescription |
plannedCaptureDelay | N/A |
posId | N/A |
restrictions (debitCardDisallowed, creditCardDisallowed) | N/A |
merchantPaymentLabel | N/A |
| N/A | customer (phoneNumber) |
| N/A | customerInteraction ("CUSTOMER_PRESENT") |
| N/A | paymentMethod (type "WALLET") |
| N/A | reference |
| N/A | userFlow ("PUSH_MESSAGE" "QR") |
| N/A | qrFormat (format, size) |
| Response | |
paymentId | reference (set in paymentInitiation) |
Query Payment
See:
| MobilePay PoS | ePayment |
|---|---|
paymentId | reference |
| Response | |
orderId | reference |
amount | amount (currency, value) |
currencyCode | Applied in amount |
status | state |
| N/A | aggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount) |
| N/A | paymentMethod (type) |
loyaltyIds | profile (sub) (see What is the sub?) |
| N/A | pspReference |
N/A: posId, restrictions (debitCardDisallowed, creditCardDisallowed), merchantPaymentLabel, plannedCaptureDelay, customerToken, customerReceiptToken, paymentExpiresAt, partialCapturePossible, pollDelayInMs
Capture, Cancel and Refund Payment
See:
| MobilePay PoS | ePayment |
|---|---|
paymentId | reference |
amount | modificationAmount (currency, value) not applicable for cancel |
| Response | |
| N/A | amount (currency, value) |
| N/A | state |
| N/A | aggregate (authorizedAmount, cancelledAmount, capturedAmount, refundedAmount) |
refundId only applicable for refund | pspReference |
| N/A | reference |
Test environment
The test environment is called Merchant Test (MT) and is now open for test. MT currently only allows Norwegian phone numbers, currency and merchants, but you can test the API and payment flow. Please see the details of limitations of the test environment.
Management API and Report API is not available in MT and can only be tested in production.
In order to request access to the test environment, please use the following links:
We will e-mail you with the information you need to get started. This is also needed even though you are an existing MobilePay integrator or merchant, since we need your information registered on our new joint platform.