App flow recommendations

We recommend that you use universal links (Apple)/asset links (Android) for your app integration to offer a smooth and secure payment experience regardless of the flow is initiated on a mobile or desktop device.

Universal/Asset links

We recommend that you use the universal links/asset links (starting with https) as they contain built-in logic to handle both desktop and mobile flow. They are more secure than the deep link flow and provide a better user experience.

• On Apple, use universal links.
• On Android, use asset links.

The universal/asset link is supplied as default when initiating payments or agreements through the Recurring or eCom API. For the ePayment API, specify the USER_FLOW as WEB_REDIRECT.

On desktop the universal/asset link will display the landing page where user can input their phone number.

On mobile the universal/asset link will ensure automatic app-switch to the Vipps or MobilePay app, if these are installed on the device. If the app is not installed, the landing page will be opened in the browser where user can enter their phone number.

Deep link flow

It is possible to perform manual handling of the interaction between the user's app and the Vipps MobilePay backend, but this is not recommended.

warning

For the ePayment API, please consider WEB_REDIRECT alternative as this is safer and provides fallback to the landing page in case the Vipps or MobilePay app can't be found.

We do not recommend deep-linking with NATIVE_REDIRECT for app to app implementations. NATIVE_REDIRECT should only be used if the merchant doesn’t have a web presence at all. WEB_REDIRECT has enhanced security and improved cross-platform compatibility.

If the payment is initiated in a native app, it is possible to explicitly force a vipps:// URL by sending the optional isApp or NATIVE_REDIRECT parameter in the initiate call:

• userFlow: WEB_REDIRECT or isApp: false (or not sent at all): The URL is https://, which handles everything automatically for you. The phone's operating system will know, through "universal linking", that the https://api.vipps.no URL should open the app, and not the default web browser. Note, in some cases, this requires the user to approve that the app is opened, but this is usually only the first time.
• userFlow: NATIVE_REDIRECT or isApp: true: The URL is for a deeplink, for forced app-switch to Vipps, with vipps://. Note, in our test environment (MT), the scheme is vippsMT://

The flow is as follows:

1. Initiate the payment:eCom API or Recurring API with isApp: true. For the ePayment API, use the NATIVE_REDIRECT.
2. In response, we return a deeplink URL in the vipps:// format.
3. Use the deeplink URL to invoke Vipps or MobilePay. (Note, always use this URL exactly as it is sent from Vipps MobilePay.)
4. The Vipps or MobilePay app opens automatically, without the user having to click OK or Accept.
5. The user accepts (or rejects) the payment request in the app.
6. The rest of the flow continues as a regular payment flow.

note

The user must always be sent directly to the deeplink. Rewriting the deeplink URL in any way may break the payment process.

The deeplink URL is only valid for five minutes. Attempts at using it after that will result in a timeout and an error.

See:

• Timeouts
• Can I send a payment link in an SMS, QR or email?

Important information when using isApp and NATIVE_REDIRECT

info

Using isApp and NATIVE_REDIRECT comes with some extra responsibility:

• The merchant's native app must ensure that the user's phone can open the vipps:// deeplink, because the landing page will not be shown to the user, and it will therefore not be possible to enter a phone number and pay with Vipps MobilePay on another device.
• If the Vipps or MobilePay app is not installed on the device "nothing will happen", and the user will not be able to pay.
• Vipps MobilePay requires a minimum version of the phone's operating system. At the time of writing this is iOS 12 (from 2018) or Android 6 (from 2015). If the user has an older version of the operating system, Vipps MobilePay cannot be used. The merchant must keep track of this by checking the Apple App Store and Google Play.
• If the deep link is used in an embedded web browser, such as Instagram or Facebook, the vipps:// URL will not work, since the embedded browser does not know what to do with it. The user will get an error from the embedded browser, or "nothing will happen".

Your app must handle failing redirects to the deep link.

If Vipps or MobilePay is not installed on the user's device, inform the user that Vipps or MobilePay is not installed, or use the following links to redirect the user to download the app:

App store

Vipps: https://apps.apple.com/us/app/vipps/id984380185

MobilePay DK: https://apps.apple.com/us/app/mobilepay/id624499138

MobilePay FI: https://apps.apple.com/us/app/mobilepay/id768172577

Google Play Store

Vipps: https://play.google.com/store/apps/details?id=no.dnb.vipps

MobilePay DK: https://play.google.com/store/apps/details?id=dk.danskebank.mobilepay

MobilePay FI: https://play.google.com/store/apps/details?id=fi.danskebank.mobilepay

Example responses

Example: Response body for isApp:false (or not sent at all):

{
  "orderId": "acme-shop-123-order123abc",
  "url": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJraWQiOiJqd3RrZXkiLC <truncated>"
}

Example: Response body for isApp:true, with a forced app-switch to Vipps:

{
  "orderId": "acme-shop-123-order123abc",
  "url": "vipps://?token=eyJraWQiOiJqd3RrZXkiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiO <truncated>"
}

FAQ

Why are universal/asset links better than deep links?

Universal links/asset links are a type of deep link which provide more security. They are bound to the mobile application and require two-way authentication.

What happens if the user doesn't have the app installed?

• Using universal link: userFlow: WEB_REDIRECT or isApp:false (or not sent at all): The landing page will be shown, and the user can enter a phone number and pay on a device with the Vipps or MobilePay app installed.
• userFlow: NATIVE_REDIRECT orisApp: true: The user will get an error message saying that the link can not be opened or, depending on the native app, nothing will happen. Please check Important information when using isApp and NATIVE_REDIRECT.

What happens if the user doesn't have an active Vipps or MobilePay account?

If the user doesn't have an active Vipps or MobilePay account, yet they insert their phone number on the landing page, they will receive an error stating that they can't continue.

This also is displayed if the user doesn't reach the minimum age requirements for a payment.

Vipps

MobilePay