Create payment

A merchant system will send a payment request to the user when they select to pay with Vipps/MobilePay.

When an ePayment is created, the customer receives a push notification for approval. If not approved or completed, no further notifications are sent. The payment status remains available in the app for the customer to view.

User flows

For general payment information, see Creating a Vipps/MobilePay payment.

The create payment request

The first step in the payment flow is to create a payment with POST:/epayment/v1/payments.

Example create payment request

This sends a Vipps/MobilePay payment request to the customer.

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"
      },
      "reference":"acme-shop-123-1234589",
      "paymentDescription": "",
      "returnUrl":"https://example.com/redirect?orderId=1512202",
      "userFlow":"WEB_REDIRECT",
   }'

Parameters

Authorization - Bearer-Authorization. The access token is a base64-encoded string that is required for all API calls.
Idempotency-Key - Idempotency key for the request, ensures idempotent actions. See Idempotency
Ocp-Apim-Subscription-Key - The subscription key for a sales unit. See API keys.
Merchant-Serial-Number - The Merchant Serial Number is a unique identifier that is defined when a sales unit is created. See How to find the Merchant Serial Number

There are several additional HTTP headers that are helpful for debugging (e.g., Vipps-System-Name).

Body

Required parameters

amount - Amount object, containing a value and a currency. The currency must match the currency for your sales unit. The minimum amounts allowed are: NOK 100 øre, DKK 1 øre, EUR 1 cent
paymentMethod - Type must be either WALLET or CARD (see paymentMethod).
reference - The reference is the unique identifier for the payment, specified when initiating the payment. The reference must be unique for the sales unit (MSN), but is not globally unique, so several MSNs may use the same reference. See the orderId / reference recommendations.
userFlow - The normal flow is WEB_REDIRECT. QR creates a one-time QR which the user scans to pay with Vipps/MobilePay.
customer - Required for userFlow of PUSH_MESSAGE. The customer phone number or login token.
returnUrl - Required for userFlow of WEB_REDIRECT. The URL the user is returned to after the payment session. The URL must use the https:// scheme or a custom URL scheme.

Optional parameters for special features

The following parameters are used for special features:

receipt - (Set order details) The order details for a payment.
shipping - (Express) Display shipping delivery options and prices in the Vipps/MobilePay app.
profile - (Profile sharing) Request the user's profile information.
expiresAt - (Long-living payments) Extend the payment deadline.
minimumUserAge - (Minimum user age) Limit payments to people over a minimum age.
customerInteraction - (Specify customer present) Should be specified when customers are physically present, specify "customerInteraction": "CUSTOMER_PRESENT".
blockedSources - (Block payment sources) Danish and Finnish sales units can block payment sources when using WALLET as payment method type.
metadata - (Add metadata) Add metadata to the payment.

`paymentMethod`

The POST:/epayment/v1/payments endpoint supports both wallet (i.e., the Vipps or MobilePay app) and freestanding card payments (e.g., VISA, Mastercard), when card details are entered. Each payment type offers separate user flows.

These are specified in paymentMethod.type as:

WALLET - normal flow, payment is through the Vipps/MobilePay app
CARD - payment is through freestanding cards

Example:

 "paymentMethod":{
         "type":"WALLET"
      }

`WALLET`

WALLET is the normal payment method where the user pays through the Vipps or MobilePay app.

This includes delegated Strong Customer Authentication (SCA), where the login to the app eliminates the need for a separate SCA step. WALLET payments include retry functionality such that, if the user attempts to pay with a declined card, they can retry with a different card for the same payment process.

`CARD`

With CARD as the payment method, the user pays with a freestanding card instead of Vipps/MobilePay. They enter the card details into a form and then complete the 3D Secure step-up for SCA.

For more information about card payments, see:

note

Card payment (CARD) is not available in the test environment.

`userFlow`

The userFlow parameter specifies how the API should handle the payment and how the user experience will be.

