Management 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.

info

More new features will soon be added in the coming months. Contact your partner manager if you have suggestions for improvement.

New features are under development now. See Ideas and proposals.

Be aware that these are only running on the production server, https://api.vipps.no and not in the test environment.

Integrating with this API

Both partners and 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 management keys or partner keys
• Merchants 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:/management/v1/merchants/{scheme}/{id}/sales-units	Get 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 a merchant's details 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-units	Get 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-orders	Prefill 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}/details	Deprecated, replaced by Get information about a prefilled product order
GET:/management/v2/product-orders/{productOrderId}/details	Get information about a product order
GET:/management/v2/product-orders	Get a list of the product orders where you are the partner
DELETE:/management/v1/product-orders/{prefilledProductOrderId}	Delete a product order.
Partners:
GET:/management/v1/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 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.

The GET:/management/v1/merchants/{scheme}/{id}/sales-units endpoint enables you to get a list a merchant's sales units by providing a business identifier for the merchant.

Response:

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

Get a merchant's details by business identifier

info

Status: ✅ Available.

The GET:/management/v1/merchants/{scheme}/{id} endpoint is for retrieving basic information about the merchant.

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.

The GET:/management/v1/sales-units/{msn} 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.

Response (now):

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

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.

The GET:/management/v1/sales-units endpoint can be used to get all sales units that a merchant or partner has access to.

For partners using management keys or 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.

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.

The POST:/management/v1/product-orders 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.

info

If the price package is specified or the partner only has one price package the price will not be displayed in the product order form.

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
}

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

note

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

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

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 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 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).
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}.

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

The GET:/management/v2/product-orders/{productOrderId}/details endpoint allows partners to get information about all product order where the partner is specified:

• Product orders made with POST:/management/v1/product-orders.
• Product orders made with Product order templates (the links we create for you).
• Product orders made by a merchant on portal.vippsmobilepay.com without prefill or template.

When the status is set to COMPLETED, the resulting sales unit will also be returned as salesUnit.

Example response, for a PO made with prefill:

{
  "productOrderType": "PREFILL",
  "productOrderId": "81b83246-5c19-7b94-875b-ea6d1114f099",
  "status": "COMPLETED",
  "businessIdentifier": {
    "scheme": "business:NO:ORG",
    "id": "9876543221"
  },
  "productOrderUrl": "https://portal.vippsmobilepay.com/register/prefilled/81b83246-5c19-7b94-875b-ea6d1114f099",
  "salesUnit": {
    "msn": 123456,
    "name": "ACME Fantastic Fitness"
  }
}

note

POs made with templates, and manually made by a merchants on portal.vippsmobilepay.com, will have less details. See GET:/management/v2/product-orders/{productOrderId}/details for details.

These are the states and possible flows:

Status	Description
RECEIVED	The prefilled PO exists (it has been sent to us), but nothing has been done with it yet.
MERCHANT_VIEWED	The PO URL has been accessed at least once.
ORDER_SUBMITTED	The merchant has submitted the PO. If the PO is rejected, the state will still be ORDER_SUBMITTED.
EXPIRED	The PO has expired, which happens after 14 days.
COMPLETED	The PO was successfully completed. The accompanying sales unit information will also be returned at this point.

info

• Only PO made with prefill can contain all statuses. See the API specification for details.
• 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.
• If a PO is rejected, or we don't get the required information to be able to process it, the end state will be ORDER_SUBMITTED. The merchant will have more details, but we can (for the reasons mentioned above) not give this information 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 product order (v1, deprecated)

info

Status: 🟡 Deprecated 2024-10-31. Unavailable after 2025-02-28.

Details

The GET:/management/v1/product-orders/{prefilledProductOrderId}/details endpoint allows partners to get information about an existing prefilled product order.

When the status is set to COMPLETED, the resulting sales unit will also be returned as salesUnit.

Example response:

{
  "productOrderId": "81b83246-5c19-7b94-875b-ea6d1114f099",
  "status": "COMPLETED",
  "businessIdentifier": {
    "scheme": "business:NO:ORG",
    "id": "9876543221"
  },
  "productOrderUrl": "https://portal.vippsmobilepay.com/register/prefilled/81b83246-5c19-7b94-875b-ea6d1114f099",
  "salesUnit": {
    "msn": 123456,
    "name": "ACME Fantastic Fitness"
  }
}

These are the states and possible flows:

Status	Description
RECEIVED	The prefilled PO exists (it has been sent to us), but nothing has been done with it yet.
MERCHANT_VIEWED	The PO URL has been accessed at least once.
ORDER_SUBMITTED	The merchant has submitted the PO. If the PO is rejected, the state will still be ORDER_SUBMITTED.
EXPIRED	The PO has expired, which happens after 14 days.
COMPLETED	The PO was successfully completed. The accompanying sales unit information will also be returned at this point.

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.
• If a PO is rejected, or we don't get the required information to be able to process it, the end state will be ORDER_SUBMITTED. The merchant will have more details, but we can (for the reasons mentioned above) not give this information 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 a list of product orders

info

Status: ✅ Available

The GET:/management/v2/product-orders endpoint allows partners to get a list of all product order where the partner is specified:

• Product orders made with POST:/management/v1/product-orders.
• Product orders made with Product order templates (the links we create for you).
• Product orders made by a merchant on portal.vippsmobilepay.com without prefill or template.

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, ORDER_SUBMITTED and COMPLETED are returned, if the query parameter includeExpired is set to true orders with the expired status will be returned as well

info

• Only PO made with prefill can contain all statuses. See the API specification for details.

Get a list of prefilled product orders (v1, deprecated)

info

Status: 🟡 Deprecated 2024-10-31. Unavailable after 2025-02-28.

Details

The GET:/management/v1/product-orders endpoint allows partners to get a list of all the prefilled product orders they have created.

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, ORDER_SUBMITTED and COMPLETED 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

info

Status: ✅ Available.

The DELETE:/management/v1/product-orders/{prefilledProductOrderId} endpoint allow partners to delete an existing prefilled product order.

This may be used if an incorrect product order has been created with POST:/management/v1/product-orders.

It is not possible to delete product orders that have been submitted by a merchant.

Partners

Get the price packages for a partner

info

Status: ✅ Available.

Partners can use the GET:/management/v1/partners/price-packages 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.

Response:

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

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 management keys or 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 management keys or 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:

• ePayment API checklist
• Recurring API checklist

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