Express

Still in progress 🚩

The Express feature is currently under development and is expected to launch in Q2 2025. Please note that the specifications and logic are subject to change as we finalize the implementation.

With the new Express feature, you can provide users with different shipping options, which they can then choose from within the Vipps or MobilePay app.

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.

The customer journey

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.

Here is an example of the screens:

Vipps

MobilePay

Place an Express button on your checkout screen or your product screens.

For more illustrations, see: How Express works.

Create a payment with express options

Express is initiated in the create payment request setting paymentMethod="WALLET" and supplying the shipping property.

You have two options:

• Fixed options - If you know the shipping alternatives at the time you send the request, specify them all in the shipping.fixedOptions property.

• Dynamic options - If you don't know the shipping alternatives because you don't know their address yet, specify a callback server URL in the shipping.dynamicCallbackUrl property. Then, we can send you their address once we have their consent, and you can send us the array with relevant shipping alternatives.

  tip

  If the shipping methods and cost can be known in advance, it's better to provide these when you create the payment to avoid the extra round-trip between our backend and your server. This will speed up the user experience and reduce the risk of drop-offs and errors.

Fixed options

Fixed shipping methods are predefined and specified by the merchant in the shipping.fixedOptions property of the Create payment request.

The fixedOptions property contains an array of several shipping groups. For example:

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. We'll add the logo based on the vendor in the apps. Here are the options: 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').

An example of a shipping group with only one option:

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

Here is a 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": "DKK",
                            "value": 4900
                        },
                        "name": "Delivery to your door"
                    }
                ]
            }
        ]
    },
    "paymentMethod": {
        "type": "WALLET"
    },
    "amount": {
        "currency": "DKK",
        "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"
}'

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.

For example, 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": "DKK",
                            "value": 3900
                        },
                        "priority": 0,
                        "name": "Gellerup Shoppen",
                    },
                    {
                        "id": "bring_pickup_2",
                        "amount": {
                            "currency": "DKK",
                            "value": 3900
                        },
                        "name": "Pakkeboks Bazar Vest",
                        "priority": 1,
                    }
                ]
            }
        ]
    }

Use the options for small differences in either the pickup location or the delivery time.

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.

Here is an example with two shipping groups:

    "shipping": {
        "fixedOptions": [
            {
                "brand": "BRING",
                "type": "PICKUP_POINT",
                "options": [
                    {
                        "id": "bring_pickup_1",
                        "isDefault": true,
                        "amount": {
                            "currency": "DKK",
                            "value": 3900
                        },
                        "priority": 0,
                        "name": "Gellerup Shoppen",
                    },
                    {
                        "id": "bring_pickup_2",
                        "amount": {
                            "currency": "DKK",
                            "value": 3900
                        },
                        "name": "Pakkeboks Bazar Vest",
                        "priority": 1,
                    }
                ]
            },
            {
                "brand": "BRING",
                "type": "HOME_DELIVERY",
                "options": [
                    {
                        "id": "bring_home_1",
                        "amount": {
                            "currency": "DKK",
                            "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 the shipping methods and cost can be known in advance, it's better to provide these when you create the payment to avoid the extra round-trip between our backend and your server. This will speed up the user experience and reduce the risk of drop-offs and errors.

Dynamic shipping options allow you to fetch live delivery methods and present these to the user.

We send the user's address to your callback endpoint, and you respond with groups of shipping options. These will be displayed when the user reaches the shipping screen in the Vipps or MobilePay app.

This option is specified in the shipping.dynamicOptions property of the create payment request.

To use dynamic options, specify the following:

callbackUrl: URL to the callback server. callbackAuthorizationToken: Authorization token for secure callbacks.

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

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

Callback request

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

Field	Required	Type	Description
reference	Yes	string	The unique identifier for the payment, specified when initiating the payment. Must be 8-64 characters matching the regex ^[a-zA-Z0-9-]{8,64}$. The reference must be unique for the sales unit (MSN), but not globally unique. See the recommendations.
AddressLine1	Yes	string	First address line.
AddressLine2	No	string or null	Second address line.
City	Yes	string	City name.
PostCode	Yes	string	Postcode of the address in local country format.
Country	Yes	string	Name of the country.

For example:

{
"Reference": "string",
"AddressLine1": "Robert Levins gate 5",
"AddressLine2": "Apt 4",
"City": "Oslo",
"PostCode": "0154",
"Country": "Norway"
}

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

The UserDetails object holds the recipient's email, firstName, lastName, and mobileNumber. This is available for Express payments only.

User consent

As part of the express flow, you will get access to the user's personal information. 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.

Privacy terms

Ensure that you comply with our privacy terms.

Related pages

• How it works guide for Express