Skip to main content

App flow recommendations

VippsMobilePay

Always use universal links when integrating Vipps MobilePay payments into your app.

Universal links are required because they offer enhanced security, cross-platform compatibility, and automatic fallback handling.

If you believe deep links are necessary for your integration, please contact us before proceeding: developer@vippsmobilepay.com

Universal links help create a smoother user experience and typically lead to fewer integration issues over time.

Universal links are standard https:// URLs that the operating system recognizes as associated with the Vipps or MobilePay app. On Android, these are technically known as digital asset links, but for simplicity, we’ll use the term universal links to refer to both Apple and Android platforms.

When a user is redirected to an app link:

  1. On mobile with app installed: The OS recognizes the URL and automatically opens the Vipps Vipps or MobilePay MobilePay app.
  2. On mobile without app: The URL opens the landing page in the browser where users can enter their phone number.
  3. On desktop: The URL opens the landing page where users can enter their phone number to complete payment on their mobile device.

Universal links are the default for most APIs:

  • Recurring API: Universal links provided by default (omit isApp or set isApp: false)
  • eCom API: Universal links provided by default (omit isApp or set isApp: false)
  • ePayment API: Set userFlow: WEB_REDIRECT in your request

Example response:

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

Implementation guidelines​

Avoid blocking the app-switch

The most common mistake is breaking the automatic app-switch on mobile devices. Users on phones should always get the automatic app-switch and should never see the landing page.

✅ How it works correctly:

When the app link URL is opened normally (e.g., user clicks a button that opens the URL), the phone's operating system recognizes it as belonging to Vipps MobilePay and automatically switches to the app for seamless payment confirmation.

❌ What breaks the app-switch:

The automatic app-switch is blocked when the URL is opened in:

  • Browser redirects using window.location.href = url;
  • iframes
  • Web views
  • Embedded browsers (Instagram, Facebook, LinkedIn, etc.)

When the app-switch is blocked, users must manually enter their phone number, approve launching the app, and confirm the payment again — a tedious process that leads to poor user experience and lower conversion rates.

How to fix:

  • Use native navigation instead of web redirects
  • Open URLs directly with the system's default handler
  • Don't embed the payment flow in web views or iframes

Behavior if user doesn't have an active Vipps or MobilePay account​

With universal links, if the user enters their phone number on the landing page, but doesn't have an active account (or doesn't meet the minimum age requirement), they receive an error message stating they cannot continue.

Vipps landing page

Deep links are not recommended

Always use universal links when integrating Vipps MobilePay payments into your app.

If you believe deep links are necessary for your integration, please contact us before proceeding: developer@vippsmobilepay.com

Deep links use custom URL schemes (vipps://) for direct app-to-app switching. Note that, in the test environment (MT), the URL scheme is vippsMT://. :::

We do not recommend deep links for most integrations because:

  • They don't work on desktop
  • They require manual error handling
  • There's no fallback if the app isn't installed
  • WEB_REDIRECT (universal links) provides better security and compatibility

Use NATIVE_REDIRECT only if you have a native-only app with no web presence.

Your responsibilities​

When using deep links, you are responsible for:

  1. Checking app availability: Verify the user can open vipps:// URLs before initiating the payment
  2. Handling missing app: Provide clear error messages or redirect users to install the app
  3. OS version compatibility: Ensure the device meets minimum OS requirements (check help.vippsmobilepay.com)
  4. Embedded browser handling: Deep links don't work in embedded browsers (Instagram, Facebook, etc.)

When a user is redirected to a deep link:

  1. On mobile with app installed: The OS recognizes the URL and automatically opens the Vipps Vipps or MobilePay MobilePay app.
  2. On mobile without app: Error message.
  3. On desktop: Error message

To explicitly request deep links:

  1. Initiate payment or agreement:
    • Recurring API: Set isApp: true in your request
    • eCom API: Set isApp: true in your request
    • ePayment API: Set userFlow: NATIVE_REDIRECT in your request
  2. Receive a vipps:// URL in the response
  3. Redirect user to the URL exactly as provided (do not modify)
  4. Vipps Vipps or MobilePay MobilePay app opens automatically (may prompt for approval)
  5. User approves or rejects the payment/agreement and the flow continues as normal

Example response:

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

The deep link URL must be identical to what was sent by Vipps MobilePay.

If the app is not installed, redirect users to download it:

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

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

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

API parameter reference​

Quick reference for choosing between universal links and deep links:

APIApp link (recommended)Deep link
ePaymentuserFlow: WEB_REDIRECTuserFlow: NATIVE_REDIRECT
RecurringisApp: false (or omit)isApp: true
eComisApp: false (or omit)isApp: true
Last updated on