How to: Setup and use Vipps E-Payments integration in POS
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 npm: 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.
Video demo