> **Description:** Troubleshoot payment failures, API errors, and HTTP status codes. Covers business reasons for failed payments, technical errors, configuration issues, and general troubleshooting guidance. # Troubleshoot errors ## Error response format The standard response body format for our error messages follows [RFC 7807](https://tools.ietf.org/html/rfc7807). For example (this is not a real error message): ```json { "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](https://developer.vippsmobilepay.com/docs/APIs/README.md). * 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: * [ePayment API](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/errors.md) * [Recurring API](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#errors) * [eCom API](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api.md#errors) ## HTTP status code errors The APIs return the following HTTP statuses in the responses: | HTTP status | Description | |:------------------------|:-------------------------------------------------------| | `200 OK` | Request successful | | `201 Created` | Request successful, resource created | | `204 No Content` | Request successful, but empty result | | `400 Bad Request` | Invalid request, see the error for details | | `401 Unauthorized` | Invalid credentials | | `403 Forbidden` | Authentication ok, but credentials lack authorization | | `404 Not Found` | The resource was not found | | `409 Conflict` | Unsuccessful due to conflicting resource | | `423 Locked` | Can 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 Requests` | See more details in [rate limiting topic](https://developer.vippsmobilepay.com/docs/knowledge-base/errors.md#http-429-too-many-requests). | | `500 Server Error` | An 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](https://www.webfx.com/web-development/glossary/http-status-codes/). The authoritative reference is: [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes). ### 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 or 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](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#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](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/README.md). **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](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/standard-authentication.md#step-2-request-an-access-token) for details, how long it is valid, and related information. Remember to use `Authorization: Bearer `. 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](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys.md) 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"](#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 ` is not the same as `Authorization: bearer `. 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](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment.md) 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](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api.md#errors). 8. For partners: Double check everything described here: [Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md). 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 ([View your sales units](https://developer.vippsmobilepay.com/docs/partner/partner-portal.md#view-your-sales-units)), with the [Management API](https://developer.vippsmobilepay.com/docs/APIs/management-api/management-api-guide.md#get-information-about-a-sales-unit), or ask the merchant to check on the [business portal](https://portal.vippsmobilepay.com). You can log in to the [business portal](https://portal.vippsmobilepay.com) to double-check your API keys, sales units and API products. See: [Getting the API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys.md#getting-the-api-keys). You should also ensure you have access to the correct API. See: [API products](https://developer.vippsmobilepay.com/docs/APIs/README.md). 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 the [business portal](https://portal.vippsmobilepay.com). See [How to regenerate API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-regenerate-api-keys) for step-by-step instructions. 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](https://developer.vippsmobilepay.com/docs/APIs/login-api/README.md) 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 the [business portal](https://portal.vippsmobilepay.com). For partners: Partners can get this error if they use [Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md) and: * Do not send the `Merchant-Serial-Number` header. See: [HTTP headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md). * 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 [business portal](https://portal.vippsmobilepay.com/login). Partners can use the partner portal to see which sales unit they have access to (and that are active). For details, see [About the partner portal](https://developer.vippsmobilepay.com/docs/partner/partner-portal.md). Partners must contact their partner manager or email [partner@vippsmobilepay.com](mailto: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: * [ePayment API Rate limiting](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/errors.md#rate-limiting) * [Recurring API Rate limiting](https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide.md#rate-limiting) * [eCom API Rate limiting](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api.md#rate-limiting) ### 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"](#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: * [ePayment API: Errors](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/errors.md) * [eCom API: Errors](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api.md#errors). * [Status page](https://developer.vippsmobilepay.com/docs/knowledge-base/status-pages.md). ## 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: * [eCom Get payment details](https://developer.vippsmobilepay.com/redocusaurus/ecom-swagger-id.yaml) * [ePayment Get payment details](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml) * [Recurring Fetch a charge](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml) For non-technical users troubleshooting transactions in the business portal, see [Can't find a transaction?](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#cant-find-a-transaction) See also: * [HTTP 404 Not Found](#http-404-not-found) * [Error codes](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api.md#error-codes) ### 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 the [business portal](https://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](https://www.brreg.no). * A sales unit can be deactivated on the [business portal](https://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 the [business portal](https://portal.vippsmobilepay.com). * Partners using [partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md) 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 the [business portal](https://portal.vippsmobilepay.com), and if there is not enough information there: [contact customer service](https://help.vippsmobilepay.com/). ### 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*](https://vippsmobilepay.com/en-NO/online/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](#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 or MobilePay user. Vipps MobilePay cannot give more details, as we cannot "leak" information about a user's age, whether a user has been blocked, or whether a user has reached its spending limit. ## 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 or perform other operations. See: [Test Environment (MT)](https://developer.vippsmobilepay.com/docs/knowledge-base/test-environment.md). ### Invalid MSN: Check your API keys This error can happen when: * A partner tries to use [Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md) for a sales unit that is not registered with them as partner. * API keys for the test environment are used in the production environment, or vice versa. * [Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md) 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](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md) 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. PSPs can only initiate payments for MSNs that are connected to them. The solution is to create a new MSN with the [PSP Merchant API](https://developer.vippsmobilepay.com/docs/APIs/psp-merchant-api/psp-merchant-api-guide.md). ## General troubleshooting The most common reasons why payments are not completed are organized by category below. ### Card-related issues **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. **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](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/README.md): 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](https://developer.vippsmobilepay.com/docs/knowledge-base/payments.md#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. ### 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](https://developer.vippsmobilepay.com/docs/knowledge-base/timeouts.md). **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?](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#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?](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#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](https://developer.vippsmobilepay.com/docs/APIs/ecom-api/vipps-ecom-api.md#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 or 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](https://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 to the [business portal](https://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](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml). For Recurring, send [Fetch a charge](https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml). 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](https://developer.vippsmobilepay.com/docs/knowledge-base/reserve-and-capture.md#customer-reports-being-charged-twice) for additional context about reservation vs capture. > **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).