Express

🥳 Express is now available in production! 🥳

With the Express feature, you can provide users with groups of shipping options, which they can then choose from within the Vipps or MobilePay app. Place the Express button on your checkout screen or your product screens.

Vipps

MobilePay

The customer can select the delivery option from the main screen. When you provide several alternatives for an option, they can click the Change location button and select from the alternatives.

Vipps

MobilePay

The customer can update their address and select between delivery options.

Vipps

MobilePay

The Express flow is as follows:

1. The user selects to pay with Vipps or MobilePay .
   • If they are on a PC, they will go through the Vipps MobilePay landing page, where they enter their phone number and the app opens.
   • If they are on a phone, their app will open, and they will switch to it.
2. In their Vipps or MobilePay app, they will provide consent for sharing their name, address, phone number, and email address with the merchant.
3. They then choose one of the displayed shipping options.
4. On the last page, confirm the final payment. The amount shown will include the shipping.
5. They will be directed back to your website, where you should show a confirmation of the payment.

Create an express payment

Express is initiated with the create payment request with:

• paymentMethod set to WALLET
• scope set to "name address email phoneNumber"
• The shipping property included

All of these scope values must be included for Express payments; they cannot be selectively omitted.

See a detailed example

curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "amount":{
    "currency":"NOK",
    "value":6000
    },
    "customer":{
        "phoneNumber":"4712345678"
    },
    "paymentMethod":{
        "type":"WALLET"
    },
    "profile": {
        "scope": "name address email phoneNumber"
    },
  "shipping": {
    "fixedOptions": [        
        {
            "isDefault": true,
            "priority": 0,
            "type": "PICKUP_POINT",
            "brand": "POSTNORD",
            "options": [
                {
                    "id": "meny_grunerlokka",
                    "isDefault": true,
                    "amount": {
                        "currency": "NOK",
                        "value": 3900
                        },
                    "priority": 0,
                    "name": "Meny Grünerløkka",
                    "meta": "Henrik Ibsens Gate 1, 0000 Oslo",
                    "estimatedDelivery": "In 2 days"
                },      
                {
                    "id": "bunnpris_skoyen",
                    "isDefault": false,
                    "amount": {
                        "currency": "NOK",
                        "value": 3900
                        },
                    "name": "Bunnpris Skøyen",
                    "priority": 1,
                    "meta": "Gatenavn 21, 0001 Oslo",
                    "estimatedDelivery": "In 2 days"
                }
            ]
        }
        ]
    },
  "reference": 2810171754658432260,
  "userFlow": "WEB_REDIRECT",
  "returnUrl": "https://developer.vippsmobilepay.com/docs/example-pages/result-page",
  "paymentDescription": "Purchase of socks"
}'

Shipping options

In the shipping property, you can specify either fixedOptions or dynamicOptions (not both).

🚩 If you know the delivery options in advance, send only fixedOptions .

• Fixed options - Specify all the shipping options.
• Dynamic options - Register a callback to generate dynamic options (optional)

Fixed options

When you know the shipping options in advance, supply these through the shipping.fixedOptions property. We accept only one of these options: fixedOptions or dynamicOptions, so please don't supply dynamicOptions if you already know what the shipping options should be.

The fixedOptions property contains an array of one or more shipping groups.

Here is an example showing one type of shipping (e.g., home delivery with PostNord) and two options (standard or express delivery).

 "shipping": {
        "fixedOptions": [
            {
                "brand": "POSTNORD",
                "type": "HOME_DELIVERY",
                "options": [
                    {
                        "id": "postnord-home-1",
                        "amount": {
                            "currency": "NOK",
                            "value": 19900
                        },
                        "name": "Posten home express",
                        "estimatedDelivery": "1 business day"
                    },
                    {
                        "id": "postnord-home-2",
                        "amount": {
                            "currency": "NOK",
                            "value": 9900
                        },
                        "name": "Posten home standard",
                        "estimatedDelivery": "3-5 business days"
                    }
                ]
            }
        ]
    }

