Skip to main content

Vipps eCommerce API (1.6.36)

Download OpenAPI specification:Download

For details, see the API Guide.

Authorization Service

Authorization Service

Fetch the JWT authorization token

The access token endpoint is used to get the JWT (JSON Web Token) that must be passed in every API request in the Authorization header. The access token is a base64-encoded string value that must be acquired first before making any Vipps API calls. The access token is valid for 1 hour in the test environment and 24 hours in the production environment.

header Parameters
client_id
required
string <guid>
Example: fb492b5e-7907-4d83-ba20-c7fb60ca35de

The client_id is available on portal.vipps.no, under the 'Utvikler' tab.

client_secret
required
string
Example: Y8Kteew6GE2ZmeycEt6egg==

The client_secret is available on portal.vipps.no, under the 'Utvikler' tab. Keep it secret.

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

The subscription key for the authorization token is available on portal.vipps.no, under the 'Utvikler' tab. Keep it secret.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "ext_expires_in": 3600,
  • "expires_on": 1547823408,
  • "not_before": 1547819508,
  • "resource": "00000002-0000-0000-c000-000000000000",
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni..."
}

Vipps eCom API

Functionality provided by the Vipps eCommerce API. For details, see the API Guide.

Initiate Payment

This API call lets the merchants initiate payments. The merchantSerialNumber (MSN) specifies which sales unit the payment is for. Payments are uniquely identified with the merchantSerialNumber and orderId together. The merchant-provided orderId must be unique per sales unit. Once the transaction is successfully initiated in Vipps, you will receive a response with a URL that will direct the customer to the Vipps landing page (when using a laptop/desktop), or app-switch to Vipps (when using a phone). The landing page detects if the request comes from a mobile or laptop/desktop device, and if on a mobile device automatically switches to the Vipps app, if it is installed. The merchant may also pass the optional 'isApp: true' parameter that will make Vipps respond with a app-switch deeplink that will take the customer directly to the Vipps app. This is normally not necessary, as Vipps handles this automatically. URLs passed to Vipps must validate, see the API guide. The URLs must use HTTPS.

header Parameters
Authorization
required
string
Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

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.

Content-Type
required
string
Example: application/json

The content type must be application/json

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. Keep it secret.

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique id for the sale unit that this payment is made for. This is a required parameter if you are a Vipps eCom partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps merchants making payments for themselves.

Vipps-System-Name
string
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good.

Vipps-System-Version
string
Example: 5.4

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.

Vipps-System-Plugin-Version
string
Example: 1.2.1

The version number of the ecommerce plugin (if applicable).

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

initiatePaymentCommand

required
object (CustomerInfo)
required
object (MerchantInfo)

Information about the merchant.

required
object (TransactionInfoInitiate)

Responses

Callbacks

Request samples

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

Response samples

Content type
application/json;charset=UTF-8
{
  • "orderId": "acme-shop-123-order123abc",
  • "url": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJraWQiOiJqd3RrZXkiLC <snip>"
}

Callback payload samples

Callback
Content type
application/json;charset=UTF-8
{
  • "merchantSerialNumber": "123456",
  • "orderId": "acme-shop-123-order123abc",
  • "shippingDetails": {
    },
  • "transactionInfo": {
    },
  • "userDetails": {
    },
  • "errorInfo": {
    }
}

Capture Payment

This API call lets merchant capture the reserved amount. Amount to capture cannot be higher than reserved. The API also allows capturing a partial amount of the reserved amount. Partial capture can be called as many times as required so long there is a remaining reserved amount to capture. The transaction text is not optional and is used as a proof of delivery (tracking code, consignment number etc.). In a case of direct capture, both the reservation and the capture are executed in a single operation. It is important to check the response, and the capture is only successful when the response is HTTP 200 OK.

path Parameters
orderId
required
string

The orderId is specified when initiating the payment.

header Parameters
Authorization
required
string
Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

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.

Content-Type
required
string
Example: application/json

The content type must be application/json

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. Keep it secret.

X-Request-Id
required
string
Example: kRk3uEeiogxLu1yGSZRlNgsIv3TuNS

