Skip to main content

Dynamic QR directing to the app for payment

This flow uses a one-time payment QR (i.e., a dynamic QR) that is shown on a screen. The QR directs the customer to the Vipps MobilePay app, where they authorize the payment.

One-time payment QR

When to use​

This is the preferred flow when it's possible to show a dynamic QR code on the vending machine.

Use this flow when you have a screen connected.

Prerequisites​

Screen​

You need a screen to display the one-time QR.

Webhooks for ePayment events​

Register a webhook to alert you when your payment requests are approved.

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.

Here is an example HTTP POST:

POST:/webhooks/v1/webhooks

{  
    "url": "https://example.com/mystore_website_backend",
    "events": ["epayments.payment.authorized.v1"]
}

Use the secret to authenticate the message with HMAC. For examples, see Webhooks API: Request authentication.

The payload from the ePayment webhooks will be in this form:

{
    "msn": "123456",
    "reference": "24ab7cd6ef658155992",
    "pspReference": "1234567891",
    "name": "AUTHORIZED",
    "amount":
    {
        "currency": "NOK",
        "value": 35000
    },
    "timestamp": "2023-08-14T12:48:46.260Z",
    "idempotencyKey": "49ca711a9487112e1def",
    "success": true
}

Note that the payload of the webhook depends on the originating service, in this case the ePayment API.

Details​

A one-time payment QR code is presented on the vending machine. The QR code is a dynamic representation of the payment URL, and the customer needs to scan the QR code within 5 minutes.

Step 1: Generate a dynamic QR code and payment request​

When the customer selects a product, generate the payment request with a dynamic QR code. Display the QR on the screen.

Detailed example

To generate the dynamic QR code and associated payment request, specify "userFlow": "QR". You may also specify the qrFormat and size for the QR.

Specify "customerInteraction": "CUSTOMER_PRESENT".

You can also include a receipt at this time.

Since the customer will scan from their phone, you don't need their phone number. This payment command can do an app-switch and open their Vipps MobilePay app with the payment request.

Here is an example HTTP POST:

POST:/epayment/v1/payments

With body:

{
  "amount": {
    "value": 42924,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customerInteraction": "CUSTOMER_PRESENT",
  "receipt":{
    "orderLines": [
      {
        "name": "Ear buds",
        "id": "21231211",
        "totalAmount": 42924,
        "totalAmountExcludingTax": 32193,
        "totalTaxAmount": 10731,
        "taxPercentage": 25,
      },
    ],
    "bottomLine": {
      "currency": "NOK",
      "posId": "vending_machine_12345"
    },
   "receiptNumber": "0527013501"
  },
  "reference": 2486791679658155992,
  "userFlow": "QR",
  "returnUrl": "http://example.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Ear buds",
  "qrFormat": {
    "format": "IMAGE/SVG+XML",
    "size": 1024
  }
}

Step 2: The customer authorizes the payment​

When the customer scans the QR code, they go directly to the payment screen on their phone, where they can approve the payment.

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

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

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

Step 3: Capture the payment​

Capture the payment and confirm that it was successful.

Detailed example

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

With body:

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

Sequence diagram​

Sequence diagram for the vending machine flow with dynamic QR directing to the app for payment.