Skip to main content
API docs by Redocly

PSP API v3 (1.0.21)

Download OpenAPI specification:Download

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

The PSP API allows Payment Service Providers (PSPs) to process Vipps payments as a part of their payment offerings. See the PSP API guide for more details.

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 to which this payment is made. This is the identity of the merchant's sales unit.

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

This is your PSP subscription key, used to create and manage payments for all your 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/knowledge-base/http-headers/

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

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

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

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/knowledge-base/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 to use for the request to the PSP's makePaymentUrl.

paymentText
string <= 100 characters

Text to be displayed to end user. The text should be as user-friendly and informative as possible. See: https://developer.vippsmobilepay.com/docs/knowledge-base/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/knowledge-base/app-flow/

skipLandingPage
boolean
Default: false

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

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

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.vipps.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 to which this payment is made. This is the identity of the merchant's sales unit.

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

This is your PSP subscription key, used to create and manage payments for all your 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/knowledge-base/http-headers/

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

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

Request Body schema: application/json
required

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/knowledge-base/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 to which this payment is made. This is the identity of the merchant's sales unit.

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

This is your PSP subscription key, used to create and manage payments for all your 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/knowledge-base/http-headers/

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

The version number of the ecommerce solution. See: https://developer.vippsmobilepay.com/docs/knowledge-base/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 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.vipps.com/docs/knowledge-base/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

This is your PSP subscription key, used to create and manage payments for all your merchants. Keep it secret.

Merchant-Serial-Number
required
string

The Merchant Serial Number (MSN) is a unique ID for the sales unit to which this payment is made. This is the identity of 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/knowledge-base/http-headers/

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

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

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

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": "12345678",
  • "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
required

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 identity for the merchant's sales unit (MSN).

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