API guide

Available for Vipps now. New features may be provided in the future.

Available for MobilePay in selected markets at the Vipps MobilePay joint platform launch.

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.

Please note: This API replaces the Partner API and now contains all the same functionality. More functionality 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):

Endpoint	Description
Merchants:
GET:/merchants/{scheme}/{id}/sales-units	Get the sales units for a merchant by business identifier. An easy way to get a list of all the sales units that belong to the specified merchant.
GET:/merchants/{scheme}/{id}	Get one merchant by business identifier. Available first week in Q4
Sales units:
GET:/sales-units/{msn}	Get information about a sales unit. This endpoint is for retrieving details about one sales unit (MSN), such as the name of the sales unit, the business identifier is belongs to and the sales unit's configuration.
GET:/sales-units	Get all sales units. Available in Q4
Product orders:
POST:/products/orders	Pre-fill a product order. This endpoint allows for "pre-fill" of the product order form on portal.vipps.no. The merchant simply uses a URL to get to the pre-filled product order, checks the data, and submits. 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 pre-filled this way are processed faster, since they are correct and contain all the required information.
Partners:
GET:/partners/price-packages	Get the price packages for a partner. Enables a partner to retrieve its price package details. The price packages are needed for pre-filling the product orders.

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

Merchants

Get the sales units for a merchant by business identifier

Status: ✅ Available.

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

Response:

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

Get one merchant by business identifier

Status: 🟡 Available first week in Q4.

This endpoint is for retrieving basic information about the merchant:

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

Response:

{
  "merchant": {
    "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": {
      "city": "Oslo",
      "country": "NO",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "lines": [
        "Robert Levins gate 5"
      ],
      "postCode": "0154"
    },
    "businesspostAddress": {
      "city": "Oslo",
      "country": "NO",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "lines": [
        "Robert Levins gate 5"
      ],
      "postCode": "0154"
    }
  }
}

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.vipps.no (depend on GDPR)
• Changelog: What was changed when by whom?

Sales units

Get information about a sales unit

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,
   },
   "bankDetails": {
      "bankAccount": {
         "id": "NO93 8601 1117 947",
         "scheme": "IBAN"
      }
   },
   "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

Status: 🟡 Available in Q4.

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:

{
   "salesUnits":[
      {
         "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

Pre-fill a product order

Status: ✅ Available.

This endpoint allows for "pre-fill" of the product order form on portal.vipps.no. 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 pre-filled this way are processed faster, since they are correct and contain all the required information.

The response from a pre-fill request contains a URL to portal.vipps.no. The merchant simply uses the URL to get to the pre-filled product order, checks the data, and submits.

Please note: 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 pre-fill 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
    }
  }
}

Important: 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.

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.

Response:

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

Processing of the pre-filled 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 pre-filled 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

Please note: The only way we can verify that a user is allowed to sign a merchant agreement for a merchant is by using data from Brønnøysundregistrene. It is therefore a requirement that the user logging in on portal.vipps.no is registered as chairman of the board (styreleder) or CEO (daglig leder). The user will then automatically be presented with the pre-filled PO.

Scenario 1: The merchant does not have a Merchant Agreement

1. The partner/merchant pre-fills the PO using POST:/management/v1/products-orders and gets a link to the pre-filled PO on portal.vipps.no.
2. The merchant uses the link and logs in with BankID on portal.vipps.no.
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 re-uses the link or finds the link to the pre-filled PO form on the front page on portal.vipps.no and is presented with the pre-filled PO, checks the details in the PO and submits it.
6. We process the PO and send both the merchant and partner/merchant who made the pre-fill request an email when done. The partner/merchant who made the pre-fill request can also check with the API: GET:/management/v1/merchants/{scheme}/{id}.

The most important part of the MA form is the "reelle rettighetshavere" ("real rights holders"), meaning the people with direct or direct ownership or rights for the company. 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 pre-fills the PO using POST:/management/v1/products/orders and gets a link to the pre-filled PO on portal.vipps.no.
2. The merchant uses the link and logs in with BankID on portal.vipps.no.
3. The merchant is presented with the pre-filled PO, checks the details and submits it.
4. We process the PO and send both the merchant and partner/merchant who made the pre-fill request an email when done. The partner/merchant who made the pre-fill 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 pre-filled 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 pre-fill

PO: Product order. MA: Merchant agreement.

Partners

Get the price packages for a partner

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": "ePayment"
  }
]

Ideas and proposals

Endpoint	Description
Merchants:
GET:/merchants	Get all merchants.
GET:/merchants/{scheme}/{id}/contracts	Get a merchant's contract(s).
PATCH:/sales-units/{msn}	Update sales unit.
Product orders:
GET:/product-orders/{product-order-id}	Get information about a product order.
DELETE:/product-orders/{product-order-id}	Delete a product order.
Partners:
GET:/partners/whoami	Get information about a partner.
API quality:
GET:/api-quality/sales-units/{msn}	API quality.

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)

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

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 product order

Status: 💡 Idea/proposal.

For both merchants and partners.

The best way to check the status of a product order is on portal.vipps.no.

We are considering an endpoint like this:

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

Response, if the pre-fill URL has been accessed:

{
  "prefilledOrderId": "81b83246-5c19-7b94-875b-ea6d1114f099",
  "prefillStatus": "ACCESSED"
}

Please note: There are strict rules for what information we are allowed to share with a partner, as this requires active consent from the merchant, and the merchant must also be able to withdraw the consent. Implementing a consent solution for merchants is complex, and may not be possible to prioritize.

Delete a product order

Status: 💡 Idea/proposal.

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

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

Get information about a partner

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

Status: 💡 Idea/proposal.

We want to offer an API endpoint that lets merchants and partners retrieve the same information that is available on the API Dashboard.

This will make it easier to monitor usage the API platform.

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
      }
   ]
}

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

• ePayment API checklist
• Recurring API checklist

See Errors for examples of common errors.