Skip to main content

Troubleshoot errors

Error response format​

The standard response body format for our error messages follows RFC 7807.

For example (this is not a real error message):

{
   "type":"https://developer.vippsmobilepay.com/api-name/v1/validation-error",
   "title":"Your request parameters didn't validate.",
   "detail":"The request body contains one or more validation errors.",
   "instance":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "status":"400",
   "extraDetails":[
      {
         "name":"amount",
         "reason":"Must be a positive integer larger than 100"
      },
      {
         "name":"URL",
         "reason":"Must use HTTPS and validate according to the API specification"
      }
   ]
}
note
  • Most of the APIs use this error format, but legacy APIs may not. For details: See the specific API specification.
  • Some errors are sent from Microsoft Azure, and not the APIs. These include 401, 403, 422 and 429. These errors may have a different format, as they are not configurable.
  • It is the integrator's responsibility to monitor and handle all errors.

See error descriptions in the specific API guide sections:

HTTP status code errors​

The APIs return the following HTTP statuses in the responses:

HTTP statusDescription
200 OKRequest successful
201 CreatedRequest successful, resource created
204 No ContentRequest successful, but empty result
400 Bad RequestInvalid request, see the error for details
401 UnauthorizedInvalid credentials
403 ForbiddenAuthentication ok, but credentials lack authorization
404 Not FoundThe resource was not found
409 ConflictUnsuccessful due to conflicting resource
423 LockedCan be caused by transient errors outside our control. Can also occur if an integrator repeatedly sends calls several times within a very short time frame
429 Too Many RequestsSee more details in rate limiting topic.
500 Server ErrorAn internal Vipps MobilePay problem.

In general:

  • 2XX responses: Everything is OK.
  • 4XX responses: Client error. You have a problem, and you must correct it.
  • 5XX responses: Server error. We have a problem, and we must correct it.

For some errors (like 423 and 429) the solution is to retry, using the Idempotency-Key header to avoid duplication. See the API specification.

The HTTP status overview here is quite good: HTTP Status Codes Glossary.

The authoritative reference is: RFC 9110: HTTP Semantics.

HTTP 400 Bad Request​

This error occurs when you make an incorrect API request. The response body contains information about what you are doing wrong.

Some common errors:

  • Invalid API keys.
  • Invalid amount.
  • callbackUrl is invalid.
  • Captured amount exceeds the reserved amount. You can't capture a higher amount than the user has accepted.
  • Cannot refund more than captured amount.
  • User unknown. The phone number is either incorrectly formatted, is not a Vipps Vipps or MobilePay MobilePay user, or the user is under 15 years old and cannot pay businesses. Vipps MobilePay cannot give more details. This error also occurs if using a non-Norwegian phone number. Look for related questions in this FAQ.
  • Cannot capture because the payment's capture period has passed. See Payment capture deadlines.

HTTP 401 Unauthorized​

This error means you are using the wrong API keys or an incorrect Authorization header.

The full error message, and the reason for the 401 error, should be in the response body, such as:

  • Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.
  • Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
  • Subscription not found.

If the error message is Something went wrong, please try again later, it normally indicates that the provided Authorization header (the access token) is invalid. Check that the access token is in the correct format and that it has not expired. See Access Token API.

info

We have never found any problems with the API keys themselves. Every HTTP 401 Unauthorized has been caused by incorrect use.

Please follow these steps to make sure everything is correct:

  1. Make sure that you are using a valid access token. See Request an access token for details, how long it is valid, etc. Remember to use Authorization: Bearer <access token goes here>. If you do not include Bearer, you may get a HTTP 401 Unauthorized error.
  2. Check that you are using the correct API credentials for the MSN (Merchant Serial Number) you are using::
    • client_id
    • client_secret
    • Ocp-Apim-Subscription-Key (the subscription key) See API keys for more details.
  3. Make sure that you have copied all the characters in the client_id, client_secret and Ocp-Apim-Subscription-Key. It seems that double-clicking to copy sometimes omits the trailing = sign(s), and maybe others.
  4. Check that you are using the same subscription key for both the access token and the payment requests. If you have a valid access token, but for a different MSN, you will get an error. If you are caching the access token: Check that too. See: errorCode 35 "Requested Order not found".
  5. Check the API specification for the correct spelling of all the header parameters. They are case-sensitive: Authorization: Bearer <access token goes here> is not the same as Authorization: bearer <access token goes here>.
  6. Make sure you are using the right environment and check that you are using the correct API keys for the right sales unit in that environment. The test environment is completely separate from the production environment, and both the MSN and the API keys are different.
  7. Check both the HTTP response header and the response body from our API for errors. For most errors the body contains an explanation of what went wrong. See: HTTP response codes and errors.
  8. For partners: Double check everything described here: Partner keys. A common mistake is to mix Merchant-Serial-Number (used in the HTTP header) and merchantSerialNumber (used in the request body).
  9. For partners: Make sure that the merchant's sales unit is configured with you as the partner. Check on the partner portal, with the Management API, or ask the merchant to check on portal.vippsmobilepay.com.

