Skip to main content

Create payment

The first step in the payment flow is to create a payment with POST:/epayment/v1/payments. This endpoint supports both wallet (i.e., the Vipps or MobilePay app) and freestanding card payments, when card details are entered. Each payment type offers separate user flows.

User flows

The paymentMethod.type in the request determines the type of payment:

  • WALLET: 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: The user pays with a card. They enter the card details into a form and then complete the 3D Secure step-up for SCA. See Card payments for more information.

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

General create request example

Here is an example HTTP POST:

POST:/epayment/v1/payments

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"
      },
      "receipt":{
         "orderLines": [
            {
               "name": "Socks",
               "id": "line_item_1",
               "totalAmount": 1000,
               "totalAmountExcludingTax": 800,
               "totalTaxAmount": 200,
               "taxRate": 2550,
               "unitInfo": {
               "unitPrice": 400,
               "quantity": "2.5",
               "quantityUnit": "KG"
               },
               "discount": 0,
               "productUrl": "https://example.com/store/socks",
               "isReturn": false,
               "isShipping": false
            },
            {
               "name": "Flip-flops",
               "id": "line_item_2",
               "totalAmount": 5000,
               "totalAmountExcludingTax": 4000,
               "totalTaxAmount": 1000,
               "taxRate": 2550,
               "unitInfo": {
               "unitPrice": 2500,
               "quantity": "3",
               "quantityUnit": "PCS"
               },
               "discount": 2500,
               "productUrl": "https://example.com/store/flipflops",
               "isReturn": false,
               "isShipping": false
            }
         ],
         "bottomLine": {
            "currency": "NOK",
            "tipAmount": 0,
            "posId": "pos_122",
            "paymentSources": {
               "giftCard": 0,
               "card": 0,
               "voucher": 0,
               "cash": 0
            },
            "barcode": {
               "format": "CODE 39",
               "data": "SC0527013501"
            },
            "receiptNumber": "0527013501"
         }
      },
      "reference":"acme-shop-123-1234589",
      "paymentDescription": "Invoice# 424243, due date: 01 Jan 2025",
      "returnUrl":"https://example.com/redirect?orderId=1512202",
      "userFlow":"WEB_REDIRECT",
   }'

The minimum amounts allowed are NOK 100 øre, DKK 1 øre, EUR 1 cent.

Payment guidelines

You should capture as soon as is legally possible after a payment is reserved, because some banks will release the funds after some days, making it difficult to capture later. If it's not captured within the payment capture deadlines, it will be automatically cancelled.

However, be aware that it isn't legal to capture before the product or service is provided to the customer, as per the capture regulations.

If you do not plan to capture the entire amount, please make sure to cancel the remainder as soon as possible. Cancelling the remaining reservations will benefit the consumer, freeing up the amount for other purposes.

If you need to communicate some change to the payment after it has been reserved, you will need to send a new API request. You can refund and cancel, as well as other operations. The Electric vehicle charging flow shows an example of partially capturing the payment and then cancelling the remainder.

Rate limiting

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

User flow alternatives​

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

userFlowDescription
WEB_REDIRECTWEB_REDIRECT is the normal flow. It works for browsers and native apps, since we take care of all the app-switching. If on a mobile device, the Vipps or MobilePay app will open automatically with app-switch. Otherwise, the landing page will open. A valid value for returnUrl is required.
PUSH_MESSAGEPUSH_MESSAGE 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.
QRQR returns a QR code that can be scanned to complete the payment.
NATIVE_REDIRECTNATIVE_REDIRECT is not recommended, except in some cases where merchant doesn’t have web presence. It provides automatic app-switch between the merchant's native app and the Vipps or MobilePay app. We recommend using WEB_REDIRECT instead.

WEB_REDIRECT​

Applicable for both WALLET and Card payment flows.

This is the default flow for webshops and apps. WEB_REDIRECT provides fallback to the landing page in case the Vipps or MobilePay app can't be found.

  • In WALLET flow: When the user is on a mobile device, redirect them to the Vipps or MobilePay app. From the desktop, open the landing page.

  • In Card flow: Whether the user is on a desktop or mobile device, open the card entry page. See Card payments for more information.

For app integration, WEB_REDIRECT is more secure than NATIVE_REDIRECT and better cross-platform compatibility. Please see Knowledge base: App flow recommendations for more details.

PUSH_MESSAGE​

Applicable only for WALLET payments initiated on a device other than the user's device.

For payments initiated on a device other than the user's phone. The user gets a push message that opens the payment in the app.

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.

If userFlow is PUSH_MESSAGE, a valid customer is required.

Please note: 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.

For more details, also see skipLandingPage.

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.

NATIVE_REDIRECT​

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

This can be used to 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.

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.

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

Reference ID​

The reference field is used to identify a transaction. The value must be unique for a sales unit (i.e., Merchant Serial Number). Please read orderId / reference for more recommendations.

Receipt​

Add a receipt to the payment. This includes the order Lines for the payment, which are identical to those referenced in the Order Management API.

Applicable only for WALLET payments.

Minimum user age​

Limit payments to people over a minimum age by specifying the minimumUserAge property.

For example:

{
   "amount":{
      "currency":"NOK",
      "value": 16000
   },
   "minimumUserAge": 100,
   "paymentMethod":{
      "type":"WALLET"
   },
   "reference":"acme-shop-123-order123abcd4",
   "paymentDescription": "Reference acme-shop-123-order123abcd. Thank you for shopping at our webshop!",
   "returnUrl":"https://example.com/redirect?reference=12345989434343",
   "userFlow":"WEB_REDIRECT"
}

See Features: Minimum user age for details.

Block payment sources​

In the Danish and Finnish markets, it is possible to block payment sources when using WALLET as payment method type.

Specify the blockedSources parameter in the POST:/epayment/v1/payments request.

For example:

{
  "amount": {
    "value": 49900,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET",
    "blockedSources": ["COMMERCIAL_CARDS"]
  },
  "reference": 2810171731400321010,
  "userFlow": "WEB_REDIRECT",
  "returnUrl": "https://developer.vippsmobilepay.com/docs/example-pages/result-page",
  "paymentDescription": "Reference 2810171731400321010 from webshop.no"
}

This is only available for Danish and Finnish sales units. If you attempt with a Norwegian sales unit, you will get the error message:

{
   "extraDetails": [],
   "type": "https://httpstatuses.io/400",
   "title": "Blocking sources not applicable",
   "status": 400,
   "detail": "Not possible to block payment sources for market: 'Norwegian'",
   "instance": "/v1/payments"
}

In Norway, there may be cases where your customers cannot use a credit card. If this is the case, contact your KAM.

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

Help us improve our documentation

Did you find what you were looking for?