HTTP headers

System headers

Please use the following HTTP headers for all requests to the APIs. These headers provide useful metadata about the merchant's system, which help us improve our services, and also helps in investigating problems.

• Ocp-Apim-Subscription-Key - The subscription key for the sales unit (see How to find the API keys)
• Merchant-Serial-Number - The MSN identifies a sales unit (not a merchant) (see How to find the MSN)
• Vipps-System-Name - The name of the solution
• Vipps-System-Version - The version number of the solution
• Vipps-System-Plugin-Name - The name of the plugin
• Vipps-System-Plugin-Version - The version number of the plugin

The last four headers (starting with Vipps-System-) are meant to identify your system (and plugin). Please use self-explanatory, human-readable and reasonably short values.

These headers are required for plugins and partners and sent by the official plugins. We strongly recommend that all customers with direct integration with the API to also do so.

Partners must always send the Merchant-Serial-Number header, and we recommend that everyone sends it, also when using the merchant's own API keys. It can speed up any troubleshooting of API problems quite a bit. However, for requests that are not on behalf of a merchant, the partner can omit the Merchant-Serial-Number header.

For example, if the merchant's name is "Acme AS" and they offer three different systems: point of sale (POS) integration, web shop, and vending machines, the headers could be:

Header	Description	Example value for POS	Example for web shop	Example for vending machine	Example for WooCommerce plugin	Example for Checkout plugin
Vipps-System-Name	The name of the solution	Acme Commerce	Acme Commerce	Acme Commerce	WooCommerce	WooCommerce
Vipps-System-Version	The version number of the solution	1.7	2.6	2.6	5.4	5.4
Vipps-System-Plugin-Name	The name of the plugin	acme-pos	acme-webshop	acme-vending	woocommerce-payment	woocommerce-checkout
Vipps-System-Plugin-Version	The version number of the plugin	3.2	4.3	4.3	1.4.1	1.4.1

info

• Please use self-explanatory, human-readable and reasonably short values that uniquely identify the system (and plugin).
• The max length of each header is 30 characters. See the API specification for details.

If the Vipps-System-Plugin-* headers do not make sense to you, you can simply send the same as for Vipps-System-*. The important thing is that you send as much useful information as possible, so it is as easy as possible to solve problems with your API requests if there are any.

Special headers

Sometimes we have to make exceptions and allow custom headers like:

Header	Description
X-Vipps-Authorization	Only used for Webhooks for some plugins. Must not be used, and may change or disappear without notice.

Idempotency

Many API requests to the APIs can be retried without any side effects by providing Idempotency-Key(in older APIs, this may be called, Request-Id) in the header of the request.

For example, in case the request fails because of network error, it can safely be retried with the same Idempotency-Key key without causing a duplicate. The Idempotency-Key key must be generated by the merchant according to the API specification.

Example HTTP request with all HTTP headers

-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \

With realistic example API keys:

-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated> \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-H 'Idempotency-Key: 49ca711a-acee-4d01-993b-9487112e1def' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \