Skip to main content
API docs by Redocly

PSP API v3 (1.0.20)

Download OpenAPI specification:Download

URL: https://developer.vippsmobilepay.com/

The Vipps PSP API allows PSPs to process Vipps payments as a part of their payment offerings. See the API Guide for more information.

Vipps PSP API

Endpoints and operations in the PSP API

Initiate a PSP payment

Initiate a payment

header Parameters
Authorization
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Merchant-Serial-Number
required
string

The Merchant Serial Number (MSN) is a unique id for the sales unit that this payment is made for. The Vipps number (MSN) for the merchant's sales unit.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your API product is available on portal.vipps.no, under the Utvikler tab. This is the PSP's key, and is the same for all the PSP's merchants. Keep it secret.

Psp-Id
required
string
Default: C948DFD1546347568874C4DDC93A2E3C
Example: C948DFD1546347568874C4DDC93A2E3C

PSP id is provided by Vipps. This is the PSP's id, and the same for all the PSP's merchants. This is a GUID value for PSPs created after 2020.

Vipps-System-Name
string <= 30 characters
Example: Acme Commerce

The name of the ecommerce solution. One word in lowercase letters is good. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Vipps-System-Version
string <= 30 characters
Example: 1.7

The version number of the ecommerce solution. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Request Body schema: application/json;charset=UTF-8

pspInitiatePaymentRequest

pspTransactionId
required
string <= 36 characters [a-z0-9]

Used as a globally unique per PSP transaction reference for the PSP systems

merchantOrderId
required
string <= 50 characters ^[a-zA-Z0-9-]{1,50}$

Id which uniquely identifies a payment. Maximum length is 50 alphanumeric characters: a-z, A-Z, 0-9 and '-'. See: https://developer.vippsmobilepay.com/docs/common-topics/orderid/ (merchantOrderId is similar to orderId).

customerMobileNumber
string <= 8 characters ^\d{8}

Mobile number (eight digits) of the user who has to pay for the transaction from Vipps.

amount
required
integer <int32>

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

currency
required
string
Default: "NOK"

ISO 4217 defined currency code. Vipps currently only supports NOK.

pspRedirectUrl
required
string

Vipps will use this URL to redirect end user after payment confirmation. Important: Do not rely on the user always reaching this URL, as some users may close Vipps immediately after seeing the payment confirmation, therefore not being "redirected" back to the merchant.

makePaymentUrl
required
string
makePaymentToken
string <= 255 characters

PSP-specified Authorization HTTP header tu use foer the request to the PSP's makePaymentUrl.

paymentText
string

Text to be displayed to end user. The text should be as user-friendly and informative as possible. See: https://developer.vippsmobilepay.com/docs/common-topics/transactiontext/ (transactionText is similar to paymentText).

isApp
boolean
Default: false

Optional parameter. Indicates whether payment request is triggered from a mobile app or a web browser. See: https://developer.vippsmobilepay.com/docs/common-topics/isApp/

skipLandingPage
boolean
Default: false

Optional parameter. Skips the landing page for whitelisted sales units. Requires a valid customerMobileNumber. See: https://developer.vippsmobilepay.com/docs/common-topics/landing-page/

scope
string (Scope)
Default: "psp_subscription"
Value: "psp_subscription"

A scope for future payments you want to process with the userToken. Current available scopes are "psp_subscription"

merchantAgreementUrl
string

For use with PSP Recurring scope: psp_subscription, provides the user a link back to the merchants surfaces from their agreement overview in the Vipps App.

Responses

Request samples

Content type
application/json;charset=UTF-8
{}

Response samples

Content type
application/json;charset=UTF-8
{}

Delete a payment agreement

Used to cancel a recurring agreement

header Parameters
Authorization
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Merchant-Serial-Number
required
string

The Merchant Serial Number (MSN) is a unique id for the sales unit that this payment is made for. The Vipps number (MSN) for the merchant's sales unit.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your API product is available on portal.vipps.no, under the Utvikler tab. This is the PSP's key, and is the same for all the PSP's merchants. Keep it secret.

Psp-Id
required
string
Default: C948DFD1546347568874C4DDC93A2E3C
Example: C948DFD1546347568874C4DDC93A2E3C

PSP id is provided by Vipps. This is the PSP's id, and the same for all the PSP's merchants. This is a GUID value for PSPs created after 2020.

User-Token
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

JWT

Vipps-System-Name
string <= 30 characters
Example: Acme Commerce

The name of the ecommerce solution. One word in lowercase letters is good. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Vipps-System-Version
string <= 30 characters
Example: 1.7

The version number of the ecommerce solution. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get card data to process a payment with token

Request a MIT payment for a recurring agreement, provides card details for processing. A updatestatus call should be made afterwards with the result of the authorisation.

header Parameters
Authorization
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your API product is available on portal.vipps.no, under the Utvikler tab. This is the PSP's key, and is the same for all the PSP's merchants. Keep it secret.

