Skip to main content

Payments

Payment request

When you create a payment request, with the user's phone number, they will get a notification in their Vipps or MobilePay app. If you don't have their phone number, you can specify that they should be directed to the Vipps or MobilePay Landing page, where they enter their phone number and then open their own app.

Within the user's Vipps or MobilePay app, they will be presented with a payment screen with the following details:

  • Sales unit name - The name of the sales unit. A merchant can have multiple sales units to represent different physical shops, vending machines, collection points, services, and similar.
  • Organization name - The name of the merchant that owns this sales unit.
  • Merchant Serial Number - The Merchant Serial Number (MSN), or ID number, for a sales unit.
  • Reference (orderId) - The orderId associated with this purchase as provided by the merchant.

Payment request

Payment reservation

When the user authorizes the payment, the amount will be reserved. It will remain in the "reserved" state up until it is captured or cancelled. If it is not captured within 14 days (MobilePay) or 180 days (Vipps).

Payment reserved

The payment details will show the authorized amount in faint gray (e.g., 500 kr).

Payment capture

The payment transactions are shown in reverse order, where the oldest transaction is at the bottom of the list. So, here you see the authorized amount at the bottom of the Transactions list in faint gray (e.g., 500 kr).

The payment transfer (i.e., capture) is reflected as a negative transaction in red (e.g., -500 kr), so the user can see that you have transferred 500 kr from their account.

If you later refund an amount (perhaps there was a mistake), the refunded amount will be shown in green (e.g., 250 kr) at the top of the list. The total amount paid will be updated to show the new amount.

Payment captured and partially refunded

In cases where the final amount owed is not known at the time of the payment request (e.g., for vending machines, charging stations, and taxis), it's common to reserve a larger (but reasonable) amount, so they have authorization to cover the cost of the service. Once the true amount is known, they capture this amount and cancel the remaining.

In this case, you see that the captured amount (e.g., -250 kr) is less than the original authorized amount (e.g., 500 kr). The actual amount paid is also updated.

Payment partially captured and cancelled

info

You can capture a payment within 90 days (MobilePay) or 180 days (Vipps). If it is not captured or cancelled within this time, it will be automatically cancelled.

Using Vipps MobilePay for payments

It's possible to use the ePayment API for several types of payments. The regulatory requirements are different for different types of purchases. One major difference is if the cardholder is physically present and "can look the seller in the eye" while making the payment.

Vipps MobilePay needs to do more thorough "Know Your Customer" (KYC) and compliance checks for some examples above. This must be done per sales unit. Vipps MobilePay is also required to have the correct MCC (Merchant Category Code) for each sales unit.

Because of this, merchants must use separate sales units for separate types of purchases. This also has some benefits:

  • Each sales unit has its own name presented to the user in the app
  • Each sales unit has separate transaction logs
  • Each sales unit can have its own settlement account. Sharing a single account across multiple sales units is available on request.

High success rate for direct integrations

note

We have extremely high success rate (low drop-off) for direct integration. Almost every user that selects to pay with Vipps or MobilePay completes the payment. The success rate is much higher than when using a payment card directly.

When comparing drop-off rates: Remember to compare drop-off data for when the user selects payment method, do not compare Vipps MobilePay to numbers for when the user has selected card payment and already has manually entered the card number, etc.:

  • Drop-off data for Vipps: Measure the success rate after the user has selected Vipps MobilePay.
  • Drop-off rate for cards: Measure the success rate after the user has selected card, but from before the user has to enter the card details.

The success rate for PSP integrations is not quite as high. See: Direct integration and PSP integration and Benefits of direct integration.

Card payments

The ePayment API and the Checkout API support freestanding card payments: Users can enter their card details and pay with the card without using the app. This means that payments are possible also for users in countries where Vipps MobilePay is not yet available.

Both Visa and Mastercard are supported. This includes any cards that are co-branded with VISA and Mastercard.

Visa Electron is supported if the card is enabled for online purchases.

info

To reduce risk, we do a 3D Secure step-up for all cards used for freestanding payments. This is because, when users are making freestanding payments, the delegated SCA that is used in the app isn't present. If the issuer does not handle 3D Secure correctly, the payment will fail.

Cards issued in the following countries are accepted:

  • EEA/EØS (European Economic Area)
  • Australia
  • Canada
  • Israel
  • Japan
  • New Zealand
  • Republic of Korea
  • Switzerland
  • UK
  • USA
