PSP Signup API guide

The PSP Signup API lets Payment Service Providers (PSPs) onboard and manage merchants who accept Vipps MobilePay payments.

MobilePay Online

👉 Go to MobilePay Online API

Introduction

A PSP can use its existing API keys to access this API, and perform the following:

List one or all merchants under them
Create a new merchant under them
Update an existing merchant

Merchant information

Each merchant you create through this API corresponds to a sales unit in the Vipps MobilePay system. One company can have multiple sales units (for example, separate stores or apps), each with its own Merchant Serial Number (MSN).

Some or all of the information will be displayed on the landing page and payment screens.

Merchant name

The name of the store, app, or service. This is what you set in the name field. Note that in the Vipps MobilePay business portal, this same value is labelled sales unit name — so if you set "Fresh Cakes" as the merchant name, it will appear as the sales unit name in the portal.

This name is specified in the name field when you create the merchant. It can be changed with the update a merchant request.

Company name

Company name is the legal name of the business that owns the store, app, or service. This name is specified in the companyName field when you create the merchant. It can be changed with the update a merchant request, but the change may not be reflected in the app.

Merchant Serial Number

The Merchant Serial Number (MSN) is a number for identifying the merchant (sales unit). For identifying the company, use the organization number.

The MSN is assigned when you create a merchant. This number can't be changed.

Organization number

The organization number is a unique identifier for a business and can be used to retrieve information from the national registries for the country in which the business operates. You specify the organization number in the organizationNumber field when you create a merchant.

This value can't be changed through the API. The only workaround is to deactivate the merchant and create a new one. The new merchant will have a new MSN.

Logo

The merchant logo is displayed on the landing page and payment screens. This logo is specified in the logo field as a base64-encoded PNG image when you create the merchant.

Logo requirements:

Format: PNG
Minimum size: 100 × 100 pixels
Maximum size: 1000 pixels on the longest side
Square images are recommended

The logo can be updated at any time with the update a merchant request. See Update an existing merchant for details.

Merchant status

A merchant's status field indicates its current state:

Status	Description
`PENDING`	The merchant has been created but is not yet active. This is the initial state.
`ACTIVE`	The merchant is active and can process payments.
`DEACTIVATED`	The merchant has been deactivated and cannot be reactivated or updated.

A newly created merchant starts in PENDING status and transitions to ACTIVE once the setup is complete. To deactivate a merchant, see Deactivate a merchant.

Customer-facing screens

The merchant information you provide through this API is shown to customers during payment. The following shows which fields appear where.

The landing page

Vipps
MobilePay

Vipps landing page

Merchant name - The name of the store, app, or service. Set via the name field.
Customer phone number - This field can be prefilled through a payment API, or can be empty, allowing the customer to enter their own phone number.

The payment screen

Vipps
MobilePay

Vipps Payment Screen

Logo - Set via the logo field.
Merchant name - The name of the store, app, or service. Set via the name field.
Company name - The legal name of the business. Set via the companyName field.
Merchant Serial Number - Identifier for the merchant (sales unit). Assigned by this API when you create the merchant.
Payment description - Set via the payment initiation request, not via this API.

API requests

Key identifiers

Value	Scope	Where it comes from
`PSP-ID`	Your PSP account — the same for all your merchants	Provided by Vipps MobilePay when you become a partner
`client_id` / `client_secret`	Your PSP account	Provided by Vipps MobilePay when you become a partner
`Ocp-Apim-Subscription-Key`	Your PSP account	Provided by Vipps MobilePay when you become a partner
`merchantSerialNumber` (MSN)	One specific merchant	Returned by this API when you create a merchant

Get all merchants

For a JSON response showing all the merchants and their information, send GET:/merchant-management/psp/v1/merchants.

Example request (API spec):

curl -X GET https://apitest.vipps.no/merchant-management/psp/v1/merchants \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6"

Example response:

{
    "merchants": [
        {
            "organizationNumber": "123456789",
            "companyName": "Pastry Bakery AS",
            "companyEmail": "info@example.com",
            "merchantSerialNumber": "123456",
            "name": "Fresh Cakes",
            "status": "ACTIVE",
            "email": "info@example.com",
            "website": "https://example.com",
            "createdAt": "2023-08-21T07:54:23.602Z",
            "updatedAt": "2024-09-23T10:34:03.239Z",
            "address": {
                "addressLine1": "Sognefjellsvegen 7",
                "addressLine2": "",
                "city": "Fossbergom",
                "postCode": "2686",
                "country": "NO"
            }
        },
        {
            "organizationNumber": "987654321",
            "companyName": "Blues Brothers AS",
            "companyEmail": "info@example.com",
            "merchantSerialNumber": "223456",
            "name": "Blues Brothers Music",
            "status": "ACTIVE",
            "email": "info@example.com",
            "website": "https://example.com",
            "createdAt": "2023-08-21T07:54:23.602Z",
            "updatedAt": "2024-09-23T10:34:03.239Z",
            "address": {
                "addressLine1": "Felegate 1",
                "addressLine2": "",
                "city": "Oslo",
                "postCode": "0154",
                "country": "NO"
            }
        }
    ]
}

You can use the merchantSerialNumber to get information for a specific merchant.

Get information about a specific merchant

For information about a specific merchant, send GET:/merchant-management/psp/v1/merchants/{merchantSerialNumber}. Supply the MSN. This will only provide information from your list of merchants.

Example request (API spec):

