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
- 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. - The merchant uses the link and logs in with BankID on portal.vipps.no.
- The merchant is presented with a page informing them that they need to sign an MA before filling in the PO.
- The merchant completes, signs and submits the MA.
- 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.
- 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.
- 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. - The merchant uses the link and logs in with BankID on portal.vipps.no.
- The merchant is presented with the pre-filled PO, checks the details and submits it.
- 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
Get all merchants
Status: 💡 Idea/proposal.
For partners using
partner keys:
Get a (long) list of all businessIdentifier
s that have one or more sales units registered with the partner making the API call.
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:
See Errors for examples of common errors.