In the create payment request, specify userFlow as one of the following options (usually "userFlow": "WEB_REDIRECT"):

`userFlow`	Description
`WEB_REDIRECT`	`WEB_REDIRECT` (the normal flow) works for browsers and native apps by handling the app-switching. If the user is on a mobile device with the Vipps or MobilePay app installed, it will open automatically. Otherwise, the landing page will open. A valid value for `returnUrl` is required.
`PUSH_MESSAGE`	`PUSH_MESSAGE` (requires approval) is specified to skip the landing page for payments initiated on a device other than the user's phone. The user gets a push message that opens the payment in the Vipps or MobilePay app. A valid value for `customer` is required.
`QR`	The `QR` flow returns a QR code that is scanned by the user to complete the payment.
`NATIVE_REDIRECT`	`NATIVE_REDIRECT` (not recommended, except in some cases where merchant doesn't have web presence) provides automatic app-switch between the merchant's native app and the Vipps or MobilePay app. We recommend using `WEB_REDIRECT` instead.

`WEB_REDIRECT`

The WEB_REDIRECT flow provides fallback to the landing page in case the Vipps or MobilePay app aren't installed.

This is the recommended flow for webshops and apps. WEB_REDIRECT is more secure than NATIVE_REDIRECT and offers better cross-platform compatibility. Please see Knowledge base: App flow recommendations for more details.

This flow is applicable for both WALLET and Card payment flows. Specify "userFlow": "WEB_REDIRECT" in the create payment request.

For 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": {
    "value": 49900,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": 4712345678
  },
  "reference": 58712432,
  "userFlow": "WEB_REDIRECT",
  "returnUrl": "http://example.com/redirect?reference=58712432",
  "paymentDescription": "descriptive"
}'

The WALLET payment method is the normal flow. In this flow there are two scenarios:

When the user is on a mobile device with the Vipps or MobilePay app installed, we will automatically do an app-switch to the app, eliminating the need to enter the phone number, and avoiding any potential friction. This is the normal flow on mobile devices. The landing page should never be seen on a mobile device with the app installed.
When the user is on a device without the Vipps or MobilePay app installed (a PC/Mac, a tablet, a second phone, etc.), we will open the landing page where the user can enter the phone number (browsers may remember the phone number, simplifying this step).

In the CARD flow, regardless of whether the user is on a desktop or mobile device, the card entry page will open.

Important information for the default WEB_REDIRECT flow

The API response from POST:/epayment/v1/payments contains the redirectUrl (previously called "deeplink URL").

It is crucial that this URL is opened directly, without making any changes to it. Do not redirect to the URL, but open it using the default URL opening functionality on the phone's operating system. Never open the URL in a web view, iframe or similar, as that will break the flow.

On phones, the phone operating system will recognize the URL and automatically do an app-switch to the Vipps MobilePay app using universal linking.

On other devices, the landing page will be shown, so the user can enter the phone number, get a push notification on the phone, and confirm the payment in the Vipps MobilePay app on the phone.

Important:
Do not attempt to detect if the Vipps MobilePay app is installed, as users must be able to initiate a payment flow on any device without the app, and complete it on a device with the Vipps MobilePay app installed. This is handled automatically by us, based on years of continuous improvement, ensuring the best possible success rate.

Please see Knowledge base: App flow recommendations for more details.

`PUSH_MESSAGE`

Special approval required

Sales units must be approved to use this user flow because it skips the Vipps/MobilePay landing page.

To request this feature, please contact your key account manager, your partner manager, or customer service.

Applicable only for WALLET payments initiated on a device other than the user's device (e.g., a Point of Sale).

Specify "userFlow": "PUSH_MESSAGE". A valid customer is required.

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": {
        "value": 15000,
        "currency": "DKK"
    },
    "paymentMethod": {
        "type": "WALLET"
    },
    "customer": {
        "phoneNumber": "4512345678"
    },
    "reference": 21203831704360461822,
    "userFlow": "PUSH_MESSAGE"
}'

