Skip to main content

Static QR directing to the app for payment

Vipps Available for Vipps.

MobilePay Available for MobilePay in Finland. Expected availability in Denmark is March 2024.

This flow uses a QR code that is posted on the vending machine. The QR directs the user to the payment screen in their Vipps or MobilePay app.

QR direct to payment

When to use

This QR code can be used when you don't have a screen, and it's not possible to present the dynamic one-time payment QR.

Prerequisites

Merchant Callback QR

Generate a merchant callback QR code.

How to create a merchant callback QR code

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

Here is an example HTTP PUT:

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

{
"locationDescription": "pos_2345",
}

Registered webhooks

Register a webhook to alert you when your payment requests are approved and your QR codes are scanned.

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", "user.checked-in.v1"]
}

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

The payload from this webhook 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
}

The payload from the QR webhook will be in this form:

{
"customerToken": "wbA8ceVRKkoYiQAVELHeFCC3Sn5dtNCvvEtVPiOT77j6wx7uR965AG6Q+q0ATP4=",
"merchantQrId": "d8b7d76d-49aa-48b8-90c6-38779372c163",
"msn": "12345",
"initiatedAt": "2023-10-06T10:45:40.3061965Z"
}

Details

A Vipps MobilePay QR code is posted on the vending machine.

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 amount should be the max amount of the vending machine products. After reservation, the amount of the selected product must be captured, and the remaining amount must be released.

Step 1: Initiate a payment request

When the user scans the QR code, send a Create Payment request.

Detailed example

Specify the amount of the most expensive item in your vending machine so that any selection they make can be successful.

Specify "customerInteraction": "CUSTOMER_PRESENT". Specify "userFlow": "WEB_REDIRECT" to redirect user to the app.

Here is an example HTTP POST:

POST:/epayment/v1/payments

With body:

{
"amount": {
"value": 5000,
"currency": "NOK"
},
"paymentMethod": {
"type": "WALLET"
},
"customer": {
"customerToken": "wbA8ceVRKkoYiQAVELHeFCC3Sn5dtNCvvEtVPiOT77j6wx7uR965AG6Q+q0ATP4="
},
"customerInteraction": "CUSTOMER_PRESENT",
"reference": 2486791679658155992,
"userFlow": "PUSH_MESSAGE",
"paymentDescription": "Vending machine purchase"
}

Step 2: 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 get confirmation that payment was approved, monitor your webhooks.

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

Step 3. Capture the amount due

After the selection is made, determine how much the customer owes and provide a receipt. After final amount is confirmed, do a partial capture.

Check the status of the captured payment.

Detailed example

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

With body:

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

Step 4 Cancel remaining amount

Release the remaining amount from the reservation with a cancel.

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

Step 5. Add a receipt

Attach a receipt with the amount paid.

Detailed example

Here is an example HTTP POST:

POST:/order-management/v2/{paymentType}/receipts/{orderId}

For paymentType, use eCom for eCom or ePayment payments. For orderId, use the chargeId of the charge.

Body:

{
"orderLines": [
{
"name": "Fanta",
"id": "21231211",
"totalAmount": 3000,
"totalAmountExcludingTax": 2250,
"totalTaxAmount": 750,
"taxPercentage": 25,
},
],
"bottomLine": {
"currency": "NOK",
"posId": "vending_machine_12345"
}
}

Sequence diagram

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

Help us improve our documentation

Did you find what you were looking for?