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

If you need to communicate some change to the payment, 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.

See Rate limits.

User flow alternatives

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

userFlow	Description
WEB_REDIRECT	WEB_REDIRECT is the normal flow for browser-based payment flows. It also works well for 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.
NATIVE_REDIRECT	NATIVE_REDIRECT is the normal flow for native app flows, with automatic (forced) app-switch between the merchant's native app and the Vipps or MobilePay app.
PUSH_MESSAGE	PUSH_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.
QR	QR returns a QR code that can be scanned to complete the payment.

WEB_REDIRECT

This is the default flow for wallet and card payments.

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

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

NATIVE_REDIRECT

Applicable only for WALLET payments.

The redirectUrl will automatically open the Vipps or MobilePay app on mobile devices.

If the user doesn't have the Vipps or MobilePay app installed, they will be taken to Apple's or Google's app store. The landing page will not be shown (unlike for WEB_REDIRECT).

PUSH_MESSAGE

Applicable only for WALLET payments.

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.

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

Set the minimum age required for the customer to make the purchase.

For example, make a POST:/epayment/v1/payments request with the following body:

{
   "amount":{
      "currency":"NOK",
      "value":6000
   },
   "customer":{
      "phoneNumber":"4712345678"
   },
   "minimumUserAge": 25,
   "paymentMethod":{
      "type":"WALLET"
   },
   "reference":"12345989434343",
   "paymentDescription": "Something for older people",
   "returnUrl":"https://example.com/redirect?reference=12345989434343",
   "userFlow":"WEB_REDIRECT",
}

If the user owning the phone number is younger than the specified age (in years), an error message will be provided. In the WEB_REDIRECT flow, the user enters their own phone number and sees the error message in the browser. In the PUSH_MESSAGE flow, the error is returned to you in the response.