You can log in to portal.vippsmobilepay.com to double-check your API keys, sales units and API products. See: Getting the API keys.

You should also ensure you have access to the correct API. See: API products.

If you are absolutely, completely 100 % sure that you have done everything correctly, and it still doesn't work, you can regenerate the API keys on portal.vippsmobilepay.com. This should never be necessary, and we do not know of any situations where this fixes any known problem, so it's our very last suggestion. The old API keys will of course stop working when they have been regenerated.

info

Vipps MobilePay cannot help with the debugging of your code, we can only help with the API requests and response. Please do not send us your source code asking us to fix it for you.

HTTP 403 Forbidden​

There are multiple reasons that can lead to this error.

Merchants that only have access to the Login API and attempt to use the ePayment API (or eCom API) will get this error, with Merchant Not Allowed for Ecommerce Payment in the response body.

This is because the compliance checks required for making payments are not done for merchants that only need the Login API. If you need access to the ePayment API (or eCom API), you can apply for this on portal.vippsmobilepay.com.

For partners: Partners can get this error if they use Partner keys and:

  • Do not send the Merchant-Serial-Number header. See: HTTP headers.
  • Send a Merchant-Serial-Number header for a sales unit (MSN) that is not connected to them as a partner.
  • Attempt to make API requests for a sales unit that is deactivated (or for a sales unit for a merchant that is deactivated).
info

Merchants can check which partner is connected to their sales units on the portal. Partners can use the Partner portal to see which sales unit they have access to (and that are active). Partners must contact their partner manager or email partner@vippsmobilepay.com if there are problems in connecting them to sales units.

HTTP 429 Too many requests​

We rate-limit some API endpoints to prevent incorrect usage. The rate-limiting has nothing to do with our total capacity, it is designed to stop obviously incorrect use.

See:

HTTP 404 Not found​

This error has multiple causes. You must check the body of the response.

Some common causes:

  • You are making a request to a non-existent API endpoint
  • You are using the API keys for one MSN for a payment (identified by orderId or reference) that belongs to a different MSN.
  • You have initiated a payment with the ePayment API, but attempt to retrieve it with the eCom API (or some other API mix up)

See: errorCode 35 "Requested order not found".

HTTP 500 Internal server error​

Something might be wrong on our side, and we are working to fix it. We monitor and log all errors, and fix them as quickly as we can.

However, a HTTP 500 Internal Server Error usually indicates that there is a problem with your request, and that our input validation does not catch it. In other words: We should have returned HTTP 400 Bad Request.

Some tips:

  • Make sure the JSON payload in your API request validates. That is the most common source of this type of error.
  • See the API's "Quick Start" guide, the corresponding curl commands and Postman collection to see the correct API requests.
  • See the API's API specification for all the details.
  • Make sure you are not sending a string instead of an integer, or vice versa. Example: If the API specification says that amount is an integer, and our input validation is not quite at the level it should be, you may get a HTTP 500 Server Error if you send amount as a string.
  • Check the capitalization of all parameters. Example: If the API specification says phoneNumber, and our input validation is not quite at the level it should be, you may get a HTTP 500 Server Error if you send phonenumber.

Check both the HTTP response header and the response body from our API for errors. For most errors the body contains an explanation of what went wrong.

note

If you get a HTTP 500 Internal Server Error in the test environment, it may be a glitch in the SQL server. We are running a "weaker" instance than in production, and on very rare occasions, with very high traffic, this can cause SQL errors that result in a HTTP 500 Server Error. Retry the request, and see if it helps.

See:

Business and payment errors​

This section covers specific error codes returned by the API.

errorCode 35 "Requested order not found"​

This error occurs either because you are specifying an incorrect orderId, or because the payment with this orderId was initiated using the API keys for one sales unit (MSN), and you are attempting to get the details with the API keys for a different sales unit (MSN).

The orderId (reference) is not globally unique, it's only unique per MSN.

Common causes:

  • Using API keys from one sales unit to retrieve a payment made with a different sales unit
  • Incorrect orderId or reference in the API request
  • The payment hasn't been successfully initiated yet

Solution:

Ensure your integration implements polling to get payment details using the correct API keys:

For non-technical users troubleshooting transactions in the portal, see Can't find a transaction?

See also:

