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.

Parameters

The required header parameters are:

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

The required body parameters are:

amount - Amount object, containing a value and a currency. The minimum amounts allowed are: NOK 100 øre, DKK 1 øre, EUR 1 cent
paymentMethod - Type must be either WALLET or CARD
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 body parameters for special features:

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

Several other parameters are detailed in the create payment spec.

Example 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":"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",
   }'

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

User flows

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.
`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.
`QR`	The `QR` flow returns a QR code that is scanned by the user to complete the payment.

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

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

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

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

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.

Rate limiting

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

Special features

See the ePayment Features section for all the special features. For example:

and many more...

The create payment request​

Parameters​

paymentMethod​

WALLET​

CARD​

User flows​

WEB_REDIRECT​

Important information for the default WEB_REDIRECT flow​

NATIVE_REDIRECT​

PUSH_MESSAGE​

QR​

App switch integration​

Rate limiting​

Special features​

The create payment request

Parameters

`paymentMethod`

`WALLET`

`CARD`

User flows

`WEB_REDIRECT`

Important information for the default `WEB_REDIRECT` flow

`NATIVE_REDIRECT`

`PUSH_MESSAGE`

`QR`

App switch integration

Rate limiting

Special features