Used for making requests idempotent. Adding the X-Request-Id header will allow repeated requests without it making additional changes. Unique for orderId, merchantSerialNumber and endpoint. Required for making partial captures. You can use any unique id for your X-Request-Id. Max 40 characters.

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique id for the sale unit that this payment is made for. This is a required parameter if you are a Vipps eCom partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps merchants making payments for themselves.

Vipps-System-Name
string
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good.

Vipps-System-Version
string
Example: 5.4

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.

Vipps-System-Plugin-Version
string
Example: 1.2.1

The version number of the ecommerce plugin (if applicable).

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

paymentActionsRequest

object (MerchantInfoPayment)
object (Transaction)

Responses

Request samples

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

Response samples

Content type
application/json;charset=UTF-8
{
  • "paymentInstrument": "Mastercard",
  • "orderId": "acme-shop-123-order123abc",
  • "transactionInfo": {
    },
  • "transactionSummary": {
    }
}

Cancel Payment

This API call lets merchants cancel a reserved or initiated transaction as long as it is less than 6 months old. In order to enable cancellation of remaining funds after partial capture, the shouldReleaseRemainingFunds flag must be set. Please note that the payment will be cancelled by Vipps even in cases of communication errors during an initiate payment service call between Vipps and PSP/Acquirer/Issuer and even in cases where the customer has confirmed a payment. Note this means you cannot cancel a captured payment.

path Parameters
orderId
required
string

The orderId is specified when initiating the payment.

header Parameters
Authorization
required
string

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.

Content-Type
required
string
Example: application/json

The content type must be application/json

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. Keep it secret.

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique id for the sale unit that this payment is made for. This is a required parameter if you are a Vipps eCom partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps merchants making payments for themselves.

Vipps-System-Name
string
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good.

Vipps-System-Version
string
Example: 5.4

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.

Vipps-System-Plugin-Version
string
Example: 1.2.1

The version number of the ecommerce plugin (if applicable).

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

paymentActionsRequest

required
object (MerchantInfoPayment)
required
object (CancelTransaction)
shouldReleaseRemainingFunds
boolean
Default: false

An opt-in field to instruct the release of remaining funds after a partial capture.

Responses

Request samples

Content type
application/json;charset=UTF-8
{
  • "merchantInfo": {
    },
  • "transaction": {
    },
  • "shouldReleaseRemainingFunds": false
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "paymentInstrument": "Mastercard",
  • "orderId": "acme-shop-123-order123abc",
  • "transactionInfo": {
    },
  • "transactionSummary": {
    }
}

Refund Payment

The API lets a merchant do a refund of an already captured transaction. There is an option to do a partial refund of the captured amount. Refunded amount cannot be larger than captured. Time frame for issuing a refund for a payment is 365 days from the date payment has been captured. If the refund payment service call is called after the refund time frame, service call will respond with an error. Refunded funds will be transferred from the merchant account to the customer credit card that was used in payment flow. Pay attention that in order to perform refund, there must be enough funds at merchant settlements account.

path Parameters
orderId
required
string

The orderId is specified when initiating the payment.

header Parameters
Authorization
required
string
Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

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.

Content-Type
required
string
Example: application/json

The content type must be application/json

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. Keep it secret.

X-Request-Id
required
string
Example: kRk3uEeiogxLu1yGSZRlNgsIv3TuNS

Used for making requests idempotent. Adding the X-Request-Id header will allow repeated requests without it making additional changes. Unique for orderId, merchantSerialNumber and endpoint. Max 40 characters. Required if the amount is partial.

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique id for the sale unit that this payment is made for. This is a required parameter if you are a Vipps eCom partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps merchants making payments for themselves.

Vipps-System-Name
string
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good.

Vipps-System-Version
string
Example: 5.4

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.

Vipps-System-Plugin-Version
string
Example: 1.2.1

The version number of the ecommerce plugin (if applicable).

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

paymentActionsRequest

object (MerchantInfoPayment)
object (Transaction)

Responses

Request samples

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

Response samples

Content type
application/json;charset=UTF-8
{
  • "orderId": "acme-shop-123-order123abc",
  • "transaction": {
    },
  • "transactionSummary": {
    }
}

Force Approve Payment

