Skip to main content

API guide

info

Freestanding card payments (outside the Vipps and MobilePay apps) are only available in Norway at the moment. It will be available in the other markets later.

The Checkout API provides an all-in-one solution for receiving payment for goods and services online using our trusted technology and brand. It combines several Vipps MobilePay products, including Login, ePayment, Recurring and Order management allowing a frictionless integration for merchants.

API version: 3.0.0.

Please note: The test environment is currently limited to Norway, and will soon work in other markets. Read more about the test environment and its limitations.

Please note: Always use the most recent API version when integrating with Checkout. All endpoints are described in detail in our API Reference.

Migrating to V3? Consult our Migration Guide.

Checkout Features​

Explains the high level features of Checkout.

Checkout API​

Checkout works around the concept of a session, with a time to live of one hour. The API exposes endpoints for the merchant to interact with a session. These include:

  • session initiation
  • session status

Session types​

A Checkout session support both one-time-payments and subscriptions by setting the type property to PAYMENT or SUBSCRIPTION respectively at session initiation.

Checkout frontend​

Once a session is created, it is to be opened inside an iFrame embedded on the merchant website. The iFrame loads a web application that fetches all necessary information about the session from Vipps MobilePay.

Frontend SDK​

We provide a frontend SDK to make opening the session on the merchant easy (the SDK is explained in detail later in this guide).

It is strongly recommended to use the frontend SDK to make sure you get the latest improvements and bug fixes.

Shipping​

In most situations a merchant wants to send goods to a customer using a shipping provider. Consult the shipping guide and the API spec for a detailed description of which shipping providers and features Checkout support.

Checkout Direct - Hosted checkout​

With Checkout Direct you can easily implement an express checkout experience directly from a product page without going through a shopping cart. Checkout Direct decouples you from needing to embed an iFrame and lets us handle everything at checkout.vipps.no before returning the customer to your shop after a payment is finished. To use Checkout Direct , follow the System integration guidelines and make sure you pick Option 2 under Step 2: Displaying the session to the user.

Checkout Elements​

With Checkout Elements, you can adjust the fields and values present in the Checkout. For example, you might have a purchasing flow where you do not require an address because you are not sending physical goods, or you do not need the customers to identify themselves because they are already logged into your system.

The Elements mode is optionally set by the configuration.Elements property at session initiation, and defaults to Full.

If you do not need the address from a user you can disable it using Elements set to PaymentAndContactInfo, resulting in the following personal details form.

Address_field_false_form

And the following payment form:

Address_field_false_form

Remembering of customer data​

Checkout supports easy fetching of user info with the built-in Login integration. With a functionality called "Remember Me", the user is can opt in to having this information being persisted across different Checkout sessions on the same machine.

Prefill customer data​

We believe that simplicity is key to providing the best user experience. With prefillCustomer, you can easily send in any information you have about your customer, making filling out forms in the Checkout a breeze. All fields in prefillCustomer are optional. We will prefill the form with whatever information you send and let your customers fill in the rest if any information is missing.

To further streamline the payment process, we've implemented a feature that automatically forwards the phone number to our landing page. This removes the hassle of having to fill in the phone number multiple times and makes it even easier for your customers to pay.

Even if your Checkout is set up with PaymentOnly, you can still send in your customer's phone number to make the payment process smoother.

Sometimes you need to ask your customers for permission for certain actions, such as subscribing to technical updates. That's where our "custom consent" feature comes in handy!

When you enable "custom consent", a checkbox with a message appears at the bottom of the checkout page. Your customers can choose to check this box if they want to give their consent. You can make the checkbox optional or required, depending on your needs.

