Partner keys

We offer Partner keys which allow partners make API calls on behalf of their merchants.

If you are a Vipps MobilePay partner managing integrations on behalf of merchants, you can use your partner API credentials to authenticate, and then send the Merchant Serial Number (MSN) to identify which of your merchants you are acting on behalf of.

About partner keys

Read more about partner verification in:

• Partner keys
• Access token API guide

👉 Partner API keys are only functional in the production environment, not the test environment.

Key differences between partner keys and merchant keys in Login

The main differences between partner key integration and merchant integration are:

1. Authentication:

   • Merchant integration: Authentication is based on the Login access token, as described in the Access token section.
   • Partner key integration:

     • A token is obtained from the POST:/accesstoken/get endpoint. This authorization method must be used because the endpoints token_endpoint_authentication methods used by merchants are not supported for partner key integrations.

     • The token is passed as a Bearer token in the header:

       Authorization: Bearer <access-token>

2. Merchant identification:

   • For partner key integration, the Merchant-Serial-Number header must be included in backend requests to identify the merchant you are acting on behalf of.

note

The target client must be configured with client_secret_basic authentication, although the partner themselves must use standard access token.

See Portal: How to set up Login for your sales unit.

Partner key when integrating from a website

This is a partner version of the Integrate from a website flow.

Authorization endpoint

To initiate a login as partner, redirect the end-user's browser to a /auth URL containing the merchant serial number as a msn query parameter instead of client_id.

GET https://api.vipps.no/access-management-1.0/access/oauth2/auth?msn={Merchant-Serial-Number}&response_type=code&scope={scopes}&state={state}&redirect_uri={redirect_uri}

This request will return a redirect to a /auth URL where the msn query parameter is replaced by the merchant's client_id

Token endpoint

For the /token endpoint, you should authenticate using an access token. Regular client_secret_basic or client_secret_post does not work for partner key integration. The target client must be configured with client_secret_basic authentication.

1. Fetch access_token
2. Use the access token in the Authorization header, Bearer access-token.
3. Add the Merchant-Serial-Number header with the target merchant serial number.

Example request:

POST https://api.vipps.no/access-management-1.0/access/oauth2/token
Authorization: Bearer <access-token>
Content-Type: application/x-www-form-urlencoded
Merchant-Serial-Number: 12345

grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_uri}

Partner key in merchant-initiated login flow

This is a partner version of the Merchant-initiated login flow. This works for both the regular flow and Redirect to browser.

The Merchant-Serial-Number header must be sent in the header of all API requests.

1. Fetch access_token
2. Use the access token in the Authorization header Bearer access-token
3. Add the Merchant-Serial-Number header with the target merchant serial number

Example /backchannel/authentication request

POST https://api.vipps.no/vipps-login-ciba/api/backchannel/authentication
Authorization: Bearer <access-token>
Content-Type: application/x-www-form-urlencoded
Merchant-Serial-Number: 12345

scope=name address openid&login_hint=urn:msisdn:{msisdn}&state=13821s837213bng26e2n61gege26&nonce=21hebdhwqdb7261bd1b23

Example /token request (without redirect)

For the subsequent token request you should authorize with the same access token and add the Merchant-Serial-Number header as in the /backchannel/authentication request.

POST https://apitest.vipps.no/access-management-1.0/access/oauth2/token
Authorization: Bearer <access-token>
Content-Type: application/x-www-form-urlencoded
Merchant-Serial-Number: 12345

auth_req_id=<auth-req-id>&grant_type=urn:openid:params:grant-type:ciba

ID token validation

When acting as a partner on behalf of a merchant's sales unit, you don't have access to the merchant's client_id, which is used for ID token validation.

It is important to validate the Id-token before using any data contained in it. See the OIDC standard on Id-token validation for the specifics. We recommend that you use a library for this. A good place to start is finding a library for your language at jwt.io.

We strongly encourage partners to use the msn claim in the ID token for this purpose and ensure that its value is the same as the Merchant Serial Number used for the login.

Requirements

The target client must be configured with client_secret_basic authentication. The partner themselves must use standard access token.

See Portal: How to set up Login for your sales unit.

Merchant Serial Number (MSN)

This is a unique identifier for the sales unit. This is a required parameter if you are a partner making API requests on behalf of a merchant. Use the merchant's MSN, not the partner's MSN.

See: How to find the Merchant Serial Number.

Userinfo

For fetching user information, the token received during the login flow must be used.