This endpoint lets developers approve a payment through the Vipps eCom API without the use of the Vipps app. This is useful for automated testing. Express checkout is not supported for this endpoint. 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.

path Parameters
orderId
required
string

The orderId is specified when initiating the payment.

header Parameters
Authorization
required
string
Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

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.

Content-Type
required
string
Example: application/json

The content type must be application/json

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. Keep it secret.

X-Request-Id
string
Example: kRk3uEeiogxLu1yGSZRlNgsIv3TuNS

Id used for making requests idempotent. Adding this ID will allow the merchant to retry requests without it making additional changes. Unique for orderId, merchantSerialNumber and endpoint. Max 40 characters.

Vipps-System-Name
string
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good.

Vipps-System-Version
string
Example: 5.4

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.

Vipps-System-Plugin-Version
string
Example: 1.2.1

The version number of the ecommerce plugin (if applicable).

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

ForceApproveRequest

customerPhoneNumber
string^\d{8}$

Target customer phone number. 8 digits.

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

Response samples

Content type
application/json;charset=UTF-8
Example
[ ]

Get Payment Details

This API call lets merchant get the details of a payment transaction. Service call returns detailed transaction history of given payment where events are sorted from newest to oldest for when the transaction occurred.

path Parameters
orderId
required
string

The orderId is specified when initiating the payment.

header Parameters
Authorization
required
string
Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

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.

Content-Type
required
string
Example: application/json

The content type must be application/json

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. Keep it secret.

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique id for the sale unit that this payment is made for. This is a required parameter if you are a Vipps eCom partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps merchants making payments for themselves.

Vipps-System-Name
string
Example: woocommerce

The name of the ecommerce solution. One word in lowercase letters is good.

Vipps-System-Version
string
Example: 5.4

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string
Example: vipps-woocommerce

The name of the ecommerce plugin (if applicable). One word in lowercase letters is good.

Vipps-System-Plugin-Version
string
Example: 1.2.1

The version number of the ecommerce plugin (if applicable).

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "orderId": "acme-shop-123-order123abc",
  • "shippingDetails": {
    },
  • "transactionLogHistory": [
    ],
  • "transactionSummary": {
    },
  • "userDetails": {
    },
  • "sub": "string"
}

Deprecated: Get Order Status Deprecated

This deprecated endpoint lets the merchant get the status of the last payment transaction. The response may be confusing. Please use /details instead, as it offers more information.

path Parameters
orderId
required
string

The orderId is specified when initiating the payment.

header Parameters
Authorization
required
string
Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

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. Keep it secret.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "orderId": "acme-shop-123-order123abc",
  • "transactionInfo": {
    }
}

Merchant Endpoints

These endpoints must be implemented by the merchant, and are called by Vipps.

Remove User Consent (for Vipps Hurtigkasse (express checkout))

This API endpoint on the merchant side lets Vipps send consent removal requests to the merchant. When receiving requests the merchant is obliged to remove the user details permanently, as per the GDPR guidelines. Vipps will add /v2/consents/{userId} to the end of this URL. URLs passed to Vipps must validate, see the API guide. We don't send requests to all ports, so to be safe use common ports such as: 80, 443, 8080. The URL must use HTTPS.

path Parameters
userId
required
string
Example: uiJskNQ6qNN1iwN891uuob==

URL-encoded userId provided when requesting user information from Vipps. Received by callback or with /detail request.

Responses

Fetch Shipping Cost & Method (for Vipps Hurtigkasse (express checkout))

This API endpoint on the merchant side lets Vipps get the shipping cost and method based on the provided address and product details. The primary use of this service is Vipps Hurtigkasse (express checkout) where Vipps needs to present shipping cost and method to the Vipps user. Vipps will add /v2/payments/{orderId}/shippingDetails to the end of this URL. Vipps has a 10 second timeout for these requests, to ensure a good user experience, and thus requires a quick reply from the merchant's server for successful payments. URLs passed to Vipps must validate, see the API guide. We don't send requests to all ports, so to be safe use common ports such as: 80, 443, 8080. The URL must use HTTPS.

path Parameters
orderId
required
string
Example: acme-shop-123-order123abc

orderId