As with other ePayment API requests, the value field is in minor units (e.g., 9900 is 99,- NOK).

Shipping groups

Each shipping group contains all the parameters needed for a shipping method.

The properties for each shipping group are:

• type (required): Enum specifying the delivery type: HOME_DELIVERY, PICKUP_POINT, MAILBOX, IN_STORE, OTHER
• brand (required): Enum representing the shipping provider (e.g., BRING, DHL). We'll add the logo based on the vendor in the apps. Here are the options (see Brand logos): BRING, DHL, FEDEX, GLS, HELTHJEM, INSTABOX, MATKAHUOLTO, PORTERBUDDY, POSTEN, POSTI, POSTNORD, OTHER
• isDefault: Boolean indicating whether this method is the default option. The default value is false. If no default is found, then the first option will be preselected.
• priority: Integer defining the display order (lower numbers appear higher in the app). If no priority is set, we show your options in the order you provide them. If some options have a priority set and others not, we'll show the prioritized options first and show the remaining options in the order you have specified them.
• options (required): This is an array with one or more delivery options for a shipping group. This is used for showing options with small differences, such as pickup locations or delivery times. Each array element contains the following:
  • id (required): Unique identifier for the shipping option. The ID of the selected option will be returned in the API after the payment is completed.
  • amount (required): Cost of the shipping in currency and value (e.g., NOK 3900 = NOK 39.00).
  • name (required): Name of the delivery point or store.
  • isDefault: Boolean indicating whether this is the default selection.
  • priority: Determines the order that options appear in the app, with lower numbers appearing higher.
  • meta: Additional information such as address or opening hours.
  • estimatedDelivery: Expected delivery (e.g., 'Ready in 2 hours', '17:00–19:00', '1-2 Days').

For more details, see the Create payment spec.

How the fields map to the app

Shipping group with one option

An example of a shipping group with only one option:

 "shipping": {
        "fixedOptions": [
            {
                "brand": "POSTNORD",
                "type": "HOME_DELIVERY",
                "options": [
                    {
                        "id": "postnord_home_1",
                        "amount": {
                            "currency": "NOK",
                            "value": 4900
                        },
                        "name": "Delivery to your door"
                    }
                ]
            }
        ]
    }

Full HTTP POST example

curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
     "shipping": {
        "fixedOptions": [
            {
                "brand": "POSTNORD",
                "type": "HOME_DELIVERY",
                "options": [
                    {
                        "id": "postnord_home_1",
                        "amount": {
                            "currency": "NOK",
                            "value": 4900
                        },
                        "name": "Delivery to your door"
                    }
                ]
            }
        ]
    },
    "paymentMethod": {
        "type": "WALLET"
    },
    "profile": {
        "scope": "name address email phoneNumber"
    },
    "amount": {
        "currency": "NOK",
        "value": 49900
    },
    "customer": {
        "phoneNumber": "4512345678"
    },
    "reference": "acme-shop-123-order123abc",
    "returnUrl": "https://developer.vippsmobilepay.com/docs/example-pages/result-page",
    "userFlow": "WEB_REDIRECT",
    "paymentDescription": "Descriptive message"
}'

Shipping group with multiple options

If you have more than one shipping option with the same brand and type (e.g., Postnord pickup points, PorterBuddy delivery times), add these to options. You can specify the priority property, where lower numbers appear higher in the app, otherwise we will display them in the order you send them. To set a default, use isDefault.

An example of a shipping group with two options (i.e., pickup points):

"shipping": {
        "fixedOptions": [
            {
                "brand": "BRING",
                "type": "PICKUP_POINT",
                "options": [
                    {
                        "id": "bring_pickup_1",
                        "isDefault": true,
                        "amount": {
                            "currency": "NOK",
                            "value": 3900
                        },
                        "priority": 0,
                        "name": "Gellerup Shoppen",
                    },
                    {
                        "id": "bring_pickup_2",
                        "amount": {
                            "currency": "NOK",
                            "value": 3900
                        },
                        "name": "Pakkeboks Bazar Vest",
                        "priority": 1,
                    }
                ]
            }
        ]
    }