The message displayed next to the checkbox can contain up to one link, formatted in Markdown like this: [linkText](https://example.com). This allows you to direct customers to additional information or resources related to the consent request.

Custom consent

Receipts​

Checkout supports creating receipts that become visible to the user in the App. This can be useful in many cases, and is sometimes mandatory as described below.

To enable Checkout to create receipts, the orderSummary property in the session initiation request must be set. Detailed information is available in the OpenAPI spec session initiation endpoint

Receipt information is a combination of a list of OrderLines and a BottomLine. An OrderLine is a description of each item present in the order. The BottomLine contains information regarding the order as a whole. It is possible to specify shipping costs in one or more OrderLines in the session initiation. If shipping is handled in Checkout and is not free, an order line with the shipping cost will be automatically added, even if shipping costs are specified in the session initiation.

If set up properly in the OrderSummary property in the session initiation, the receipt will be created when payment is initiated (by sending it to Order Management API), and will be visible in the customer's app when the payment is successfully completed. Further details regarding receipts in The Order Management API

Show order summary​

In addition to automatically creating receipts, setting up the OrderSummary property as described above enables the use of showOrderSummary: true inside configuration in the session initiation. This will display a simplified order summary, similar to the receipt, on top of the Checkout window. Use this feature if you would like to show what the user is paying for during the checkout. We show a simpler summary than the receipt using a subset of the properties inside OrderSummary. For example, tax calculations are shown in the receipt, but not in the order summary. The following properties are honored: id, name, discount, giftcard, totalAmount, productUrl, isReturn, isShipping, currency, giftCardAmount, quantity.

Show order summary

Receipts and Content monitoring​

We offer Content monitoring as a way for Merchants to deal with the regulatory demands of content monitoring. For some merchants, we can utilize the merchant's webpage for content monitoring, continuously verifying that the actual products being sold coincides with the expected products. If you, as a merchant, do not have a permanent website that can be utilized for content monitoring, for example you do not have a user facing website or the website is ephemeral/short-lived, then you must utilize Content monitoring. In order to comply with Content monitoring, all transactions must be posted to the Order Management receipts functionality described in this section.

System integration guidelines​

Be sure to always use the most updated version of the API when integrating.

See also: Checkout quick start guide.

Flow diagram​

The standard flow for a Checkout consists of

  1. Initiating a session
  2. Displaying the session to the user
  3. Handling the result of the session

Step 1: Initiating a session​

The merchant backend calls the session initiation endpoint:

POST:/checkout/v3/session

Provide headers described in HTTP Headers.

All fields of the request body are described in our API Reference.

The response object consists of a token and a checkoutFrontendUrl, which are used in the next step

Configuration for use inside a native mobile application​

Checkout can be used in an iOS or Android app to pay for goods and services. The Checkout frontend may then be opened directly inside a web view, instead of as an iFrame inside a merchant website.

In this situation, the merchant may wish to have a returnUrl to direct the user back to an application using a custom URL scheme (e.g. myapp://) instead of HTTPS. The frontend application will automatically try to detect if the user is on a mobile device, if so doing an "app switch" into the Vipps or MobilePay app, and then back to your application upon completion. Because of variations in devices and browser implementations there are certain edge cases where the device type is wrongly detected. Initiate the session with userFlow set to NATIVE_REDIRECT to ensure that the app switching is done consistently after payment.

Step 2: Displaying the session​

Load the frontend SDK in the <head> section of the merchant website.

<head>
  <script src="https://checkout.vipps.no/vippsCheckoutSDK.js"></script>
</head>

The most common flow includes embedding Checkout on the merchant web site, typically as the step succeeding a shopping cart view.

Option 1: iFrame and Option 2: Checkout Direct can also work in combination on your site.

The frontend SDK exposes a global function called VippsCheckout. Initialize this with the following parameters:

ParameterDescriptionOptional
checkoutFrontendUrlSpecifies where to load the iFrame content from. Comes from session creation responseNo
iFrameContainerIdThe ID of the HTML element to contain the Checkout iFrameNo
tokenToken identifying the session. Comes from session creation response.No
languageCan be set to 'nb', 'dk', 'fi' or 'en'. This is optional and will default to 'en' English if not specifiedYes
onListen to events from Checkout. See SDK events for more details.Yes

Example merchant website using Checkout frontend SDK to embed an iFrame with the session in plain html/js.

<html>
  <head>
    <title>Merchant website</title>
    <script src="https://checkout.vipps.no/vippsCheckoutSDK.js"></script>
  </head>
  <body>
    <button type="button" id="checkout-button">Checkout with Vipps</button>
    <section id="vipps-checkout-frame-container">
      <!-- This is where the iFrame will be embedded -->
    </section>
    <script>
      document
        .getElementById("checkout-button")
        .addEventListener("click", function () {
          // Relay an initiate session request to Checkout API through the merchant's backend
          fetch("<MERCHANT BACKEND CREATE SESSION URL>", {
            method: "POST",
          })
            .then((response) => response.json())
            .then((data) => {
              var vippsCheckout = VippsCheckout({
                checkoutFrontendUrl: data.checkoutFrontendUrl,
                iFrameContainerId: "vipps-checkout-frame-container",
                language: "nb",
                token: data.token,
              });
            })
            .catch((error) => {
              // Handle at least these two types of errors here:
              // 1. Fetch to create session endpoint failed
              // 2. Checkout frontend SDK not loaded resulting in VippsCheckout not being defined
            });
        });
    </script>
  </body>
</html>

Please note: Never leak the merchant credentials to the frontend. A Checkout session should always be created by the merchant backend

Please note: The Checkout frontend is not supposed to be open in its own browser window/tab. The only exception to this is when using Checkout inside a web view in a native mobile application.

Sticky Checkout session​

The frontend SDK provides an alternative way to display the session, using a query parameter in the URL. This makes the session "sticky", meaning that the same session will open after a page refresh.

If the query parameter token is present and the token attribute in the argument object to VippsCheckout is not defined, the frontend SDK will load the iFrame with the token from the query parameter.

The SDK provides a helper method that will redirect the user to the current page with the token query parameter added to the URL.

Please note: Make sure to initialize VippsCheckout outside any user dependent execution blocks (like event handlers) to make sure that the iFrame is loaded every time a user lands on the page.

// Globally defined
var vippsCheckout = VippsCheckout({
  checkoutFrontendUrl: data.checkoutFrontendUrl,
  iFrameContainerId: 'checkout-iframe-container',
});

// Attach to checkout button
fetch("<MERCHANT BACKEND CREATE SESSION URL>", { method: "POST" })
  .then((response) => response.json())
  .then((data) => {
    vippsCheckout.redirectToCurrentPageWithToken(data.token)
  })

Frontend SDK events​

You can listen to changes in Checkout by supplying callbacks to the on option in the frontend SDK. Each key in the map supplied to on corresponds to an event and accepts a call callback-function with a data parameter as a value.

Available events:

ParameterDescriptionType
shipping_option_selectedIs triggered when the user selects a shipping option or undefined when shipping option is deselected.ShippingOption | undefined
total_amount_changedIs triggered when the total amount changes (for example, when a shipping option is selected).Money
session_status_changedIs triggered upon changes in session status (for example, when payment is started).SessionStarted | PaymentInitiated | PaymentSuccessful | PaymentFailed | SessionTerminated | SessionExpired
shipping_address_changedIs triggered when a new "delivered to" address is submitted or undefined when removed.Address | undefined
customer_information_changedIs triggered when new customer information is submitted or undefined when removed.Address | undefined
Type definition​
ShippingOption​
ParameterTypeDescription
idstringThe merchants shipping option identification.
brandstringThe name of the brand of the option (for example, "Posten" or "PostNord").
descriptiondescription | undefinedThe description of the shipping option.
productstringThe brand specific product (for example, "Servicepakke" or "Home delivery").
priceMoneyThe price of the shipping option.
Example​
window.VippsCheckout = {
  checkoutFrontendUrl: data.checkoutFrontendUrl,
  iFrameContainerId: "vipps-checkout-frame-container",
  language: "nb",
  token: data.token,
  on: {
    shipping_option_selected: function (data) {
      // Do something when the shipping option is selected
    },
    total_amount_changed: function (data) {
      // Do something when the total amount changed
    },
    session_status_changed: function (data) {
      // Do something when status changed
    },
    shipping_address_changed: function (data) {
      // Do something when shipping address changed
    },
    customer_information_changed: function (data) {
      // Do something when customer information changed
    },
  },
};

Step 3: Handling the result of the session​

After the user has completed the checkout process, the merchant will be notified with transaction details through callback and polling, as described below.

Please note: It is highly recommended implementing polling in addition to callback. We do not guarantee delivery of the callback.

Callback Handling​

The callback will be sent to a callback endpoint (click on the "Callbacks" tab) implemented by the merchant.

POST:{merchantInfo.callbackUrl}

The callbackAuthorizationToken, provided by the merchant at session initiation, will be attached as the Authorization header. Use this to authorize the caller.

Every callback must be answered with a HTTP 2XX response. In the eventuality that any other response is sent, we will retry with an exponential backoff until 2XX is received again. The callback will be retried a maximum of 3 times. Please keep in mind that we do not guarantee delivery of the callback, so it is highly recommended implementing polling in addition to callback.

It is critical that the endpoint receiving the callback is robust. It should also be able to receive any additional data not specified in the minimum example, so that it can be backwards compatible in accordance with our integration guidelines.

Session polling​

Checkout exposes a polling endpoint.

The complete URL for polling is returned from the session creation endpoint as pollingUrl.

Payment state​

The sessionState property of the callback/polling response gives information about the state of the payment. Values PaymentSuccessful, PaymentTerminated and SessionExpired are terminal states. Stop polling when receiving one of these states. The callback will only be sent once the session is in a terminal state.

The paymentDetails property gives additional information about the transaction. The shape of the object differs based on paymentMethod.

Applicable for checkout sessions created with type: "PAYMENT".

Example callback/polling response for payment method Wallet (Vipps/MobilePay):

{
    ...
    sessionState: "PaymentSuccessful",
    paymentMethod: "Wallet",
    paymentDetails: {
        type: "wallet",
        state: "AUTHORISED",
        amount: {
            value: 1234,
            currency: "NOK"
        }
    },
    ...
}

Additional details for Wallet transactions can be retrieved from the underlying get payment endpoint that Checkout uses under the hood.

Step 3a: Transaction/Agreement operations​

Depending on the payment method additional actions must be taken after a successful payment.

For payment methods Wallet/Card the amount will be reserved on the customer account until you capture it to complete the payment. Capture must be done in accordance with the terms and conditions you have with the user. Our recommendation is that this is not performed until the goods or services have been delivered.

See the ePayment API for payment operations for more information on how to perform capture/cancel/refund on a payment. The merchant credentials and the reference are cross compatible between Checkout and ePayment API's

Please note: That the eCom API is deprecated and should not be used, as it lacks full support for card transactions.

Please note: Checkout only supports sales units that are set up with type reserve/capture (as opposed to direct capture). Read more about reserve and capture

For payment method BankTransfer (only in the Finnish market) the payment is instant. The transaction amount is settled immediately from the customer account to the merchant account. No additional actions need to be taken. Refunds must be handled by the merchant manually upon agreement between customer and merchant.

Help us improve our documentation

Did you find what you were looking for?