Express

Still in progress

The Express feature is coming in April! Just a heads-up that the spec and some of the logic might still see changes before the final release.

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.

The following is the planned flow:

1. The user selects to pay with Vipps or MobilePay, and their chosen app opens.
2. Through the app, they provide consent to share their address and personal information.
3. You respond by displaying available shipping options within the app.
4. The user selects the preferred shipping option and approves the payment in the app.

Vipps

MobilePay

Create a payment with express options

Still in progress

This is not yet available and may yet change.

Express is initiated by specifying shipping in the Initiate payment request.

Within the shipping property, specify either dynamic or fixed shipping options.

• Dynamic Options:

  • Merchant integrates their backend with the provided callbackUrl.
  • Use callbackAuthorizationToken for secure communication.
  • Backend responds with dynamically generated shipping options.

• Fixed Options:

  • Define static shipping methods directly in the fixedOptions array.
  • Prioritize options using the priority property.
  • Add rich metadata such as addresses and estimated delivery times to enhance customer experience.

note

If you send both fixed and dynamic options, the dynamic options will be used.

Fixed Options

Fixed shipping methods are predefined by the merchant.

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.

Each item in the fixed option array contains all the parameters needed for a shipping method. For example:

• type: HOME_DELIVERY
• brand: DHL
• options: including express shipping, normal shipping, and alternatives with different delivery times and associated costs

Properties

• isDefault: Boolean indicating whether this method is the default option.
• priority: Integer defining the display order (lower numbers appear higher in the app).
• 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. [POSTEN, BRING, POSTNORD, HELTHJEM, PORTERBUDDY, DHL, INSTABOX, FEDEX, OTHER]
• options: Array of delivery details for each fixed shipping option. 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' or '1-2 Days').

For example:

Extended example

 "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"
        }
      ]
    },
    {
      "isDefault": false,
      "name": "Home delivery",
      "priority": 0,
      "type": "HOME_DELIVERY",
      "brand": "HELTHJEM",
      "options": [
        {
          "id": "home",
          "isDefault": true,
          "amount": {
            "currency": "NOK",
            "value": 4900
          },
          "name": "Home delivery",
          "priority": 1,
          "meta": "",
          "estimatedDelivery": "2-5 days"
        }
      ]
    },
    {
      "isDefault": false,
      "name": "Home delivery",
      "priority": 0,
      "type": "HOME_DELIVERY",
      "brand": "PORTERBUDDY",
      "options": [
        {
          "id": "home",
          "isDefault": true,
          "amount": {
            "currency": "NOK",
            "value": 5900
          },
          "name": "Home delivery",
          "priority": 2,
          "meta": "",
          "estimatedDelivery": "3-5 days"
        }
      ]
    }
  ]
}

Dynamic Options

When you specify dynamicOptions, we fetch the shipping options when the user reaches the shipping screen in the Vipps or MobilePay app.

Dynamic shipping options allow the merchant to fetch live delivery methods and costs based on external conditions or APIs. This is used to support Express, where users are presented with real-time shipping costs and methods.

The callbackUrl you provide will allow us to fetch the shipping cost and method from your server, based on the provided address and product details.

You will then reply to us with an array of shipping costs and methods. The array should match the format for fixed options.

Properties

callbackUrl: URL to fetch shipping options dynamically. callbackAuthorizationToken: Authorization token for secure callbacks.

Example:

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

Notes

• Always use secure tokens for dynamic shipping callbacks.
• Prioritize user-friendly naming conventions for fixed options.
• Ensure priority values are unique for optimal sorting.

User consent

As part of the express flow, you will request access to the user's personal information. They must approve this in order to proceed.

The user can remove the consent later by using settings in their Vipps or MobilePay app.