How to: Setup and use Vipps E-Payments integration in POS

1 General information
2 Setup
3 Application builder
4 Financial App
- 4.1 Create Vipps Incoming payment option
5 Pos App
- 5.1 Create Vipps agreement
- 5.2 Setup Vipps agreement webhook
- 5.3 Create Vipps sales unit
- 5.4 Setup merchant QRs
- 5.5 Setup agent profile
6 Payment flow
7 View payment event log flow
8 Refund payment flow
9 How to test Vipps webhook locally
10 Video demo

General information

Only production environments (prod2, prod3, prod5 and prod6) are sat up to use Vipps E-payments in production mode. Other deployments uses test mode.

Setup

Application builder

Make sure that feature [Payments.Basic] is turned on for tenant (this is feature of new Payments microservice which is responsible of handling of payments, particualry Vipps payments).

Financial App

Open [Financial] app.

Create Vipps Incoming payment option

Go to [Incoming Payment Options] page ({base address}/financial/app/#/incoming-payment-options) and create new incoming payment option with [Payment type] = Vipps E-payment and [Quick access avaliable] checked.

Then make sure that payment option is enabled.

Pos App

Open [Pos] app.

Create Vipps agreement

Go to [Vipps Agreements] page ({base address}/pos/app/#/vipps-agreements) and press [+] button. In editor enter display name of new Vipps agreement and press [Set API Keys] button. I then enter Api keys (client_id, client_secret and Ocp-Apim-Subscription-Key). Then press [Save].

Note: api keys are stored in db in crypted way so they will be not availalbe on next edit and if user will want to change them - they need to be entered again.

Setup Vipps agreement webhook

On [Vipps agreements] page with selected Vipps agreement press [Register webhook] button.

Create Vipps sales unit

Go to [Vipps Sales Units] page ({base address}/pos/app/#/vipps-sales-units) and press [+] button. In opened dialog window select current organizational unit.

Then will be opened edit window when need to be defined Vipps Sales Unit display name and selected Vipps agreement (for example created on previous steps).

Also need to be entered Merchant Serial Number of Vipps sales unit.

Setup merchant QRs

On [Vipps sales units] page with selected Vipps sales unit press [Merchant callback Qrs] button.

Then on popup press [Sync with Vipps] button in order to fetch arleady created webhooks from Vipps. Also in this popup it is possible to create new Merchant callback QR or convert existing MobilePay QR to Merchant callback QR. Also it is possible to view QR image.

Setup agent profile

Go to [Agent Instances] page ({base address}/pos/app/#/agentInstances) and select one of agent instances in grid (for example NoAgent). Then press [View agent profiles] button.

Select one of agent profiles and press [Edit] button. In opened window select Vipps Sales unit and one of its Merchant callback QRs.

Save changes and select changed agent profile for current session.

Payment flow

Payment flow will be demonstrated by create sale.

Go to [New sale] page ({base address}/pos/app/#/new-sale) and press [Start new sale] button.

Add some products to basket.

Then press [Vipps] button (payment option that was created during setup).

Payment screen will be opened. Uncheck [Email invoice] checkbox (for simplicity) and press [Pay]

Customer identification dialog will be opened.

There are 2 options: enter customer phone manually or scan merchant callback QR previously assigned to agent profile and then window will be closed automatically and payment will be started.

After that there are 2 options:

A - Unhappy flow. Before user will approve payment on their phone press [Abort] button.

Then payment will be aborted.

B - Happy flow. Customer will get push notification about paymen on their phone with information: "[Tenant name]: payment for sale [Sale identifier]". Approve payment in customer phone. Payment will be captured and completed and in case if payment amount will be enough to complete sale - sale will be completed automatically.

View payment event log flow

Go to [Sales] page ({base address}/pos/app/#/processed-sales) and press [View] button on latest sale selected. [View sale] page will be opened.

On [View sale] page find [Financial] section and press [log] icon for Vipps payment

Vipps E-Payment event log will be displayed

Refund payment flow

On [View sale] page press [Refund] button.

On opened popup press [Select all] and then [Refund]

Return items will be added to basket.

On [more] menu press [Refund original sale payment] item.

On selected popup select payment to refund and amount to refund, then press [Ok].

Refund payment will be registered.

It is possible to press [log] icon for it to display event log with refund record.

How to test Vipps webhook locally

For debug purposes may be need to test Vipps webhook locally. For that we need somehow expose HTTP url to internet and register webhook using it.

Following chnages need to be made in Payments microservice app.config:

added following key to KeyValueSettings section : <add key="VippsTestWebhookUrl" value="<https://crs-vipps-webhook-test.loca.lt>" /> (value https://crs-vipps-webhook-test.loca.lt is used as example);
Make sure that setting VippsEPaymentIsTestMode is set to “true”, in other case VippsTestWebhookUrl setting will be ignored.

Need to be installed globally on workstation following npm package https://www.npmjs.com/package/localtunnel

After start of services need to be started following command in command prompt :

lt --subdomain crs-vipps-webhook-test --port 9000

Answer will be: your url is: https://crs-vipps-webhook-test.loca.lt and after that 9000 port will be available from internet by url https://crs-vipps-webhook-test.loca.lt which will be enough for setup and test VIPPS webhook.

NOTE: lifetime of thus local tunnel is not defined but by my experiese it is turned off each time when debug services are stopped so each time after restart services locally local tunnel command need to be runned again.