In-store payments with customer club

This flow makes a great product-market fit for retail stores that want to combine loyalty with payments. It's a great way to improve the payment experience for customers and simplify the process of adding customers to the merchant loyalty club.

The solution is a combination of the personal QR codes in the Vipps or MobilePay app, along with the Login API and ePayment API.

The following describes the process at a high level.

tip

With a 2D QR code scanner, your customers to scan their own personal QR codes as part of the checkout process. Then, you don't need to ask for their phone number.

Details

Step 1: Get the customer's 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.

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 2: Check membership

Check the customer's membership status in your internal system by using the phone number you received in the previous step.

Step 3: Request membership (if they are not a member)

If the customer is not a member of the loyalty program, request to enroll them by using the Login API.

You already have their phone number, so just provide a button in your user interface to allow the cashier to initiate the login.

Pressing the button will trigger a Login flow to gather consent from the customer. The steps needed to get consent from the user are explained in detail there. The CIBA flow will send a push to the user, and once the user has finished the flow, it should be reflected in the POS.

When this login flow is completed, the customer will be enrolled in the loyalty program.

Vipps

MobilePay

See Merchant initiated login for a detailed example.

Step 4: Add the products to be purchased

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

Step 5: Send a payment request

After membership status has been determined and all articles have been scanned, send a payment request to the customer.

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.

Detailed example for payment request

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

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

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": 239900,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "personalQr": "https://qr.vipps.no/p/qwjhewqhueheuqwhuqwhe"
  },
  "receipt":{
    "orderLines": [
      {
        "name": "winter jacket",
        "id": "jacket1234",
        "totalAmount": 239900,
        "totalAmountExcludingTax": 179925,
        "totalTaxAmount": 59975,
        "taxRate": 2550,
        "discount": 80000
        "unitInfo": {
          "unitPrice": 319900,
          "quantity": "1",
          "quantityUnit": "PCS"
        },
      },
    ],
    "bottomLine": {
      "currency": "NOK",
      "posId": "pos_122",
      "receiptNumber": "0527013501"
    },
  },
  "reference": 2486791679658155992,
  "userFlow": "PUSH_MESSAGE",
  "returnUrl": "http://example.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Winter jacket - blue"
}'

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 6. Customer approves 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 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 7: Capture the payment

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

Detailed example for payment capture

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": 239900
  }
}'

Sequence diagram

Sequence diagram for in-store payment with customer club.

Next steps

Now, you can go to the ePayment API guide and start experimenting.

👉 Go to the ePayment API guide