In-store using merchant callback QR

There is an issue that the test app requires you to go back to the home screen after scanning the QR. There, you will see the payment request when it is initiated. This is not an issue in production.

Before implementing this flow, please see the recommended flows in-store payments flow and in-store payments with customer club.

In this flow, a user pays by scanning a QR with their Vipps or MobilePay app. The merchant gets their ID and sends a payment request to them through the app. Optionally the merchant can also get the phone number of the user and enroll them in their loyalty program.

Prerequisites

Merchant callback QR

Generate a merchant callback QR code.

How to create a merchant callback QR code

The QR code contains an ID that connects it to a specific POS or cash register in your store.

Specify merchantQrId is arbitrary. You can use specify the value here to use as the identifier for a QR code.

PUT:/qr/v1/merchant-callback/{merchantQrId}

curl -X POST '/qr/v1/merchant-callback/{merchantQrId}' \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
--data '{
    "locationDescription": "pos_2345",
    "category": "IN_STORE",
}'

Details

Step 1: The customer scans the QR

When the customer scans the QR, your system will receive a notification that the customer is ready to pay with Vipps MobilePay. The notification will contain a token the merchant can use to start a payment.

(Optional) Step 2: Get the customer's phone number

The customer token can be used to get the phone number of the customer if needed.

How the token exchange works

Please use the Customer token exchange endpoint to get the phone number from the customer token.

For example:

POST:/v1/exchange/customer

curl -X POST https://apitest.vipps.no/qr/v1/exchange/customer \
-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 '{
    "customer": {
      "customerToken" : "qwieyiqwyeiuqwyeiuywqiueyiwquy"
    },
}'

Example response:

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

(Optional) Step 3: Enroll the customer

If the customer is not a member of the loyalty program, you can request to enroll them by using the Login flow to gather consent from the customer. The steps needed to get consent from the user are explained in detail there. The merchant initiated login flow will send a push to the user, and once the user has finished the flow, they will be ready to pay.

Step 4: Send the payment request

Use the token to send the customer a Create Payment request.

Detailed example of payment request

After getting your access token, send the API request for create payment.

Specify "userFlow": "PUSH_MESSAGE" to send the payment to the user's app. Attach the receipt simultaneously.

Specify "customerInteraction": "CUSTOMER_PRESENT".

For example:

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": 10000,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "customerToken": "insert customerToken here"
  },
  "receipt":{
    "orderLines": [
      {
        "name": "socks",
        "id": "line_item_1",
        "totalAmount": 10000,
        "totalAmountExcludingTax": 8000,
        "totalTaxAmount": 2000,
        "taxRate": 2550,
        "unitInfo": {
          "unitPrice": 4000,
          "quantity": "2",
          "quantityUnit": "PCS"
        },
      },
    ],
    "bottomLine": {
      "currency": "NOK",
      "posId": "pos_122",
      "receiptNumber": "0527013501"
    },
  },
  "reference": 2486791679658155992,
  "userFlow": "PUSH_MESSAGE",
  "returnUrl": "http://example.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Purchase of socks"
}'

Step 5: The 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.

To determine that the user has authorized the payment, you can get notifications via the Webhooks API and/or poll for the status.

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

Step 6: Capture the payment

Capture the payment with the POST:/epayment/v1/payments/{reference}/capture API request. Confirm that the request was successful.

Detailed example of payment capture

To capture the payment, send the POST:/epayment/v1/payments/{reference}/capture request with the value set to the amount of the purchase.

For example:

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/capture \
-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 '{
  "modificationAmount": {
    "currency": "NOK",
    "value": 10000
  }
}'

Sequence diagram

Sequence diagram for only payment

Sequence diagram for complete flow including phone number lookup, customer enrollment and payment.

Next steps

Review some related pages:

• Merchant Callback QR codes
• ePayment API guide