Express
The Express feature is currently under development and is expected to launch in Q2 2024. 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.
The customer journey
The Express flow is as follows:
- 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.
- In their Vipps or MobilePay app, they will provide consent for sharing their name, address, phone number, and email address with the merchant.
- They then choose one of the displayed shipping options.
- On the last page, confirm the final payment. The amount shown will include the shipping.
- 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
As part of the express flow, you will get access to the user's personal information. Ensure that you comply with our privacy terms.
Create a payment with express options
This feature is under development.
Express is initiated in the create payment request under 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.fixedOptionsproperty. -
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.dynamicCallbackUrlproperty. Then, we can send you their address once we have their consent, and you can send us the array with relevant shipping alternatives.tipIf 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 by the merchant and specified in the shipping.fixedOptions property of the
Create payment request.
The fixedOptions property contains an array of several shipping groups.
Each shipping group contains all the parameters needed for a shipping method.
For example:
Properties of a shipping group
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. Here are the options: [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 incurrencyandvalue(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').
Here is an example HTTP POST for the create payment request:
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": "DKK",
"value": 49900
},
"paymentMethod": {
"type": "WALLET"
},
"customer": {
"phoneNumber": "4512345678"
},
"shipping": {
"fixedOptions": [
{
"isDefault": true,
"priority": 0,
"type": "PICKUP_POINT",
"brand": "BRING",
"options": [
{
"id": "bring_pickup_1",
"isDefault": true,
"amount": {
"currency": "DKK",
"value": 3900
},
"priority": 0,
"name": "Gellerup Shoppen",
"meta": "Gudrunsvej 78, 8220 Braband",
"estimatedDelivery": "In 2 days"
},
{
"id": "bring_pickup_2",
"isDefault": false,
"amount": {
"currency": "DKK",
"value": 3900
},
"name": "Pakkeboks Bazar Vest",
"priority": 1,
"meta": "Edwin Rahrs Vej 32, 8220 Braband",
"estimatedDelivery": "In 2 days"
}
]
},
{
"isDefault": false,
"priority": 0,
"type": "HOME_DELIVERY",
"brand": "POSTNORD",
"options": [
{
"id": "postnord_home_1",
"isDefault": true,
"amount": {
"currency": "DKK",
"value": 4900
},
"name": "Home delivery",
"priority": 1,
"meta": "",
"estimatedDelivery": "2-5 days"
}
]
}
]
},
"reference": "acme-shop-123-order123abc",
"receiptUrl":"https://example.com/link/to/my.pdf",
"returnUrl": "https://yourwebsite.com/redirect?reference=acme-shop-123-order123abc",
"userFlow": "WEB_REDIRECT",
"paymentDescription": "One pair of socks"
}'
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": [
{
"isDefault": false,
"priority": 0,
"type": "HOME_DELIVERY",
"brand": "PORTERBUDDY",
"options": [
{
"id": "porterbuddy_4417",
"isDefault": true,
"amount": {
"currency": "NOK",
"value": 3900
},
"name": "Tuesday 04.04.2025",
"priority": 0,
"meta": "",
"estimatedDelivery": "17:00 – 19:00"
},
{
"id": "porterbuddy_5410",
"isDefault": false,
"amount": {
"currency": "NOK",
"value": 1900
},
"name": "Wednesday 05.04.2025",
"priority": 1,
"meta": "",
"estimatedDelivery": "10:00 – 12:00"
}
]
}
]
},
This makes it easy for users to see all available options and pick what works best for them.
Full code example
Here's a sample shipping property to create these options.
Add this to your POST:/epayment/v1/payments request.
"shipping": {
"fixedOptions": [
{
"isDefault": false,
"priority": 0,
"type": "HOME_DELIVERY",
"brand": "PORTERBUDDY",
"options": [
{
"id": "porterbuddy_4417",
"isDefault": true,
"amount": {
"currency": "NOK",
"value": 3900
},
"name": "Tuesday 04.04.2025",
"priority": 0,
"meta": "",
"estimatedDelivery": "17:00 – 19:00"
},
{
"id": "porterbuddy_5410",
"isDefault": false,
"amount": {
"currency": "NOK",
"value": 1900
},
"name": "Wednesday 05.04.2025",
"priority": 1,
"meta": "",
"estimatedDelivery": "10:00 – 12:00"
},
{
"id": "porterbuddy_5412",
"isDefault": false,
"amount": {
"currency": "NOK",
"value": 1900
},
"name": "Wednesday 05.04.2025",
"priority": 2,
"meta": "",
"estimatedDelivery": "12:00 – 14:00"
},
{
"id": "porterbuddy_5414",
"isDefault": false,
"amount": {
"currency": "NOK",
"value": 1900
},
"name": "Wednesday 05.04.2025",
"priority": 3,
"meta": "",
"estimatedDelivery": "14:00 – 17:00"
},
{
"id": "porterbuddy_5417",
"isDefault": false,
"amount": {
"currency": "NOK",
"value": 2900
},
"name": "Wednesday 05.04.2025",
"priority": 4,
"meta": "",
"estimatedDelivery": "17:00 – 19:00"
}
]
}
]
},
"amount": {
"currency": "DKK",
"value": 49900
},
"paymentMethod": {
"type": "WALLET"
},
"customer": {
"phoneNumber": "4512345678"
},
"reference": "acme-shop-123-order12345abc",
"returnUrl": "https://yourwebsite.com/redirect?reference=acme-shop-123-order12345abc",
"userFlow": "WEB_REDIRECT",
"paymentDescription": "One pair of socks"
Dynamic options
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 for the fixed options.
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"
}
]
}
],
}
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.
Ensure that you comply with our privacy terms.