Psp-Id
required
string
Default: C948DFD1546347568874C4DDC93A2E3C
Example: C948DFD1546347568874C4DDC93A2E3C

PSP id is provided by Vipps. This is the PSP's id, and the same for all the PSP's merchants. This is a GUID value for PSPs created after 2020.

Merchant-Serial-Number
required
string

The Merchant Serial Number (MSN) is a unique id for the sales unit that this payment is made for. The Vipps number (MSN) for the merchant's sales unit.

User-Token
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

JWT

Vipps-System-Name
string <= 30 characters
Example: Acme Commerce

The name of the ecommerce solution. One word in lowercase letters is good. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Vipps-System-Version
string <= 30 characters
Example: 1.7

The version number of the ecommerce solution. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Request Body schema: application/json;charset=UTF-8

ProcessPaymentOnToken

pspTransactionId
string

Used as a globally unique transaction reference for the PSP systems

merchantOrderId
string <= 50 characters ^[a-zA-Z0-9-]{1,50}$

Id which uniquely identifies a payment. Maximum length is 50 alphanumeric characters: a-z, A-Z, 0-9 and '-'. See: https://developer.vippsmobilepay.com/docs/common-topics/orderid/ (merchantOrderId is similar to orderId).

amount
integer <int32>

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

currency
string

ISO 4217 defined currency code. Currently Vipps only supports NOK

paymentText
string

Text to be displayed to end user. The text should be as user-friendly and informative as possible. See: https://developer.vippsmobilepay.com/docs/common-topics/transactiontext/ (transactionText is similar to paymentText).

Responses

Request samples

Content type
application/json;charset=UTF-8
{
  • "pspTransactionId": "7686f7788898767977",
  • "merchantOrderId": "acme-shop-123-order123abc",
  • "amount": 49900,
  • "currency": "NOK",
  • "paymentText": "Description of payment"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "pspTransactionId": "7686f7788898767977",
  • "merchantOrderId": "acme-shop-123-order123abc",
  • "paymentInstrument": "TOKEN",
  • "networkToken": {
    }
}

Update the status of the PSP transaction.

Since Vipps doesn't process the PSP transactions, updates on payment status are required in order to deliver expected customer experience. That means that PSP has to inform Vipps about any PSP payment status change through this endpoint. Valid requests get a HTTP 200 OK response, but the actual update is done in a batch job during the night. See the API guide for more details: https://developer.vippsmobilepay.com/docs/APIs/psp-api/vipps-psp-api#batch-processing-of-status-updates

header Parameters
Authorization
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Merchant-Serial-Number
required
string

The Merchant Serial Number (MSN) is a unique id for the sales unit that this payment is made for. The Vipps number (MSN) for the merchant's sales unit.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your API product is available on portal.vipps.no, under the Utvikler tab. This is the PSP's key, and is the same for all the PSP's merchants. Keep it secret.

Psp-Id
required
string
Default: C948DFD1546347568874C4DDC93A2E3C
Example: C948DFD1546347568874C4DDC93A2E3C

PSP id is provided by Vipps. This is the PSP's id, and the same for all the PSP's merchants. This is a GUID value for PSPs created after 2020.

Vipps-System-Name
string <= 30 characters
Example: Acme Commerce

The name of the ecommerce solution. One word in lowercase letters is good. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Vipps-System-Version
string <= 30 characters
Example: 1.7

The version number of the ecommerce solution. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Request Body schema: application/json

pspPaymentStatus

Array of objects (TransactionInfo)
Array
pspTransactionId
required
string

Used as a globally unique per PSP transaction reference for the PSP systems

status
required
string
Enum: "RESERVED" "CAPTURED" "CANCELLED" "REFUNDED"

PSP transaction status to be updated in Vipps

amount
required
integer <int32>

Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.

currency
string
Default: "NOK"

ISO 4217 defined currency code. Vipps currently only supports NOK.

paymentText
string

Text to be displayed to end user. The text should be as user-friendly and informative as possible. See: https://developer.vippsmobilepay.com/docs/common-topics/transactiontext/ (transactionText is similar to paymentText).

operationStatus
string
Default: "SUCCESS"
Enum: "FAILED" "SUCCESS"

The operation result for the status performed (ie informing a reserve failed for recurring processing)

Responses

Request samples

Content type
application/json
{
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "responseInfo": {
    }
}

Get the details of the PSP payment

Get the details of a payment

path Parameters
pspTransactionId
required
string
Example: 7686f7788898767977

Used as a globally unique per PSP transaction reference for the PSP systems.

header Parameters
Authorization
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Merchant-Serial-Number
required
string

The Merchant Serial Number (MSN) is a unique id for the sales unit that this payment is made for. The Vipps number (MSN) for the merchant's sales unit.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your API product is available on portal.vipps.no, under the Utvikler tab. This is the PSP's key, and is the same for all the PSP's merchants. Keep it secret.