header Parameters
Authorization
string
Example: ae0cb90d91b4a84a

The token provided by the merchant in the initiate payment request as authToken (an optional parameter). Vipps uses this token when making calls to the merchant's servers. Used so that the merchant may authenticate the request from Vipps.

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

ShippingCostAndMethod

addressId
required
integer <int32>

Vipps Provided address Id. To be returned in response in the same field

addressLine1
required
string
addressLine2
string
city
required
string

City

country
required
string
Default: "NO"

The only country supported is Norway

postCode
required
string^\d{4}$

Four digits for Norway.

addressType
string^\[A-Z]$
Default: "H"
Enum: "H" "W" "O"

The type of address: Home, Work, Other.

Responses

Request samples

Content type
application/json;charset=UTF-8
{
  • "addressId": 100,
  • "addressLine1": "Robert Levins gate 5",
  • "addressLine2": "c/o Rune Garborg",
  • "city": "Oslo",
  • "country": "NO",
  • "postCode": "0154",
  • "addressType": "H"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "addressId": 0,
  • "orderId": "acme-shop-123-order123abc",
  • "shippingDetails": [
    ]
}

Callback : Transaction Update

This API call lets Vipps send the transaction details. For regular eCom payments the order and transaction details will be shared. For Vipps Hurtigkasse (express checkout) payments it will provides user details and shipping details addition to the order and transaction details. Vipps will add /v2/payments/{orderId} to the end of this URL. URLs passed to Vipps must validate, see the API guide. We don't send requests to all ports, so to be safe use common ports such as: 80, 443, 8080. The URL must use HTTPS.

path Parameters
orderId
required
string
Example: acme-shop-123-order123abc

orderId

header Parameters
Authorization
string
Example: ae0cb90d91b4a84a

The token provided by the merchant in the initiate payment request as authToken (an optional parameter). Vipps uses this token when making calls to the merchant's servers. Used so that the merchant may authenticate the request from Vipps.

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

The body of the request made by Vipps. It will differ if the request is a regular or express payment.

One of
merchantSerialNumber
required
string [ 5 .. 6 ] characters ^\d{5,}$

Unique id for this merchant's sales channel: website, mobile app etc. Short name: MSN. Early MSNs were five digits, new ones are six digits.

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

An id that uniquely identifies a payment. Please see the orderId recommendations in the API guide. Maximum length is 50 alphanumeric characters: a-z, A-Z, 0-9 and '-'.

required
object (ShippingDetailsRequest)
required
object (CallbackTransactionInfoExpress)
required
object (UserDetails)

Only used for Vipps Hurtigkasse (express payment) and when using Userinfo.

object (Error)

An error from Vipps. The most important property is the HTTP status code. The response body contains more details of the error.

Responses

Request samples

Content type
application/json;charset=UTF-8
Example
{
  • "merchantSerialNumber": "123456",
  • "orderId": "acme-shop-123-order123abc",
  • "shippingDetails": {
    },
  • "transactionInfo": {
    },
  • "userDetails": {
    },
  • "errorInfo": {
    }
}

Vipps Userinfo API

Get Userinfo

This endpoint returns the payload with the information that the user has consented to share. Find more info on the /userinfo endpoint at the OIDC Standard https://openid.net/specs/openid-connect-core-1_0.html#UserInfo

path Parameters
sub
required
string

The sub is specified when fetching payment details

header Parameters
Authorization
required
string
Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...

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
string
Example: 123456

The Merchant Serial Number (MSN) is a unique id for the sale unit that this payment is made for. This is a required parameter if you are a Vipps eCom partner making payments on behalf of a merchant. The partner must use the merchant's MSN (not the partner's MSN). This parameter is optional, and recommended, for regular Vipps merchants making payments for themselves.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "accounts": [
    ],
  • "address": [
    ],
  • "other_addresses": [
    ],
  • "birthdate": "2000-12-31",
  • "email": "string",
  • "email_verified": true,
  • "family_name": "string",
  • "given_name": "string",
  • "name": "string",
  • "nin": "09057517287",
  • "phone_number": "47912345678",
  • "sid": "7d78a726-af92-499e-b857-de263ef9a969",
  • "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944"
}