Skip to main content
API docs by Redocly

eCommerce API (2.0.3)

Download OpenAPI specification:Download

The eCom API allows you to initiate payments, get payment details, capture payments, and refund payments. See the API Guide for more details.

eCom API

Functionality provided by the 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.

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

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Vipps Recurring 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 <= 30 characters
Example: WooCommerce

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

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

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string <= 30 characters
Example: woocommerce-payment

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

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

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

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

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.

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

The subscription key for your sales unit. See API keys. 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.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Vipps Recurring 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 <= 30 characters
Example: WooCommerce

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

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

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string <= 30 characters
Example: woocommerce-payment

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

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

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

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

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
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 sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Vipps Recurring 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 <= 30 characters
Example: WooCommerce

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

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

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string <= 30 characters
Example: woocommerce-payment

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

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

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

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

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.

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

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Vipps Recurring 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 <= 30 characters
Example: WooCommerce

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

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

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string <= 30 characters
Example: woocommerce-payment

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

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

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

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.

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

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 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.

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

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Vipps Recurring 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 <= 30 characters
Example: WooCommerce

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

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

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string <= 30 characters
Example: woocommerce-payment

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

Vipps-System-Plugin-Version
string <= 30 characters
Example: 1.2.1

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

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.

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

ForceApproveRequest

customerPhoneNumber
string^\d{8}$

The customer's phone number, if available. Format: 8 digits.

Please note: The phone number is optional and should only be sent if it is already known. Users should never be asked for the phone number, as they will either be automatically app-switched to the Vipps app, or they will be presented with the landing page. The exception for this is "manual POS" integration, where the cashier asks the customer for the number, and then enters it manually on the POS.

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": "string",
  • "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.

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

The subscription key for your sales unit. See API keys. Keep it secret.

Content-Type
string
Example: application/json

The content type must be application/json

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Vipps Recurring 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 <= 30 characters
Example: WooCommerce

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

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

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string <= 30 characters
Example: woocommerce-payment

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

Vipps-System-Plugin-Version
string <= 30 characters
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 sales unit. See API keys. Keep it secret.

Merchant-Serial-Number
string
Example: 123456

The Merchant Serial Number (MSN) is a unique ID for the sales unit for which this payment is made. This is a required parameter if you are a Vipps Recurring 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 <= 30 characters
Example: WooCommerce

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

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

The version number of the ecommerce solution.

Vipps-System-Plugin-Name
string <= 30 characters
Example: woocommerce-payment

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

Vipps-System-Plugin-Version
string <= 30 characters
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",
  • "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 allows Vipps to 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. Request syntax: 'DELETE:{consentRemovalPrefix}/v2/consents/{userId}'. Vipps will add /v2/consents/{userId} to the end of the consentRemovalPrefix URL. URLs passed to Vipps must validate, see the API guide. We do not send requests to all ports, so 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 allows Vipps to get the shipping cost and method, based on the provided address and product details. The primary use of this service is to support Vipps Hurtigkasse (express checkout), where Vipps must present the shipping cost and method to the user. There is 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. Request syntax: 'POST:{shippingDetailsPrefix}/v2/payments/{orderId}/shippingDetails'. Vipps will add /v2/payments/{orderId}/shippingDetails to the end of the shippingDetailsPrefix URL. URLs passed to Vipps must be validated, see the API guide. We do not send requests to all ports, so 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
required

ShippingCostAndMethod

addressId
required
integer >= 100

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 allows Vipps to send the transaction details. For regular eCom payments, the order and transaction details will be shared. For Vipps Hurtigkasse (express checkout) payments, it will provide user and shipping details, in addition to the order and transaction details. Request syntax: 'POST:{callbackPrefix}/v2/payments/{orderId}'. Vipps will add /v2/payments/{orderId} to the end of the callbackPrefix URL. URLs passed to Vipps must be validated, see the API guide. We do not send requests to all ports, so 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
required
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
required

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 (schemas-ShippingDetailsRequest)
required
object (schemas-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": {
    }
}