API guide
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.
This API replaces the Partner API and expands upon the functionality. More new features will soon be added in the coming months.
New features are under development now. See Ideas and proposals.
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):
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:
[
{
"msn": 123456,
"name": "ACME Fantastic Fitness"
},
{
"msn": 654321,
"name": "ACME Candy and Ice Cream"
}
]
Get one merchant by business identifier
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
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
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
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.
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": "PAYMENT_INTEGRATION",
"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
}
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.
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"
}
The URL expires after 14 days due to regulatory requirements.
Accessing an expired prefillUrl will result in an error.
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
The only way we can verify that a user is allowed to sign a merchant agreement for a merchant is by using data from local registries. It is therefore a requirement that the user signed in to the merchant portal has signing rights on behalf of the company. The user will then automatically be presented with the prefilled PO.
Scenario 1: The merchant does not have a Merchant Agreement
This merchant does not yet have any Vipps MobilePay products.
- The partner/merchant prefills the PO using
POST:/management/v1/products-ordersand gets a link to the prefilled PO on portal.vippsmobilepay.com. - The merchant uses the link and logs in on portal.vippsmobilepay.com.
- 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 is presented with the confirmation page shown below, where they select the prefilled PO, and check and submit that (there will normally only be one prefilled PO waiting).
- 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}.
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.
- The partner/merchant prefills the PO using
POST:/management/v1/products/ordersand gets a link to the prefilled PO on portal.vippsmobilepay.com. - The merchant uses the link and logs in on portal.vippsmobilepay.com.
- The merchant is presented with the prefilled PO, checks the details and submits it.
- 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
Status: ✅ Available.
For partners.
GET:/management/v1/product-orders/{prefilledProductOrderId}/details
Here is an overview of statuses to be returned:
| Status | Description |
|---|---|
RECEIVED | The PO exists, but nothing has been done with it yet. |
MERCHANT_VIEWED | The PO URL has been accessed. |
ORDER_SUBMITTED | The merchant has submitted the PO. |
EXPIRED | The PO has expired. |
- 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 prefilled PO expires after 14 days due to regulatory requirements.
- 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.
Get information about a partners product orders
Status: ✅ Available.
For partners.
Partners can use this endpoint to retrieve prefilled product orders created by them.
The contents of each order entry is the same as for the Get endpoint for specific orders, and the same limitations of what can be shared apply
By default only orders with the RECEIVED, MERCHANT_VIEWED and ORDER_SUBMITTED are returned, if the query parameter includeExpired is set to true orders with the expired status will be returned as well
Delete a product order
Status: ✅ Available.
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/{prefilledProductOrderId}
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": "PAYMENT_INTEGRATION"
}
]
Ideas and proposals
| Endpoint | Description |
|---|---|
| Merchants: | |
GET:/management/v1/merchants | Get all merchants. |
GET:/management/v1/merchants/{scheme}/{id}/contracts | Get a merchant's contract(s). |
PATCH:/management/v1/sales-units/{msn} | Update sales unit. |
| Partners: | |
GET:/management/v1/partners/whoami | Get information about a partner. |
| API quality: | |
GET:/management/v1/api-quality/sales-units/{msn} | API quality. |
GET:/management/v1/merchants/{scheme}/{id}/product-orders | Get 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.
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 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 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
}
]
}
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"
]
}