Skip to main content

API guide

Vipps Available for Vipps. New features are under development now. See Ideas and proposals.

MobilePay Available for MobilePay in Finland. Expected availability in Denmark is March 2024.

The Management API enables partners and merchants to manage their sales units, and allows for self-service for the most common tasks. Our goal is to enable partners and merchants to do as much as possible without needing assistance.

info

This API replaces the Partner API and expands upon the functionality. More new features will soon be added in the coming months.

Integrating with this API

Both partners and soon merchants can use the Management API, and we use "partner/merchant" to indicate that this is the actor making the API request.

Authentication:

  • Partners use their partner keys to access the API
  • Soon: Merchants will be able to use their normal API keys.

See the Quick start guide for examples.

Endpoints and availability

These endpoints are available now (or very soon):

EndpointDescription
Merchants:
GET:/management/v1/merchants/{scheme}/{id}/sales-unitsGet the sales units for a merchant by business identifier. Get a list of all the sales units that belong to the specified merchant.
GET:/management/v1/merchants/{scheme}/{id}Get one merchant by business identifier.
Sales units:
GET:/management/v1/sales-units/{msn}Get information about a sales unit. Get details about one sales unit (MSN).
GET:/management/v1/sales-unitsGet all sales units. An easy way to get a list of all the sales units connected to the requesting merchant or partner.
Product orders:
POST:/management/v1/products-ordersPrefill a product order. Allows for "prefill" of the product order form on portal.vippsmobilepay.com, ensuring correct information, a simple experience for the merchant, and speedy processing of the product order.
GET:/management/v1/product-orders/{prefilledProductOrderId}/detailsGet information about a product order
DELETE:/management/v1/product-orders/{prefilledProductOrderId}Delete a product order. Available in Q4
Partners:
GET:/management/v1/partners/price-packagesGet the price packages for a partner. Enables a partner to retrieve its price package details. The price packages are needed for prefilling the product orders.

More functionality will be available soon, see: Ideas and proposals.

Merchants

Get the sales units for a merchant by business identifier

info

Status: ✅ Available.

GET:/management/v1/merchants/{scheme}/{id}/sales-units

Response:

[
{
"msn": 123456,
"name": "ACME Fantastic Fitness"
},
{
"msn": 654321,
"name": "ACME Candy and Ice Cream"
}
]

Get one merchant by business identifier

info

Status: ✅ Available.

This endpoint is for retrieving basic information about the merchant:

GET:/management/v1/merchants/{scheme}/{id}

Response:

{
"businessIdentifier": {
"scheme": "business:NO:ORG",
"id": "9876543221"
},
"name": "ACME Fantastic Fitness",
"status": "ACTIVE",
"createdAt": "2022-09-02T06:45:25.921251Z",
"updatedAt": "2022-09-02T06:45:25.921251Z",
"countryCode": "NO",
"businessAddress": {
"lines": [
"Robert Levins gate 5"
],
"postCode": "0154",
"city": "Oslo",
"countryCode": "NO"
},
"businessPostAddress": {
"lines": [
"Robert Levins gate 5"
],
"postCode": "0154",
"city": "Oslo",
"countryCode": "NO"
}
}

Future versions of the API will probably return more information, and we will work with our partners to find out what is useful and possible. Some candidates:

  • Contact information for the main person (depends on GDPR)
  • Contact information for the technical person (depends on GDPR)
  • A list of people with admin rights on portal.vippsmobilepay.com (depend on GDPR)
  • Changelog: What was changed when by whom?

Sales units

Get information about a sales unit

info

Status: ✅ Available.

This endpoint is for retrieving details about one sales unit (MSN), but only when both the merchant and sales unit are active. If the merchant is not active, or the sales unit is not active, the response will be a HTTP 404 Not Found error.

GET:/management/v1/sales-units/{msn}

Response (now):

{
"msn":"123456",
"name":"ACME Fantastic Fitness",
"businessIdentifier":{
"scheme":"business:NO:ORG",
"id":"9876543221"
},
"configuration":{
"paymentAllowed":true,
"captureType":"ReserveCapture",
"skipLandingPageAllowed":false,
"recurringAllowed":false
}
}

Response (this improvement is provided for discussions of what we should investigate further):