Psp-Id
required
string
Default: C948DFD1546347568874C4DDC93A2E3C
Example: C948DFD1546347568874C4DDC93A2E3C

PSP id is provided by Vipps. This is the PSP's id, and the same for all the PSP's merchants. This is a GUID value for PSPs created after 2020.

Vipps-System-Name
string <= 30 characters
Example: Acme Commerce

The name of the ecommerce solution. One word in lowercase letters is good. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Vipps-System-Version
string <= 30 characters
Example: 1.7

The version number of the ecommerce solution. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Responses

Response samples

Content type
application/json
{
  • "pspTransactionId": "7686f7788898767977",
  • "merchantOrderId": "acme-shop-123-order123abc",
  • "transactionSummary": {
    },
  • "transactionLogHistory": [
    ]
}

Force Approve Payment

This endpoint allows developers to approve a psp payment through the Vipps PSP API without the use of the Vipps app. This is useful for automated testing. The endpoint is only available in our Test environment. Attempted use of the endpoint in production is not allowed, and will fail. Important: All test users must manually approve at least one payment in Vipps (using the app) before this endpoint can be used for that user. See: https://developer.vippsmobilepay.com/docs/test-environment/

path Parameters
pspTransactionId
required
string
Example: 7686f7788898767977

Used as a globally unique per PSP transaction reference for the PSP systems.

header Parameters
Authorization
required
string
Default: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)

The access token is a base64-encoded string that is required for all API calls. It is a JWT (JSON Web Token). The access token is fetched from the POST:/accesstoken/get endpoint. It is valid for 1 hour in the test environment and 24 hours in the production environment.

Ocp-Apim-Subscription-Key
required
string
Example: 0f14ebcab0ec4b29ae0cb90d91b4a84a

The subscription key for your API product is available on portal.vipps.no, under the Utvikler tab. This is the PSP's key, and is the same for all the PSP's merchants. Keep it secret.

Merchant-Serial-Number
required
string

The Merchant Serial Number (MSN) is a unique id for the sales unit that this payment is made for. The Vipps number (MSN) for the merchant's sales unit.

Psp-Id
required
string
Default: C948DFD1546347568874C4DDC93A2E3C
Example: C948DFD1546347568874C4DDC93A2E3C

PSP id is provided by Vipps. This is the PSP's id, and the same for all the PSP's merchants. This is a GUID value for PSPs created after 2020.

Vipps-System-Name
string <= 30 characters
Example: Acme Commerce

The name of the ecommerce solution. One word in lowercase letters is good. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Vipps-System-Version
string <= 30 characters
Example: 1.7

The version number of the ecommerce solution. See: https://developer.vippsmobilepay.com/docs/common-topics/http-headers/

Request Body schema: application/json;charset=UTF-8

ForceApproveRequest

customerPhoneNumber
required
string^\d{8}$

Target customer phone number. 8 digits.

token
required
string

The token value received in the url property in the Initiate response

Responses

Request samples

Content type
application/json;charset=UTF-8
{
  • "customerPhoneNumber": "91234567",
  • "token": "eyJraWQiOiJqd3R"
}

Endpoints required by Vipps from the PSP

Calls from Vipps to the PSP

Service endpoint exposed by the PSP

Used by Vipps to send the card network token from the Vipps token requestor service to the PSP to complete the initialized transaction. The PSP will use the token to process the payment and then send the outcome (RESERVE, CAPTURE or REJECT) to Vipps using the POST:/updatestatus endpoint. Communication security is established by using 1-way SSL and makePaymentToken. The response must use Content-Type application/json.

header Parameters
Authorization
required
string

Token provided by the PSP as 'makePaymentToken' in the /v3/psppayments/init call.

Request Body schema: application/json;charset=UTF-8

makePaymentRequest

pspTransactionId
required
string

Used as a globally unique per PSP transaction reference for the PSP systems

merchantSerialNumber
required
string = 6 characters ^\d{6}$

The Vipps number (MSN) for the merchant's sales unit.

paymentState
required
string
Enum: "ACCEPTED" "TIMEOUT" "USER_CANCEL"

Credit Card Details Encryption Status

userToken
string

JWT-TOKEN

binNumber
required
string

BIN number for the card

required
Array of objects (Operation3DSecure)
paymentInstrument
required
string (PaymentInstrument)
Default: "TOKEN"
Value: "TOKEN"
required
object (NetworkToken)

Responses

Request samples

Content type
application/json;charset=UTF-8
{
  • "pspTransactionId": "7686f7788898767977",
  • "merchantSerialNumber": "123456",
  • "paymentState": "ACCEPTED",
  • "userToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni (truncated)",
  • "binNumber": "492556",
  • "operations": [],
  • "paymentInstrument": "TOKEN",
  • "networkToken": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "errorMessage": {
    },
  • "paymentInfo": {}
}