tip

Just to avoid confusion: Payments with the app are also done using the users' cards that they have been added there. The user gets all the benefits of the card, and since the app has delegated SCA, the user gets a faster and simpler user experience. See also: Direct integration and PSP integration.

Information about payment and settlements

The merchant portal provides information about your transactions, sales units and settlement reports. You can also subscribe to daily or monthly transaction reports by email.

See:

How can I use Vipps MobilePay for different types of payments?

It's possible to use the ePayment API (and eCom API) for several types of payments.

Let's say you run a book store. You can then use ePayment API (and eCom API) in several ways, such as:

  1. A webshop that sells physical books: ePayment API (or eCom API with "reserve capture", since you can't capture the payment before the book is shipped).
  2. A webshop that sells digital, downloadable books that are immediately available: ePayment API, possibly doing the capture right after the reservation, (or the eCom API with either "reserve capture" or "direct capture"). The time the capture is done depends on whether the digital product needs to be generated or not, and whether it is always immediately available, or that there may be a delay.
  3. A physical store where customers buy physical books in person in the store: ePayment API with userFlow: PUSH_MESSAGE (or eCom API with Skip landing page).
  4. A physical store where customers can buy physical books by scanning a QR code in the window, and have the physical book delivered by mail: The QR API with merchant redirect together with the ePayment API, used in the same way as in an online store. (or as above, but with the eCom API instead, with "reserve capture", since you can't capture the payment before the book is shipped).

The regulatory requirements are different for different types of purchases. One major difference is if the cardholder is physically present and "can look the seller in the eye" while making the payment.

Vipps MobilePay needs to do more thorough "Know Your Customer" (KYC) and compliance checks for some examples above. This must be done per sales unit. Vipps MobilePay is also required to have the correct MCC (Merchant Category Code) for each sales unit.

Because of this, merchants must use separate sales units for separate types of purchases. This also has some benefits:

  • Each sales unit has its own name presented to the user in the app
  • Each sales unit has separate transaction logs
  • Each sales unit can have its own settlement account. Sharing a single account across multiple sales units is available on request.

Why do payments fail?

Common reasons why payments are not completed

The most common reasons why payments are not completed are:

  1. The debit/credit card has expired. We notify users in the app in good time before a card expires, but users must update the card(s) themselves. We verify cards for every payment (resulting in an extremely low fraud rate).
    note

    Person-to-person payments use bank accounts directly, not the card. It's therefore possible for a user to pay another person (using the bank account), but not be able to pay a merchant (since the card is expired).

  2. The debit/credit is no longer valid. This can happen when a user has received a new card, but the previous card's expiry date has not yet been reached. See point 1 above.
  3. For freestanding card payments with the ePayment API: If the card issuer does not correctly handle the "3D Secure step up", meaning the required secure customer identification, the payment will fail. See Card payments. Payments also fail if the user is attempting to pay with a card from a country that is not allowed.
  4. Insufficient funds on the debit/credit card. There is not enough money in the debit card's bank account, or not enough credit left on the credit card. With a direct integration, the user can retry the same payment with a different card, and because of this "second chance" the success rate is high. See Direct integration and PSP integration.
  5. The debit/credit card has been rejected by the issuer. There are many possible reasons for this, and we may not be allowed to give the details to the merchant. See 1 above.
  6. Payment limit reached, BankID required. There are some amount limits to prevent misuse and fraud, and when a limit is reached the user sometimes (not often) needs to authenticate with BankID, even in Vipps MobilePay. Some users still need their physical BankID code token, which they may not have available.
  7. The payment has timed out. This happens if the user does not confirm in the app within 10 minutes, typically if the user has deactivated push notifications and does not open Vipps manually. See: Timeouts.
  8. Attempt to capture an amount that exceeds the reserved amount. It's not possible to capture a higher amount than the user has confirmed in Vipps MobilePay. Some merchants experience this because of rounding errors on their side. See: Why does capture fail?
  9. Attempt to capture an amount that has not been reserved. If the user does not confirm the payment in the app, it's impossible for the merchant to capture it. The payment must have status "reserved" for capture to be possible. See: Why does capture fail?
  10. The user has reached the limit for payments within a time period. See: Payment limits, in Norwegian.

Investigating problems

We strongly recommend checking the full history of every payment with the API. You can see if a payment has been actively rejected, if the user has not done anything, etc. See: Get payment details.

We are continuously improving the error messages in the app. Some of the above errors may only have a general error message when attempting to pay.

note

We are not allowed to give detailed information about all errors to the merchant, as some information should only be provided to the user. We will not "leak" more user details than we have to. The general rule is that if the problem must be corrected by the user in the Vipps or MobilePay app, all necessary information will be provided to the user there.

tip

Everyone can test their Vipps or MobilePay app with credit and debit cards in our demo store: demo.vipps.no.

See: HTTP response codes and errors

Payment FAQ

When should I charge the customer?

You should charge the customer when the product or service is delivered. That is usually when the product is shipped.

According to Norwegian regulations you must not capture a payment until the product or service is provided to the customer. See: Forbrukerkjøpsloven §38. For more information, please see the Consumer Authority's Guidelines for the standard sales conditions for consumer purchases of goods over the internet.

We can't offer legal advice for this.

Why a user doesn't receive the payment notification

Push notifications must be active.

Push notifications are "best effort", and we can't guarantee that all push notifications arrive. It depends on services, networks, and other things outside our control.

If the Vipps/MobilePay app is already open and active when the push notification is received, the user must press the Send button and move to the payments screen to see the payment notification. The app isn't able to poll or discover the payment notification automatically.

How can I open the fallback URL in a specific (embedded) browser?

The phone's operating system always opens URLs in the default browser.

This means that the fallback URL (the "result page") will be opened in the default browser. We have no way to open the fallback URL in the embedded browser on Facebook, Instagram, etc. Similarly, there is no way for us to open the fallback URL in the same tab that the user came from before the app-switch.

This means that the merchant must be able to detect or recognize the user when the fallback URL is opened, without relying on session, cookies, etc.

Why a user might not be sent back to where they came from when they have paid?

If the payment started in a custom browser (like Chrome on iOS, or an embedded browser on Instagram, instead of the default Safari browser), the fallback URL (the result page) will still be opened in the default browser.

Can I split payments to charge a fee?

No. We don't support splitting payments to charge a fee.

If you want to charge a fee (e.g., 3 %) of your payments, you can:

  1. Receive the full payment, take your fee, and then pay the remaining amount to your customer (merchant). In order to receive payments in this way, you may need the regulatory approval as e-money institution from the Finanstilsynet.
  2. Have your customer (merchant) receive the full payment directly, then send an invoice for your fee.

Companies that receive payments through Vipps MobilePay needs to be our customers. See: Applying for services

How long is an initiated order valid, if the user does not confirm in the app?

Orders through the ePayment API can have longer timeouts. See ePayment API: Long-living payment requests.

Orders through the eCom API have a max timeout of 10 minutes.

It's important that the merchant waits (at least) this long, otherwise the user may confirm in the app, and right after get an error from the merchant that the order has been cancelled.

See: Timeouts.

How long does it take until the money is in my account?

Moving money between accounts can take a couple of business days. See Settlements for more details.

Why has a customer been charged twice for the same payment?

Very rarely, due to an artifact of the logging, it can appear that a customer may have been double charged.

info

This is extremely rare, where multiple services (e.g., both Vipps MobilePay, banks, PSPs, or similar) fail simultaneously.

Unfortunately, some banks present the payment information to their customers in a way that is not intuitive. For example, some banks will display the reservation of a payment even after the payment has been captured. This may lead some customers into thinking that both the reservation and the capture are payments, and that they have paid twice.

If you get this question, please check the payment:

  1. Find the payment ID.

    • For ePayment transactions, this corresponds to reference
    • For Recurring transactions: chargeId
    • For eCom transactions: orderId
  2. Log in on portal.vippsmobilepay.com.

  3. Click Transactions and then enter the ID in the Search by Order ID field.

  4. Click the payment to see the transaction details and history. Take note of the IDs listed for any transactions.

Note that you can also check the payment through the API. For eCom and ePayment, send Get a payment's event log. For Recurring, send Fetch a charge.

The customer can verify the transaction history in their Vipps/MobilePay app:

  1. In the Vipps or MobilePay app, tap Activities on the main screen.
  2. Tap All activities.
  3. Scroll down and tap the company name.
  4. Tap the payment to view the transaction history.
  5. Compare the payment ID and any transaction IDs to the ones you found above.

Related topic: For how long is a payment reserved?

Do we need to support callbacks?

Please try to implement the API callbacks, even if you do not use the data provided in the callback.

If it's not possible for your integration to support callbacks (no fixed hostname/IP, etc.), you must actively check the payment status.

This is also required if you do support callbacks.

In which sequence are callbacks and fallbacks done?

We can't guarantee a particular sequence, as this depends on user actions, network connectivity/speed, etc. Because of this, it is not possible to base an integration on a specific sequence of events.

See: Initiate payment flow: Phone and browser

Where can I find reports on transactions?

The merchant portal provides information about your transactions, sales units and settlement reports. You can also subscribe to daily or monthly transaction reports by email.

See: Settlements.

When do users get a "soft decline" and need to complete a 3-D Secure verification?

We handle everything related to "soft declines" and 3-D Secure. We also handle BankID verification, when that is required. There is nothing a merchant needs to.

We use delegated SCA (Secure Customer Authentication) from the banks, which significantly simplifies the user experience, as there is normally no need for BankID verification. The biometric login in the Vipps or MobilePay app is enough.

We use tokenized cards, which eliminates the need for "soft decline". As long as the token is valid, the user never has to verify the card again.

In order to prevent misuse and fraud, we require users to do a 3-D Secure verification if the user has paid more than 15 000 NOK during the last five days.

In short: Users paying with Vipps MobilePay have a much faster and simpler user experience than when using a card directly.

We also have an extremely low fraud rate, as it is impossible to pay with a card that has been invalidated in any way by the issuer. All users must log in to the app with their BankID verified identity to use their card.

See:

How do I perform "testing in production"?

To do this, you need a live Vipps MobilePay account. You can order this on portal.vippsmobilepay.com.

We recommend testing with 2 NOK, even though 1 NOK is the smallest possible amount. 1 NOK is not reliable, as it gets low priority in some systems.

Can you send us logs, so we can look for errors?

Unfortunately, Vipps MobilePay can't extract logging info for one merchant or one MSN. There are terabytes of data, and it's not trivial to provide data for just one merchant or MSN.

We provide as much information as we can for all API requests that fail, both by using a sensible HTTP status for the response and by including as much relevant information as possible in the response body.

It's important to use this information. If you discard it, it's gone.

Having said that, it is possible to investigate specific API calls in special cases if you send us enough information. Please do your own investigations before contacting us about this.

Can I prevent people from paying with credit cards?

Yes, but only if you are not legally allowed to accept credit card payments.

Sales units can be configured to only accept payments from debit cards, so customers cannot pay with credit cards. This is not configurable by the merchant. Please contact us if you need this.

Can I initiate a payment with a QR code?

Yes, you can do this with the ePayment API. See the QR flow under ePayment API: Create payment.

No.

The "deeplink" opens the payment page in the Vipps or MobilePay app where the user accepts a payment. This is an integrated part of the payment process, and the link should never be sent in an SMS or email.

According to Norwegian regulations the customer needs to actively accept the terms and conditions for the purchase. This is not possible if you just send a deeplink.

For more information, please see the Consumer Authority's Guidelines for the standard sales conditions for consumer purchases of goods over the internet.

There are different regulatory requirements for payments that are initiated by a user and by a merchant.

The deeplink is only valid for 10 minutes, so users that do not act quickly will not be able to pay. There is no way to "retry" a deeplink after the timeout. See: For how long is a payment reserved?

Instead of sending a deeplink: Send a link to your website, and let the user start the Vipps or MobilePay payment there. It can be a very simple page with a link or a button. You then have the opportunity to give the user additional information, and also a proper confirmation page after the payment has been completed.

You can also send the customer a link to a prefilled shopping cart, so the customer can add more items, and pay with Vipps Hurtigkasse.

In some cases, such as for donations and gifts, it may be acceptable to automatically trigger the payment when the user enters your website. This requires that the payment process is user initiated, and that there are no relevant terms and conditions or that the user has accepted any terms and conditions at an earlier stage.

In general, we advise caution and point out that it is the responsibility of the merchant to assure that users accept terms and conditions for products and services.

You can also use Login for easy registration and login.

Help us improve our documentation

Did you find what you were looking for?