API keys for partners

Partners help their merchants with creating integrations and managing their sales units. They use the API platform to configure their merchants in Vipps MobilePay.

API keys provide the identity of the requestor and are necessary for has authorization for what is being requested. To get the API keys, the partner send us the merchant's consent and, after some verifications, we connect the partner and merchant in the system.

How API keys are used

When you use the API to request payments, logins, and other services, we must be sure of your identity and access rights.

Your API keys provide proof of your identity. This is why it's so important to keep these secret.

Supply the API keys in an authentication request through the Access token API, and we will return a token that represents your identity.

When you run further API requests, attach the token so that we get your identity and can confirm that you have permission to run the request.

For example, if you request to initiate a payment for a sales unit (merchant sales number), we will use your access token to identify who you are, and evaluate if you're allowed to initiate payments for the specified sales unit.

How to get API keys

Once your partner application has been approved, you'll receive a welcome email with a test sales unit and API keys. If you have lost this or need a new test sales unit, please contact partner@vippsmobilepay.com. Sales units are specific for either Norway, Denmark, or Finland. Remember to state which country the sales unit should be created for.

Note that partner functionality is not available in test. Instead, you will receive merchant API keys, as mentioned in the limitations section. All payment and login flows can be tested using the merchant API keys.

Partners can also get access to the test environment by ordering the Login API. See Partner: How to get access to your sales units on the merchant portal.

Types of API keys

These keys are:

• Merchant keys - Provide access to the common APIs to which the merchant has access. These are used by smaller partners who don't have partner keys.
• Management keys - Provide access to the Management API only. Management keys are useful when you don't have partner keys, or for reasons of security, you can't use your partner keys.
• Partner keys - Provide access to most of the common APIs allowing partners to act on behalf of their all their merchants.
• Accounting keys - Provide access to the Report API only. These can't be used to act on behalf of merchants, or to access the Management API.

A simple metaphor

Consider if all sales units are apartments in a large building block:

• Every apartment owner has keys to their own door
• The janitor has a skeleton key that works on all the apartment doors
• The managers have keys to the building and a management office
• The accountant has keys to the computer where the private records are stored

Merchant keys

The merchant's own keys only allow access to a single apartment. These are the resident's own keys.

Management keys

The management keys can be used to manage sales units, but not to make API requests on behalf of merchants (for instance to make payments). Think of them as the postman's keys that gives access to the entrance where the mailboxes are, but not to the apartments.

Partner keys

The partner keys are the janitor keys: A partner with partner keys can act on behalf of all the sales units that has that partner as partner (the janitor keys work for all the apartments in the building that the janitor is janitor for). The partner keys can be used both to manage sales units and to make payments.

Accounting keys

The accounting keys only allow access to the computer where the bills are paid.

note

A partner can have more than one set of keys. For instance, if a partner is both an accounting partner and a "normal" partner, they will have two separate sets of API keys: Accounting keys and either Partner keys or Management keys.

The keys provide access as follows:

API keys	Management API	Main APIs	Report API
Merchant keys	✅	✅	✅
Management keys	✅	❌	❌
Partner keys	✅	✅	❌
Accounting keys	❌	❌	✅

The keys provide access to the APIs as illustrated:

Merchant keys

The merchant's own API keys. The merchant logs in on portal.vippsmobilepay.com and gets their API keys for the sales unit MSN.

How to find the API keys

You can find the API keys for your test or production sales unit in the merchant portal, portal.vippsmobilepay.com. (Need help logging in?)

1. Select For developers in the left menu. With the API keys tab selected, you should see a table with sales units.

   

2. Select either Production or Test, depending on the type of sales unit you are looking for.

3. Find the sales unit in the table and click the corresponding Show keys button. A panel will open where you can copy the values of each key.

   For example:

   

If you need to get/give the API keys from/to someone, be sure to do it securely. If you can't do that, then create a new portal user for that person, and give them basic access to the sales unit.

If you have partner keys, use these instead of merchant keys.

Management keys

All partners with a signed contract can use the Management API to manage their merchants' sales units and improve the flow for creating new sale units through prefilled information.

Management keys provide access to the Management API only. These are useful when you don't have partner keys, or for reasons of security, you can't use your partner keys. These don't allow access to the other APIs, so the partner will not be able to act on behalf of the merchant with these.

Both partners and merchants are allowed to use management keys.

Authentication shortcut

If you are using management keys, see Partner specialized authentication.

Partner keys

Partners at Partner Plus or above may qualify for partner keys. These allow a partner to can act on behalf of all their merchants without using many sets of merchant API keys.

Partner keys provide access to APIs for all the products that can be ordered by merchants as well as the Management API.

• If you are already using the same, identical API keys for multiple merchants, you are already using partner keys.
• You must not use partner keys if the merchants can, in any way, see or access the API keys. That would be security problem that would make it possible for someone to act on behalf of all your merchants.
• Partner keys only work in the production environment. In the test environment, you must use the merchant's API keys. If you are not a Vipps MobilePay merchant in the production environment and do not have these keys, you will need to use the merchant keys belonging to one of your merchants.
• Vipps MobilePay cannot send the merchant's API keys to you. You must get them from the merchant securely (if partner keys are not used). See: Knowledge base: API Keys for more details.
• If the merchant is unable to provide the API keys to you securely, the merchant can create a user for you, as described in detail with screenshots.
• Vipps MobilePay cannot assist a partner in getting the API keys from the merchant, other than by improving the documentation for how to do it.
• Partner keys can be used for all sales units that are registered with the partner. It does not matter if the sales unit is several years old, or one minute old.

Keep the keys secret

Your API keys must never be shared in any readable way with the merchants, as that will let one merchant perform API calls (including making payments, refunds, etc.) on behalf of another merchant.

Potential pitfalls

💣 If your answer is yes to any of the following questions, don't use partner keys:

• Your merchants can see the partner keys (client_id, client_secret, Ocp-Apim-Subscription-Key) in your solution.
• Your merchants have the ability to change their MSN (Merchant Serial Number) in your solution.
• The keys and secrets are stored on the merchant's system (in a way that allows them to access and see it).

For making API calls on behalf of merchants:

• Use the same partner keys for all merchants.
• Specify the MSN of the sales unit its acting on behalf of in the Merchant-Serial-Number HTTP header.

Partner keys don't give access to the Report API, because it can reveal information about a merchant's prices and fees, including information that is regulated by GDPR. For this, you need Accounting keys.

Authentication shortcut

If you are using partner keys, see standard authentication.

Accounting keys

The accounting keys allow access to the Report API for retrieval of data about payments that have been made.

The merchant must explicitly give consent for the accounting partner to get access to this information.

Accounting keys can't be used to manage sales units or to make payments. Accounting keys are separate and don't have overlapping functionality with the other types of partner-related keys.

Partners who have either partner keys or management keys will still need a separate set of accounting keys to access the Report API.

Authentication shortcut

If you are using accounting keys, see Partner specialized authentication.