> **Description:** Understand and implement the required HTTP headers for Vipps MobilePay API requests, ensuring proper request tracking and system identification.

# 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 help in investigating problems.

* `Ocp-Apim-Subscription-Key`   - The subscription key for the sales unit (see [How to find the API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-api-keys))
* `Merchant-Serial-Number`      - The MSN identifies a sales unit (not a merchant) (see [How to find the MSN](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-merchant-serial-number))
   If you are using an endpoint that covers many sales units, this can be omitted.
* `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 or service you're providing
* `Vipps-System-Plugin-Version` - The version number of the plugin or service you're providing

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.

**Important**

These headers are **required for plugins and partners**. They are used for identifying which version of a plugin or partner solution the merchants are using. This way it is easy to identify which system and version a merchant is using.
We strongly recommend that all customers with a direct integration with the API 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:

Examples:

| Header                        | POS           | Web shop      | Vending machine | Vipps MobilePay plugin | Accounting system     |
|-------------------------------| ------------- |---------------| --------------- |----------------------- | --------------------- |
| `Vipps-System-Name`           | Acme Commerce | Acme Commerce | Acme Commerce | WooCommerce          | Acme Accounting     |
| `Vipps-System-Version`        | 1.7           | 2.6           | 2.6           | 5.4                  | 1.4                 |
| `Vipps-System-Plugin-Name`    | acme-pos      | acme-webshop  | acme-vending  | woocommerce-payment  | acme-accounting-pro |
| `Vipps-System-Plugin-Version` | 3.2           | 4.3           | 4.3           | 1.4.1                | 3.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

```text
-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" \
```