This will create a push message on the user's phone where they can approve the payment.

important

Using PUSH_MESSAGE (and skipping the landing page) is only allowed when it is not possible to show the landing page, when the payment is initiated on a device that the user does not own or control. This includes:

Not on the user's phone
Not on the user's computer
On a device that has no user-facing display where the landing page can be shown, such as physical points of sale (POS) solutions, vending machines, etc.

Troubleshooting

"PUSH_MESSAGE flow not allowed"

Sales units (i.e., Merchant Serial Numbers) must be especially approved to use this user flow. The merchant must have received the phone number from the customer with their consent for sending a payment request to the user's phone via Vipps or MobilePay app.

To request this feature, please contact your key account manager, your partner manager, or customer service.

`QR`

Applicable only for WALLET payments.

This user flow is for customer-facing screens where payments can be initiated with the One-time payment QR.

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 '{
  "userFlow": "QR",
  "qrFormat": {
    "format": "IMAGE/SVG+XML",
    "size": 1024
  },
  "amount": {
    "value": 42924,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customerInteraction": "CUSTOMER_PRESENT",
  "reference": 2486791679658155992,
  "returnUrl": "http://example.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Ear buds"
}'

Specify "customerInteraction": "CUSTOMER_PRESENT", since the customer is present. You can also specify the order details at this time.

Display the dynamic QR on a screen facing the customer.

One-time payment QR Flow

When the customer scans the QR code and are directed to the Vipps or MobilePay app, the payment screen is presented and they click Pay.

`NATIVE_REDIRECT`

warning

Please consider WEB_REDIRECT alternative as this is safer and provides fallback to the landing page in case the Vipps or MobilePay app can't be found.

On Apple, we recommend universal links. On Android, we recommend asset links, also called "App links".

We do not recommend deep-linking with NATIVE_REDIRECT for app to app implementations. NATIVE_REDIRECT should only be used if the merchant doesn't have a web presence at all. WEB_REDIRECT has enhanced security and improved cross-platform compatibility.

Applicable only for WALLET payments initiated from an app on the user's phone.

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": {
        "value": 15000,
        "currency": "DKK"
    },
    "paymentMethod": {
        "type": "WALLET"
    },
    "customer": {
        "phoneNumber": "4512345678"
    },
    "reference": 21203831704360461822,
    "userFlow": "NATIVE_REDIRECT"
}'

This should cause a switch from the merchant app to the Vipps/MobilePay app and back; however, it should only be used if the merchant doesn't have a web presence at all. Please see Knowledge base: App flow recommendations for more details.

App switch integration

We recommend that you use WEB_REDIRECT and implement universal links/asset links (starting with https) as they contain built-in logic to handle both desktop and mobile flow. They are more secure than the deep link flow and provide a better user experience.

Please see Knowledge base: App flow recommendations for more details.

App notifications

When an ePayment is created, the customer receives a push notification that approval is needed. No further notifications (push or SMS) are sent if the payment isn’t approved or completed.

The payment status remains visible in the app for the customer to act on at any time.

Rate limiting

We have added rate limiting to our APIs to increase the stability and security of our APIs. For details, see Rate limits.

The create payment request​

Parameters​

Header​

Body​

paymentMethod​

WALLET​

CARD​

userFlow​

WEB_REDIRECT​

PUSH_MESSAGE​

Troubleshooting​

"PUSH_MESSAGE flow not allowed"​

QR​

NATIVE_REDIRECT​

App switch integration​

App notifications​

Rate limiting​

The create payment request

Parameters

Header

Body

`paymentMethod`

`WALLET`

`CARD`

`userFlow`

`WEB_REDIRECT`

`PUSH_MESSAGE`

Troubleshooting

"PUSH_MESSAGE flow not allowed"

`QR`

`NATIVE_REDIRECT`

App switch integration

App notifications

Rate limiting