curl -X GET https://apitest.vipps.no/merchant-management/psp/v1/merchants/{merchantSerialNumber} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6"

Example response:

{
    "organizationNumber": "123456789",
    "companyName": "Pastry Bakery AS",
    "companyEmail": "info@example.com",
    "merchantSerialNumber": "123456",
    "name": "Fresh Cakes",
    "mccCode": null,
    "status": "ACTIVE",
    "email": "info@example.com",
    "website": "https://example.com",
    "createdAt": "2023-08-21T07:54:23.602Z",
    "updatedAt": "2024-09-23T10:34:03.239Z",
    "address": {
        "addressLine1": "Sognefjellsvegen 7",
        "addressLine2": "",
        "city": "Fossbergom",
        "postCode": "2686",
        "country": "NO"
    }
}

Please note: The mccCode may be returned as null, this is expected.

Create a new merchant

To create a new merchant, send POST:/merchant-management/psp/v1/merchants.

The request requires an Idempotency-Key header — a unique value (e.g., a UUID) that you generate per request. If a request fails or times out, you can safely retry it using the same key without risk of creating duplicate merchants.

Provide the organization number for the business.

In Norway, the organizationNumber must be 9 digits without spaces, the business must be active in the Norwegian business registry and the organization number must be for the main entity ("hovedenhet"), not a sub entity ("underenhet"). For other countries: The organization number, address, and other information are validated as much as practically possible.

Example request (API spec):

curl -X POST https://apitest.vipps.no/merchant-management/psp/v1/merchants \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
--data '{
   "organizationNumber": "123456789",
   "name": "Fresh Cakes",
   "mccCode": "5411",
   "logo": "VGhlIGltYWdlIGdvZXMgaGVyZQ== (truncated)",
   "email": "info@example.com",
   "website": "https://example.com",
   "address": {
      "addressLine1": "Sognefjellsvegen 7",
      "addressLine2": "",
      "city": "Fossbergom",
      "postCode": "2686",
      "country": "NO"
   },
   "companyName": "Pastry Bakery AS",
   "companyEmail": "info@example.com"
}'

For the country field, we support all ISO 3166 country codes.

The response contains the assigned merchantSerialNumber (MSN) for the new merchant:

{
   "merchantSerialNumber": "123456"
}

Store this MSN — it is required to identify the merchant in all subsequent API calls.

Update an existing merchant

To update a merchant, send PATCH:/merchant-management/psp/v1/merchants/{merchantSerialNumber}. Provide the MSN and update the details in the body section.

You can update any of the following fields:

name - Merchant name
logo - Base64-encoded PNG image
email - Contact email for the merchant
website - Merchant website URL
address - Address information
mccCode - Merchant category code (ISO 18245, four digits)
companyName - Legal name of the business

Example: Update merchant name (API spec):

curl -X PATCH https://apitest.vipps.no/merchant-management/psp/v1/merchants/{merchantSerialNumber} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
--data '{"name": "Bakery in Fossbergom"}'

Example: Update logo (API spec):

curl -X PATCH https://apitest.vipps.no/merchant-management/psp/v1/merchants/{merchantSerialNumber} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
--data '{"logo": "YOUR-BASE64-ENCODED-PNG"}'

You can update multiple fields in a single request by including them all in the request body.

Deactivate a merchant

To deactivate a merchant, send PATCH:/merchant-management/psp/v1/merchants/{merchantSerialNumber} with deactivate set to true.

Example (API spec):

curl -X PATCH https://apitest.vipps.no/merchant-management/psp/v1/merchants/{merchantSerialNumber} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "PSP-ID: YOUR-PSP-ID" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
--data '{"deactivate": true}'

Once deactivated, the merchant cannot be reactivated or updated through the API. If the merchant's organizationNumber or other immutable fields need to change, you must deactivate the existing merchant and create a new one with a new MSN.

caution

Deactivation is permanent and cannot be undone.

Error responses

Error responses follow the RFC 7807 Problem Details format:

{
   "type": "https://example.net/validation-error",
   "title": "Postcode validation error",
   "status": 400,
   "detail": "Postcode must be four digits",
   "instance": "https://example.net/validation-error/postcode"
}

Field	Description
`type`	A URI identifying the problem type
`title`	A short, human-readable summary of the problem
`status`	The HTTP status code
`detail`	A human-readable explanation to help correct the problem
`instance`	A URI identifying this specific occurrence of the problem

info

PSP sales units can only be updated using the PSP Signup API. The sales units can't be managed on the business portal.

Companies that only have PSP sales units cannot log in on the business portal, since it is only for managing sales units that use a direct integration (not through a PSP).

Questions

The API Reference contains more details for each endpoint.

If you have any questions, please reach out to us:

Directly to your Partner Manager
psp@vippsmobilepay.com

Introduction​

Merchant information​

Merchant name​

Company name​

Merchant Serial Number​

Organization number​

Logo​

Merchant status​

Customer-facing screens​

The landing page​

The payment screen​

API requests​

Get all merchants​

Get information about a specific merchant​

Create a new merchant​

Update an existing merchant​

Deactivate a merchant​

Error responses​

Questions​

Introduction

Merchant information

Merchant name

Company name

Merchant Serial Number

Organization number

Logo

Merchant status

Customer-facing screens

The landing page

The payment screen

API requests

Get all merchants

Get information about a specific merchant

Create a new merchant

Update an existing merchant

Deactivate a merchant

Error responses

Questions