{
"msn":"123456",
"name":"ACME Fantastic Fitness",
"businessIdentifier":{
"scheme":"business:NO:ORG",
"id":"9876543221"
},
"configuration":{
"paymentAllowed":true,
"captureType":"ReserveCapture",
"skipLandingPageAllowed":false,
"recurringAllowed":false,
"customerMustBePresent":false,
"userinfoNinAllowed":false,
},
"settlementBankAccount": {
"scheme": "BBAN:NO",
"id": "86011117947"
},
"changelog": [
{
"timestamp": "2022-12-31T00:00:00Z",
"change": "MSN created",
"changedBy":"Vipps MobilePay"
},
{
"timestamp": "2023-01-01T00:00:00Z",
"change": "skipLandingPage set to true",
"changedBy": "Merchant, using Management API"
},
{
"timestamp": "2023-11-15T00:00:00Z",
"change": "NIN allowed",
"changedBy": "Vipps MobilePay"
},
{
"timestamp": "2023-06-01T00:00:00Z",
"change": "Updated MSN name",
"changedBy": "Merchant, using the portal"
},
]
}

The businessIdentifier is included to make it possible to find out the merchant that is associated with an MSN. This is useful when only the MSN is known.

Future versions of the API will probably return more information, and we will work with our partners to find out what is useful and possible. Some candidates:

  • Products: Which products and APIs are available for this MSN ("ePayment API", "Recurring API", "Login API", etc.).
  • Transaction cost (price package)
  • Status: Active or deactivated

Get all sales units

info

Status: ✅ Available.

Get all sales units that a merchant or partner has access to.

For partners using partner keys: Get a (long) list of all sales units registered with the partner making the API call, containing sales units that are active for an active merchant.

GET:/management/v1/sales-units

Response:

[
{
"msn": 123456,
"name": "ACME Fantastic Fitness"
},
{
"msn": 654321,
"name": "ACME Candy and Ice Cream"
}
]

It is then possible to use GET:/management/v1/sales-units/{msn} to get each MSN's details, including the businessIdentifier of the merchant it belongs to.

Product orders

Prefill a product order

info

Status: ✅ Available.

This endpoint allows for "prefill" of the product order form on portal.vippsmobilepay.com. This ensures that all the data in the form is correctly filled in, and can also "lock" parameters that are normally selectable. Product orders that have been prefilled this way are processed faster, since they are correct and contain all the required information.

The response from a prefill request contains a URL to portal.vippsmobilepay.com. The merchant simply uses the URL to get to the prefilled product order, checks the data, and submits.

info

The merchant cannot change the pricePackageId provided by the partner, so if it needs to be corrected, the merchant must contact the partner to have the partner submit a new prefill product order with the correct details.

Example request

Here is a sample request to POST:/management/v1/products/orders:

{
"businessIdentifier": {
"scheme": "business:NO:ORG",
"id": "9876543221"
},
"salesUnitName": "ACME Fantastic Fitness",
"salesUnitLogo": "VGhlIGltYWdlIGdvZXMgaGVyZQ==",
"settlementBankAccount": {
"scheme": "BBAN:NO",
"id": "86011117947"
},
"pricePackageId": "8a11afb7-c223-48ed-8ca6-4722b97261aa",
"productType": "VIPPS_PA_NETT",
"productUseCase": "WebsiteWithTest",
"annualTurnover": 100000,
"intendedPurpose": "Gym membership for accessing the gym's facilities. Guests will be not physically present when buying the subscription, as that is done on the gym's website.",
"website": {
"url": "https://example.com",
"termsUrl": "https://example.com/terms-and-conditions",
"testWebsiteUrl": "https://example.com/test ",
"testWebsiteUsername": "test-user",
"testWebsitePassword": "test-password"
},
"complianceData": {
"giftCard": {
"isSalesPercentageLessThanTen": false,
"validityDuration": "3 years",
"giftCardTurnoverShare": "about 25%"
},
"membership": {
"turnoverShare": "about 25%",
"membershipValidity": "CurrentCalendarYear",
"periodDistribution": "50% yearly 20% monthly"
},
"subscription": {
"turnoverShare": "about 25%",
"periodDistribution": "50% yearly 20% monthly"
},
"course": {
"turnoverShare": "about 25%",
"timeBeforeOrder": "10 days",
"period": "once every 6. week",
"isOnlineCourseOffered": false,
"onlineAccessibleTime": "for 3 months"
},
"ticket": {
"turnoverShare": "about 25%",
"prepurchaseTime": "10 weeks"
},
"rent": {
"turnoverShare": "about 25%",
"prepurchaseTime": "15 days",
"averageRentalDuration": "3 weeks"
},
"prepaidServices": {
"turnoverShare": "about 25%",
"prepurchaseTime": "10 weeks"
},
"donation": {
"acceptsDonation": false
}
}
"merchantCategoryCode": 5942
}
info

Please provide all the required fields, so it will not be necessary for merchants to request more details. This is the most typical reason for delays.

tip

We have made as many of the fields as possible optional, but please try to send as much as possible, to make it easy for the merchant.