Multiple shipping groups

Create a new shipping group for each unique brand and delivery type. For example, if you offer POSTNORD for HOME_DELIVERY and PICKUP_POINT, provide two shipping groups.

An example with two shipping groups (i.e., same brand, different type of shipping):

    "shipping": {
        "fixedOptions": [
            {
                "brand": "BRING",
                "type": "PICKUP_POINT",
                "options": [
                    {
                        "id": "bring_pickup_1",
                        "isDefault": true,
                        "amount": {
                            "currency": "NOK",
                            "value": 3900
                        },
                        "priority": 0,
                        "name": "Gellerup Shoppen",
                    },
                    {
                        "id": "bring_pickup_2",
                        "amount": {
                            "currency": "NOK",
                            "value": 3900
                        },
                        "name": "Pakkeboks Bazar Vest",
                        "priority": 1,
                    }
                ]
            },
            {
                "brand": "BRING",
                "type": "HOME_DELIVERY",
                "options": [
                    {
                        "id": "bring_home_1",
                        "amount": {
                            "currency": "NOK",
                            "value": 2900
                        },
                        "name": "Delivery to your door",
                    }
                ]
            }
        ]
    },

Shipping groups containing time slots

Some companies, such as Porterbuddy, offer dates with time slots.

Here's a clear way to present delivery options when companies like Porterbuddy provide both dates and time slots:

• name: The shipment date (e.g., "Tuesday 04.04.2025")
• estimatedDelivery: The delivery time slot for that date (e.g., "17:00 – 19:00")
• priority: Start from 0 for the earliest time slot, then count up (0 is the first slot, 1 is next, etc.)

For example, add the following to your POST:/epayment/v1/payments request:

 "shipping": {
        "fixedOptions": [
            {
                "brand": "PORTERBUDDY",
                "type": "HOME_DELIVERY",
                "options": [
                    {
                        "id": "porterbuddy_4417",
                        "amount": {
                            "currency": "NOK",
                            "value": 3900
                        },
                        "name": "Tuesday 04.04.2025",
                        "estimatedDelivery": "17:00 – 19:00"
                    },
                    {
                        "id": "porterbuddy_5410",
                        "amount": {
                            "currency": "NOK",
                            "value": 1900
                        },
                        "name": "Wednesday 05.04.2025",
                        "estimatedDelivery": "10:00 – 12:00"
                    }
                ]
            }
        ]
    },

Dynamic options

tip

If you already know the available shipping options, you don’t need to send dynamic options.

Instead, use fixedOptions to avoid the extra communication between our backend and your server. This makes the checkout faster and reduces the risk of drop-offs or errors.

Only use dynamic options when you don’t know the user’s address and need us to send it to you, so that you can respond with the relevant delivery options. If you already have the address or fixed delivery destinations (for example, in-store pickup), use fixed options.

Dynamic shipping options let you provide live delivery methods based on the user’s address.

We send the user’s address to your callback endpoint, and you return one or more groups of shipping options. These are then shown to the user on the shipping screen in the Vipps or MobilePay app.

Enable dynamic shipping by setting shipping.dynamicOptions in the
create payment request.

To use dynamic options, include:

• callbackUrl – URL to your callback endpoint.
• callbackAuthorizationToken – Token used to securely authorize callbacks from our servers.

For example, add the following to the POST:/epayment/v1/payments request.

"shipping": {
  "dynamicOptions": {
    "callbackUrl": "https://example.com/shipping",
    "callbackAuthorizationToken": "Bearer eyJhbGciOi..."
  }
}

For more details, see the Create payment spec.

Callback request

We will provide the address to you as a JSON object with the following properties:

