In-store payments

This is the recommended flow for in-store payments. This solution is a combination of the personal QR codes in the Vipps or MobilePay app and the ePayment API.

Prerequisites

Scanner (Optional)

If you have a 2D QR code scanner, you can allow your customers to scan their own personal QR codes as part of the checkout process. This lets you identify the customer with asking for their phone number.

Webhooks for ePayment events

Register a webhook to alert you when your payment requests are approved. See the Webhooks API guide for more details.

What are webhooks?

When changes happen to your payment request, events are triggered (for example: Authorized, Terminated, Aborted, Cancelled, Expired, and many more).

You can register to receive these events, which is useful for programming an appropriate and quick response.

The webhook will send a message to your web server at the URL you specify.

See the Webhooks API guide for more details.

Details

Step 1: Ask if the customer has Vipps or MobilePay

If they have Vipps/MobilePay on their phone, you can continue. Otherwise, you'll not use this flow.

Step 2: Get their Vipps/MobilePay ID

If you have a 2D QR code scanner, scan their Vipps/MobilePay personal QR. If you don't have a scanner, just ask them for the phone number. Save this phone number for use in the later steps, so you don't need to ask them for it again.

Vipps

MobilePay

How it works

This can happen in two ways:

• Customer-facing scanner - The store will have a permanent customer-facing scanner and customers can scan their personal Vipps/MobilePay QR code at any time.
• Cashier scanner - The customer's personal QR code is scanned by the cashier using a wired scanner. This could happen while the cashier is scanning wares or immediately before the payment.

When you scan the customer's personal QR code, you can use it to get their phone number.

Please use the Personal QR exchange endpoint to get the phone number from the personal QR code.

For example:

POST:/v1/exchange

curl -X POST https://apitest.vipps.no/qr/v1/exchange \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-d '{
    "qrCode": "https://qr.vipps.no/p/qwjhewqhueheuqwhuqwhe",
}'

Example response:

{
"msisdn": "4712345678",
"timestamp": 1634025600,
"version": "2.0"
}

Step 3: Add the products to be purchased

Add the products that the customer wants to buy in the POS system.

Vipps

MobilePay

If you didn't use a scanner to get the identity, you can ask for the customer's phone number and enter it manually.

Vipps

MobilePay

Step 4: Send a payment request

Send a payment request to the customer.

Detailed example

You already have the customer's phone number, so you don't need to ask for it. Just provide a button in your user interface to allow the cashier to send the payment request.

Your system can send the payment request by using the createPayment endpoint.

Set userFlow to PUSH_MESSAGE. This will send a push directly to the customer. Attach the receipt simultaneously.

Here is an example HTTP POST:

POST:/epayment/v1/payments

With body:

{
  "amount": {
    "value": 49800,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "personalQr": "https://qr.vipps.no/p/qwjhewqhueheuqwhuqwhe"
  },
  "receipt":{
    "orderLines": [
      {
        "name": "Orange hoodie",
        "id": "hoodie1234",
        "totalAmount": 29900,
        "totalAmountExcludingTax": 22425,
        "totalTaxAmount": 7475,
        "taxPercentage": 25,
      },
      {
        "name": "White T-shirt",
        "id": "tshirt1234",
        "totalAmount": 19900,
        "totalAmountExcludingTax": 14925,
        "totalTaxAmount": 2975,
        "taxPercentage": 25,
      },
    ],
    "bottomLine": {
      "currency": "NOK",
      "posId": "Butikken-23412",
      "receiptNumber": "0527013501"
    },
  },
  "reference": 2486791679658155992,
  "userFlow": "PUSH_MESSAGE",
  "returnUrl": "http://example.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Payment to Butikken"
}

Note that, if you didn't use a scanner, your customer field would specify the phone number, instead of the personalQr.

  "customer": {
    "phoneNumber": 4712345678
  },

Step 5: Customer authorizes the payment

The payment request will appear in the customer's Vipps or MobilePay app, where they can select to pay or cancel.

Vipps

MobilePay

To get confirmation that payment was approved, monitor your webhooks.

What are webhooks?

When changes happen to your payment request, events are triggered (for example: Authorized, Terminated, Aborted, Cancelled, Expired, and many more).

You can register to receive these events, which is useful for programming an appropriate and quick response.

The webhook will send a message to your web server at the URL you specify.

See the Webhooks API guide for more details.

Once the payment is approved, update the status in your system.

Step 6: Register the payment

Register the payment in your POS system.

Vipps

MobilePay

Step 7: Capture the payment

Capture the payment and confirm that it was successful.

Detailed example

POST:/epayment/v1/payments/{reference}/capture

With body:

{
  "modificationAmount": {
    "value": 49800,
    "currency": "NOK"
  }
}

Sequence diagram

Sequence diagram for the standard in-store payment.