About the merchantCategoryCode parameter: The merchant category code (MCC) is a four-digit number used to classify the merchant by the type of goods or services it provides. The MCC is used by Vipps MobilePay to determine the risk level of the merchant. Our product order form contains a user-friendly MCC selector, which contains a subset of all MCCs. If the MCC specified with the API matches one of the user-selectable ones, that MCC will be pre-selected in the form. If the MCC does not match, or no MCC is specified, no MCC will be pre-selected. The MCCs supported at the time of writing (2024-02-01) are in this CSV file: MCC list. This list of supported MCCs may change without notice.

Response:

{
"prefilledOrderId": "81b83246-5c19-7b94-875b-ea6d1114f099",
"prefillUrl": "https://portal.vippsmobilepay.com/register/vippspanett/81b83246-5c19-7b94-875b-ea6d1114f099"
}

Processing of the prefilled product order

When the submitted product order has been processed, an email is sent to both the partner/merchant making the request and the merchant that submitted the prefilled product order. This will include information about:

  • The merchant's business identifier
  • The merchant's name
  • The sales unit's MSN
  • The sales unit's name

About "Product Order" (PO) and "Merchant Agreement" (MA)

Merchants must have both a valid Merchant Agreement (MA) and an approved Product Order (PO) to be able to use Vipps MobilePay products.

  • MA: An agreement between the merchant and Vipps MobilePay, signed with BankID. The MA contains information about all direct and indirect owners, any politically exposed persons, etc.
  • PO: This is an order for a specific product. The merchant must provide some information about the use, whether the cardholder is present, etc. The PO is not signed with BankID. A merchant may have several products, each created with a separate PO.

A merchant may order a product (submit a product order, "PO") with or without an existing Merchant Agreement ("merchant agreement", "MA").

Scenarios

info

The only way we can verify that a user is allowed to sign a merchant agreement for a merchant is by using data from the Brønnøysundregistrene, the Norwegian business registry. It is therefore a requirement that the user signed in to the merchant portal is registered as chairman of the board (styreleder) or CEO (daglig leder). The user will then automatically be presented with the prefilled PO.

Scenario 1: The merchant does not have a Merchant Agreement
  1. The partner/merchant prefills the PO using POST:/management/v1/products-orders and gets a link to the prefilled PO on portal.vippsmobilepay.com.
  2. The merchant uses the link and logs in with BankID on portal.vippsmobilepay.com.
  3. The merchant is presented with a page informing them that they need to sign an MA before filling in the PO.
  4. The merchant completes, signs and submits the MA.
  5. The merchant select the prefilled PO from the table on the order completed page.
  6. We process the PO and send both the merchant and partner/merchant who made the prefill request an email when done. The partner/merchant who made the prefill request can also check with the API: GET:/management/v1/merchants/{scheme}/{id}.

Merchant Agreement Signed Page

The most important part of the merchant agreement form is the reelle rettighetshavere (real rights holders), meaning the people with direct or indirect ownership or rights for the business. This is not something the partner can be expected to know, and in any case this is information that must be signed with BankID by a person that has signatory rights for the merchant. The form looks like this:

Scenario 2: The merchant has an active or processing Merchant Agreement

The merchant has an MA and probably also a Vipps MobilePay product.

  1. The partner/merchant prefills the PO using POST:/management/v1/products/orders and gets a link to the prefilled PO on portal.vippsmobilepay.com.
  2. The merchant uses the link and logs in with BankID on portal.vippsmobilepay.com.
  3. The merchant is presented with the prefilled PO, checks the details and submits it.
  4. We process the PO and send both the merchant and partner/merchant who made the prefill request an email when done. The partner/merchant who made the prefill request can also check with the API: GET:/management/v1/merchants/{scheme}/{id}.

In the future, we may allow the merchant to change some data prefilled by the partner, but this is not trivial. If the merchant changes any data, the partner must be notified and also get the updated data - then merge and sync that with the "old" data that was sent in the first place.

Sequence diagram for prefill

PO: Product order. MA: Merchant agreement.

Get information about a product order

info

Status: ✅ Available.

For partners.

GET:/management/v1/product-orders/{prefilledProductOrderId}/details

Here is an overview of statuses to be returned:

StatusDescription
RECEIVEDThe PO exists, but nothing has been done with it yet.
MERCHANT_VIEWEDThe PO URL has been accessed.
ORDER_SUBMITTEDThe merchant has submitted the PO.
info
  • There are strict rules for what information we are allowed to share with a partner. To give more details than the above, we need consent from the merchant, and the merchant must also be able to withdraw that consent. We don't have that consent management system, and it is unlikely that we will implement it.
  • This endpoint may be extended to offer more details, such as which MSN was created by the PO. This is not yet possible, and we have no ETA.
  • This endpoint does not provide information about when/if the PO has been approved or rejected. Partners can use Get the sales units for a merchant by business identifier to see all the merchant's sales unit that are connected to the partner.
  • The best way to check the detailed status of a PO is for the merchant to check on portal.vippsmobilepay.com.
  • See: Typical reasons for delays.