Merchant unavailable, deleted, deactivated or not allowed to make payments​

This error means that the merchant is not available or active. This can be caused by one of the following:

  • A merchant can be deactivated if they haven't confirmed their information with us. Merchants are required to periodically confirm the information we have saved about them. We are required by law to request this confirmation. We send multiple emails to notify merchants that they must log on to portal.vippsmobilepay.com to confirm their information. If the merchant doesn't confirm within 30 days from the first email, they will automatically be deactivated.
  • A merchant can be deactivated if they have been deleted from the national business registry. or if they have changed their organization type (e.g., from ENK to AS). Please check that the merchant's organization number is still active in the Business registry.
  • A sales unit can be deactivated on portal.vippsmobilepay.com. A merchant sometimes does this "by accident", without being aware of the consequences. If a sales unit has been incorrectly deactivated, the merchant can reactivate it again on portal.vippsmobilepay.com.
  • Partners using partner keys can get this error if the partner itself is deactivated, even though the sales unit (that it is acting on behalf of) is active.
note

To reactivate a merchant: First check on portal.vippsmobilepay.com, and if there is not enough information there: contact customer service.

Merchant not allowed for ecommerce payment​

This error occurs if you attempt to use a payment related API with a sales unit (MSN) that is only approved for the Login API.

Your sales unit will need to go through additional regulatory checks for access to the payment APIs. Place an order for Payment Integration.

Note that all sales units that have been approved for the eCom API can also use the Login API, but not the other way around.

See: HTTP 403 Forbidden

Error 81: User not registered with Vipps​

The most common reasons for this error are:

  • The phone number is incorrectly formatted. We attempt to correct incorrectly formatted phone numbers instead of responding with HTTP 400 Bad Request. In cases where the phone number still fails, the error will be errorCode: 81. See the API specifications.
  • The user is under 15 years old and cannot pay businesses.
  • The phone number is not for a Vipps Vipps or MobilePay MobilePay user.

Vipps MobilePay cannot give more details, as we cannot "leak" information about a user's age, whether a user has been blocked, whether a user has reached its spending limit, etc.

Configuration errors​

Error: App installed and 15 years old​

This error can happen when:

  • You attempt to use a real user in the test environment.
  • You have a new test user and have not logged into the test app before trying to make payments, etc.

See: Test Environment (MT).

Invalid MSN: Check your API keys​

This error can happen when:

  • A partner tries to use Partner keys for a sales unit that is not registered with them as partner.
  • API keys for the test environment is used in the production environment, or opposite.
  • Partner keys are used, but the Merchant-Serial-Number HTTP header is not used correctly.

Invalid MSN: Not valid for the provided supermerchant ID​

This error can happen when the partner making the API request is using:

  • API keys for the test environment in the production environment, or opposite
  • An MSN for the test environment in the production environment, or opposite
  • Partner keys without including the required Merchant-Serial-Number header

If the error message is Invalid MSN: This MSN is not valid for the provided supermerchant ID., with no MSN specified, it means that the Merchant-Serial-Number is missing in the request header.

Invalid MSN: Not valid for the provided PSP ID​

The full error message text is:

"Invalid MSN: 654321. This MSN is not valid for the provided PSP ID. Check that you are using the correct credentials for the right environment."

In addition to what the error message says, this error can occur if a PSP attempts to initiate payments for an MSN that was created by a different PSP. PSP's can only initiate payments for MSNs that are connected to them.

The solution is to create a new MSN with the PSP Signup API.

General troubleshooting​

The most common reasons why payments are not completed are organized by category below.

Expired card: 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).

Invalid card: The debit/credit card 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.

Insufficient funds: 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. This results in around 2 % higher conversion rates. See Direct integration and PSP integration.

Card rejected by issuer: 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.

Authentication and security​

3D Secure verification failure: 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 Freestanding card payments. Payments also fail if the user is attempting to pay with a card from a country that is not allowed.

Payment limit reached: 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. The user may have reached the limit for payments within a time period. See Payment limits, in Norwegian.

Technical issues​

Payment timeout: 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.

Capture amount exceeds 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?

Capture without reservation: 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?

Diagnosing payment failures​

We strongly recommend checking the full history of every payment with the API (for example, through Get payment details). You can see if a payment has been actively rejected, if the user has not done anything, or if there are other actions.

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.

Notes

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).

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 Vipps or MobilePay MobilePay app, all necessary information will be provided to the user there.

tip

Test your Vipps or MobilePay app with credit and debit cards in our demo store: demo.vipps.no. (No real money is spent.)

Requesting logs to investigate 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.

Investigating double charge reports​

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 or 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.

See also: Customer reports being charged twice for additional context about reservation vs capture.

Last updated on