> **Description:** Detailed technical guide for implementing the Management API, including authentication, endpoints, and best practices for sales unit management. # 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. Be aware that these are only running on the production server, [`https://api.vipps.no`](https://api.vipps.no) and not in the [test environment](https://developer.vippsmobilepay.com/docs/APIs/management-api/management-api-faq.md#can-i-use-the-management-api-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 [partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md#partner-keys) - Merchants use their normal [API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys.md) See the [Quick start guide](https://developer.vippsmobilepay.com/docs/APIs/management-api/management-api-quick-start.md) for examples. ## Merchants ### Get the sales units for a merchant by business identifier The [`GET:/management/v1/merchants/{scheme}/{id}/sales-units`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint enables you to get a list of a merchant's sales units by providing a business identifier for the merchant. Response: ```json [ { "msn": 123456, "name": "ACME Fantastic Fitness" }, { "msn": 654321, "name": "ACME Candy and Ice Cream" } ] ``` ### Get a merchant's details by business identifier The [`GET:/management/v1/merchants/{scheme}/{id}`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint is for retrieving basic information about the merchant. Response: ```json { "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" } } ``` ## Sales units ### Get information about a sales unit The [`GET:/management/v1/sales-units/{msn}`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) 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): ```json { "msn": "123456", "name": "ACME Fantastic Fitness", "businessIdentifier": { "scheme": "business:NO:ORG", "id": "9876543221" }, "settlementBankAccount": { "scheme": "BBAN:NO", "id": "86011117947" }, "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): ```json { "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 }, "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 business 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. ### Get all sales units The [`GET:/management/v1/sales-units`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint can be used to get all sales units that a merchant or a partner has access to. For partners using [partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md): 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: ```json [ { "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}`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) to get each MSN's details, including the `businessIdentifier` of the merchant it belongs to. ## Product orders ### Prefill a product order The [`POST:/management/v1/product-orders`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint allows for "prefill" of the product order form on the [business portal](https://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 the [business portal](https://portal.vippsmobilepay.com). The merchant simply uses the URL to get to the prefilled product order, checks the data, and submits. Here is a sample request to [`POST:/management/v1/products/orders`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml): ```json { "businessIdentifier": { "scheme": "business:NO:ORG", "id": "9876543221" }, "salesUnitName": "ACME Fantastic Fitness", "salesUnitLogo": "VGhlIGltYWdlIGdvZXMgaGVyZQ== (base64, truncated)", "settlementBankAccount": { "scheme": "BBAN:NO", "id": "86011117947" }, "pricePackageId": "8a11afb7-c223-48ed-8ca6-4722b97261aa", "productType": "PAYMENT_INTEGRATION", "productUseCase": "WebsiteWithTest", "annualTurnover": 100000, "annualTurnoverPercentage": "50", "intendedPurpose": "Gym membership for accessing the gym's facilities. Guests will not be physically present when buying the subscription, it's 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" }, "hasRecurring": true, "merchantCategoryCode": 5942 } ``` **TIP** Some of the fields may be optional, but please try to provide as many of them as possible, to make it easy for the merchant and avoid any delays in processing the product order. **INFO** Please provide **all the required fields**, so it will not be necessary for us to request more details from the merchants. This is the most [typical reason for delays](https://developer.vippsmobilepay.com/docs/partner/merchant-signup.md#typical-reasons-for-delays). If the price package is specified *or the partner only has one price package* the price will be hidden in the product order form. 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. About the `merchantCategoryCode` parameter: The [merchant category code (MCC)](https://en.wikipedia.org/wiki/Merchant_category_code) 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](https://developer.vippsmobilepay.com/downloads/management-api/mcc.csv). This list of supported MCCs may change without notice. Response: ```json { "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, and other required details. - PO: This is an order for a specific product. The merchant must provide some information about the use and whether the cardholder is present. 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 who is signed in to the [business portal](https://portal.vippsmobilepay.com) also 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/product-orders`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) and gets a link to the prefilled PO on the [business portal](https://portal.vippsmobilepay.com). 2. The merchant uses the link and logs in on the [business portal](https://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 navigated to the product order form, where the merchant completes and submits the PO. 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}`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) or in the [Partner Portal](https://portal.vippsmobilepay.com/) The most important part of the merchant agreement form is the 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. ##### 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`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) and gets a link to the prefilled PO on the [business portal](https://portal.vippsmobilepay.com). 2. The merchant uses the link and logs in on the [business portal](https://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}`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml). #### Sequence diagram for prefill PO: Product order. MA: Merchant agreement. ```mermaid sequenceDiagram autonumber participant PM as Partner/Merchant participant Merchant participant Portal participant API participant VMP as Vipps MobilePay PM->>API: POST:/management/v1/product-orders API->>PM: URL to prefilled signup form PM->>Merchant: Here is your prefilled form on Portal Merchant->>Portal: Logs in with BankID and accesses form Portal->>API: Requests prefilled data Portal->>Portal: Validate MA and prefill request? opt Invalid prefill request Portal-->>Merchant: Show warning end opt Merchant does not have a Merchant Agreement (MA) Portal-->>Merchant: Show information and navigation to the MA form Merchant-->>Portal: Fill out MA Portal-->>VMP: MA is sent for processing Merchant->>Portal: Re-access prefilled form end API->>Portal: Provides prefilled data Portal->>Merchant: Show prefilled form Merchant->>Portal: Submit form Portal->>VMP: PO is sent for processing VMP->>VMP: Processing opt Vipps MobilePay requires additional information VMP->>Merchant: Sometimes: Ask for additional information Merchant->>VMP: Sometimes: Provide additional information end VMP->>Merchant: Email with MSN and other details VMP->>PM: Email with MSN and other details ``` Partner or Merchant sends a product order request to the API (POST:/management/v1/product-orders). API returns a URL to a prefilled signup form. Partner or Merchant shares the prefilled form URL with the Merchant. Merchant logs in with BankID and accesses the form on the Portal. Portal requests the prefilled data from the API. Portal validates the Merchant Agreement (MA) and prefill request. If the prefill request is invalid: Portal shows a warning to the Merchant. If the Merchant does not have a Merchant Agreement: Portal shows information and a link to the MA form. Merchant fills out the MA. Portal sends the MA to Vipps MobilePay for processing. Merchant re-accesses the prefilled form. API provides the prefilled data to the Portal. Portal shows the prefilled form to the Merchant. Merchant submits the form on the Portal. Portal sends the Product Order (PO) to Vipps MobilePay for processing. Vipps MobilePay processes the order. If Vipps MobilePay requires additional information: Vipps MobilePay asks the Merchant for more information, and the Merchant provides it. Vipps MobilePay sends an email with the MSN and other details to the Merchant. Vipps MobilePay sends an email with the MSN and other details to the Partner or Merchant. ### Get information about a product order The [`GET:/management/v2/product-orders/{productOrderId}/details`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint allows partners to get information about all product orders where the partner is specified: - Product orders made with [`POST:/management/v1/product-orders`](https://developer.vippsmobilepay.com/docs/APIs/management-api/management-api-guide.md#prefill-a-product-order). - Product orders made with *Product order templates* (the links we create for you). - Product orders made by a merchant on [portal.vippsmobilepay.com](http://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: ```json { "productOrderType": "PREFILL", "productOrderId": "81b83246-5c19-7b94-875b-ea6d1114f099", "productType": "PAYMENT_INTEGRATION", "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 merchants on [portal.vippsmobilepay.com](http://portal.vippsmobilepay.com), will have fewer details. See [`GET:/management/v2/product-orders/{productOrderId}/details`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) for details. These are the possible flows for partner product orders: ```mermaid stateDiagram-v2 direction LR [*] --> RECEIVED RECEIVED --> MERCHANT_VIEWED MERCHANT_VIEWED --> ORDER_SUBMITTED ORDER_SUBMITTED --> COMPLETED ORDER_SUBMITTED --> REJECTED RECEIVED --> EXPIRED MERCHANT_VIEWED --> EXPIRED COMPLETED --> [*] REJECTED --> [*] EXPIRED --> [*] ``` Product order status flow: An order starts as RECEIVED. From RECEIVED it can move to MERCHANT_VIEWED (the merchant has opened the prefilled URL), or directly to EXPIRED (after 14 days). From MERCHANT_VIEWED it can move to ORDER_SUBMITTED (the merchant has submitted) or EXPIRED. From ORDER_SUBMITTED it moves to either COMPLETED (approved) or REJECTED. COMPLETED, REJECTED, and EXPIRED are all terminal states. | Status | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RECEIVED` | The prefilled product order exists (it has been sent to us), but nothing has been done with it yet. | | `MERCHANT_VIEWED` | The prefilled URL has been opened and viewed by the merchant. | | `EXPIRED` | The prefilled product order has expired, which happens after 14 days. | | `ORDER_SUBMITTED` | The merchant has submitted a product order, which is waiting to be processed. | | `COMPLETED` | The product order was successfully completed. The accompanying sales unit information will also be returned at this point. | | `REJECTED` | The product order was rejected. For legal reasons we are not allowed to share the cause of rejection with partners, they should check directly with the merchant. | **INFO** - Only product orders made with prefill can contain all statuses. See the API specification for details. - The prefilled product orders expire after 14 days due to regulatory requirements. - The best way to check the detailed status of a product order is for the merchant to check on the [business portal](https://portal.vippsmobilepay.com). - See: [Typical reasons for delays](https://developer.vippsmobilepay.com/docs/partner/merchant-signup.md#typical-reasons-for-delays). ### Get a list of product orders The [`GET:/management/v2/product-orders`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint allows partners to get a list of all product orders where the partner is specified: - Product orders made with [`POST:/management/v1/product-orders`](https://developer.vippsmobilepay.com/docs/APIs/management-api/management-api-guide.md#prefill-a-product-order). - Product orders made with *Product order templates* (the links we create for you). - Product orders made by a merchant on the [business portal](http://portal.vippsmobilepay.com) without prefill or template. The contents of each order entry are the same as for the [`Get endpoint for specific orders`](#get-information-about-a-product-order), and the same limitations of what can be shared apply. By default, only orders with the `RECEIVED`, `MERCHANT_VIEWED`, `ORDER_SUBMITTED` and `COMPLETED` statuses 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. ::: ### Delete a product order The [`DELETE:/management/v1/product-orders/{prefilledProductOrderId}`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint allows 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`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml). It is not possible to delete product orders that have been submitted by a merchant. ## Partners ### Get the price packages for a partner Partners can use the [`GET:/management/v1/partners/price-packages`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml) endpoint to get a list of all their price packages, with the `pricePackageId` to use for [`POST:/management/v1/products/orders`](https://developer.vippsmobilepay.com/redocusaurus/management-swagger-id.yaml), as well as other details. Response: ```json [ { "pricePackageId": "8a11afb7-c223-48ed-8ca6-4722b97261aa", "name": "POS standard", "description": "2.99%", "visibleInSignupForm": true, "productType": "PAYMENT_INTEGRATION", "commission": "30 %" } ] ``` > **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).