• reference (required): The unique identifier for the payment, specified when initiating the payment.
• AddressLine1 (required): First address line.
• AddressLine2 Second address line.
• City (required): City name.
• PostCode (required): Postcode of the address in local country format.
• Country (required): The country of the address in ISO 3166-1 alpha-2 format.

For example:

{
"Reference": "stracme-shop-123-order123abcing",
"AddressLine1": "Robert Levins gate 5",
"AddressLine2": "Apt 4",
"City": "Oslo",
"PostCode": "0154",
"Country": "NO"
}

For more details, see the callback section of the Create payment spec.

Callback response

Your server should respond with the addresses in this JSON format:

{ "groups": [ {shipping options 1}, {shipping options 2}, etc. ] }

The groupsproperty contains an array with one or more shipping groups. Each shipping group contains the properties as described in the Shipping groups.

For example:

{
  "groups": [
    {
      "isDefault": true,
      "priority": 0,
      "type": "PICKUP_POINT",
      "brand": "POSTNORD",
      "options": [
        {
          "id": "meny_grunerlokka",
          "isDefault": true,
          "amount": {
            "currency": "NOK",
            "value": 3900
          },
          "priority": 0,
          "name": "Meny Grünerløkka",
          "meta": "Henrik Ibsens Gate 1, 0000 Oslo",
          "estimatedDelivery": "In 2 days"
        },      
        {
          "id": "bunnpris_skoyen",
          "isDefault": false,
          "amount": {
              "currency": "NOK",
              "value": 3900
              },
          "name": "Bunnpris Skøyen",
          "priority": 1,
          "meta": "Gatenavn 21, 0001 Oslo",
          "estimatedDelivery": "In 2 days"
        }
      ]
    }
  ],
}

Get payment details with shipping options

When you include shipping details in the create payment request, these will be returned in the Get payment response as well as the ePayment webhook payload.

The ShippingDetails object provides information about the shipment:

• address - An object that holds the recipient's shipping address, including: addressLine1, addressLine2, city, country, postCode.
• shippingCost - The cost of shipping, specified in minor currency units. For example, 9900 (99.00 NOK).
• shippingOptionId - The ID of the selected shipping option.
• shippingOptionName - The name of the selected shipping option.

The UserDetails object holds the recipient's email, firstName, lastName, and mobileNumber.

Note, these are available for Express payments only.

Shipping addresses

When using Fixed options, the user's address must correspond to the currency in use.

With Dynamic options, you have the flexibility to decide whether the address is supported. If shipping to the specified address is not possible, return a 400 in the callback response. The app will then notify the user that delivery to the selected address is unavailable.

Button guidelines

note

We are currently evaluating alternative button text — "Vipps Express" and "MobilePay Express" — to measure potential conversion improvements.

We recommend using the button text "Buy now with Vipps" or "Buy now with MobilePay". For example:

The following are translations into our supported languages:

Vipps

Danish: Køb nu med Vipps
Finnish: Osta nyt Vippsillä
Norwegian: Kjøp nå med Vipps
Swedish: Köp nu med Vipps
English: Buy now with Vipps

MobilePay

Danish:: Køb nu med MobilePay
Finnish: Osta nyt MobilePaylla
Norwegian: Kjøp nå med MobilePay
Swedish: Köp nu med MobilePay
English: Buy now with MobilePay

If you can dynamically generate most of the buttons with JavaScript, see our vipps-checkout-button JavaScript library.

For button resources, see:

• Buttons design guidelines
• Vipps buttons
• MobilePay buttons

User consent

Privacy terms

As part of the express flow, you will get access to the user's personal information. Ensure that you comply with our privacy terms.

They must approve this in order to proceed, but they can remove the consent later through their Vipps or MobilePay app.

We recommend that you don't keep their information any longer than needed for the shipping to be completed.

Brand logos

Here are the brands we currently have in the app.

If you need another logo, let us know in the feedback form below.