Delete a product order

info

Status: 🟡 Available in Q4 2024

An "undo" endpoint to delete a PO. This may be used if an incorrect PO has been prefilled with POST:/management/v1/product-orders.

DELETE:/management/v1/product-orders/{product-order-id}

Partners

Get the price packages for a partner

info

Status: ✅ Available.

Partners can use this endpoint to get a list of all their price packages, with the pricePackageId to use for POST:/management/v1/products/orders, as well as other details.

GET:/management/v1/partners/price-packages

Response:

[
{
"pricePackageId": "8a11afb7-c223-48ed-8ca6-4722b97261aa",
"name": "POS standard",
"description": "2.99%",
"visibleInSignupForm": true,
"productType": "PAYMENT_INTEGRATION"
}
]

Ideas and proposals

EndpointDescription
Merchants:
GET:/management/v1/merchantsGet all merchants.
GET:/management/v1/merchants/{scheme}/{id}/contractsGet a merchant's contract(s).
PATCH:/management/v1/sales-units/{msn}Update sales unit.
Partners:
GET:/management/v1/partners/whoamiGet information about a partner.
API quality:
GET:/management/v1/api-quality/sales-units/{msn}API quality.
GET:/management/v1/merchants/{scheme}/{id}/product-ordersGet all prefilled product orders for a merchant.

Get all merchants

Status: 💡 Idea/proposal.

For partners using partner keys: Get a (long) list of all businessIdentifiers that have one or more sales units registered with the partner making the API call.

GET:/management/v1/merchants

Response:

{
"merchants":[
{
"businessIdentifier":{
"scheme":"business:NO:ORG",
"id":"987654321"
},
"name": "ACME Fantastic Fitness"
},
{
"businessIdentifier":{
"scheme":"business:NO:ORG",
"id":"987654322"
},
"name": "ACME Candy and Ice Cream"
}
]
}

If this endpoint is used with normal API keys (not partner keys), it will return just one merchant: The one making the API request.

Get a merchant's contract(s)

info

Status: 💡 Idea/proposal.

Return a (link to a) PDF.

GET:/management/v1/merchants/{scheme}/{id}/contracts

Response:

{
"urls": [
"https://example.com/contracts/contract-12345.pdf"
]
}

Update sales unit

info

Status: 💡 Idea/proposal.

May be used to update a sales unit, for instance the name or the status.

PATCH:/management/v1/sales-units/{msn}

Example PATCH request body:

{
"name": "ACME Fantastic Fitness Deluxe",
"salesUnitLogo": "VGhlIGltYWdlIGdvZXMgaGVyZQ==",
"status": "ACTIVE"
}

Get information about a partner

info

Status: 💡 Idea/proposal.

For partners using partner keys: Get details for the partner making the request.

GET:/management/v1/partners/whoami

Response:

{
"partnerId": "123456",
"name": "ACME Partner Inc",
"level": "Partner Premium",
"partnerContactName": "firstName lastName",
"partnerContactEmail": "firstname.lastname@vippsmobilepay.com",
"status": "ACTIVE"
}

If this endpoint is used with normal API keys (not partner keys), it will return an error.

API quality

info

Status: 💡 Idea/proposal.

We want to offer an API endpoint that lets you retrieve monitoring information for your API requests.

This will make it easier to check the health of your integrations.

GET:/management/v1/api-quality/sales-units/{msn}

Response:

{
"ApiQualityItems":[
{
"endpoint":"POST:/epayment/v1/payments",
"total Requests":1000,
"successRate":95,
"status200":950,
"status400":10,
"status401":10,
"status403":10,
"status404":10,
"status429":10,
"status500":0
}
]
}
info

Monitoring API errors and fixing them quickly is a requirement in the checklists for all APIs. For example, see:

See HTTP response codes and errors for examples of common errors.

Get all prefilled product orders for a merchant

Returns a list of prefilledProductOrderId items for the specified merchant.

{
"prefilledProductOrderId":[
"8a11afb7-c223-48ed-8ca6-4722b97261aa",
"8a11afb7-c223-48ed-8ca6-4722b97261ab",
"8a11afb7-c223-48ed-8ca6-4722b97261ac"
]
}

Help us improve our documentation

Did you find what you were looking for?