Skip to main content

Personal QR

View as Markdown (opens in a new tab)
Install AI tools

Give your assistant up-to-date guidance for our APIs, with our plugin or without it.

The plugin is still under development. See the AI tools page for details.

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps-developer@agent-toolkit

For troubleshooting, see the full instructions.

Implement customer identification using personal QR codes from the Vipps or MobilePay app for quick and secure user verification at physical points of sale.

Tip

For a visual walkthrough of the customer's experience with personal QR:

Overview​

If you have a QR code scanner, you can identify customers by scanning their personal QR code from the Vipps or MobilePay app. This enables quick, contactless in-store payments without manually entering phone numbers.

Vipps scan

Screenshot: The Vipps or MobilePay app displaying a personal QR code for the customer to present for scanning at a point of sale.

Scanner types​

Personal QR codes can be scanned in two ways:

Customer-facing scanner - A permanent scanner positioned for customer self-service. Customers scan their personal QR code at any time during checkout.

Cashier scanner - The cashier scans the customer's QR code using a wired scanner, either while scanning items or immediately before payment.

Either way, the scanner passes the QR code's content to your system as text: a URL that starts with https://qr.vipps.no/, such as https://qr.vipps.no/p/qwjhewqhueheuqwhuqwhe. Send this URL to the API exactly as you received it. Don't shorten it or pick values out of it.

Authorization​

All ePayment API requests must include a valid Bearer token in the Authorization header. See Authorization for how to obtain one.

Creating the payment​

Create a payment using POST:/epayment/v1/payments with the scanned URL. You don't need to look up the customer's phone number first. Use these settings:

  • Set userFlow to PUSH_MESSAGE to send the payment request directly to the customer's app
  • Set customerInteraction to CUSTOMER_PRESENT (required for regulatory compliance)
  • Set customer.personalQr to the scanned URL, unchanged
  • Optionally add receipt.orderLines to display purchase details in the app

Example request​

curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-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" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "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": 23920,
        "totalTaxAmount": 5980,
        "taxRate": 2500
      },
      {
        "name": "White T-shirt",
        "id": "tshirt1234",
        "totalAmount": 19900,
        "totalAmountExcludingTax": 15920,
        "totalTaxAmount": 3980,
        "taxRate": 2500
      }
    ],
    "bottomLine": {
      "currency": "NOK",
      "posId": "Butikken-23412",
      "receiptNumber": "0527013501"
    }
  },
  "reference": "2486791679658155992",
  "userFlow": "PUSH_MESSAGE",
  "returnUrl": "http://example.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Payment to Butikken",
  "customerInteraction": "CUSTOMER_PRESENT"
}'

Getting the customer's phone number​

If you need the customer's phone number for something else, such as a loyalty program, use the Personal QR exchange endpoint.

Note

In Denmark and Finland, the personal QR code is tokenized, so the exchange endpoint is the only way to get the phone number.

In Norway, the personal QR code currently contains the phone number in clear-text format (for example, https://qr.vipps.no/28/2/01/031/4712345678?v=1). Use the exchange endpoint there too, rather than reading the number from the URL, so your integration keeps working if Norway moves to tokenized QR codes.

Request​

POST:/qr/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"
}'

Response​

The response format differs depending on the QR code version:

Tokenized, version 2.0 (Denmark and Finland):

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

Clear-text, version 1.0 (currently Norway):

{
  "msisdn": "4712345678",
  "version": "1.0"
}

Response fields:

  • msisdn - The customer's phone number
  • timestamp - UTC timestamp (in seconds) indicating when the QR code was generated (only available in version 2.0)
  • version - The QR code version:
    • 2.0 - Tokenized format (Denmark and Finland)
    • 1.0 - Clear-text format (currently Norway, deprecated)

Troubleshooting​

Error: "The parameter PersonalQr is invalid"​

This error occurs when the QR code value cannot be recognized. The personalQr parameter only accepts QR codes from the Vipps or MobilePay app's personal QR section.

Common causes:

  • The scanned URL was shortened or changed before it was sent
  • A different type of QR code (merchant QR, promotional QR, or similar) was scanned instead
  • The scanner captured a QR code from something other than the customer's app

Solutions:

  • Verify that the request contains the whole scanned URL, unchanged
  • Ensure the customer is showing their personal QR code from within the Vipps or MobilePay app
  • Check that the scanner is reading the correct QR code and not others nearby

See also​

Last updated on