Skip to main content

Long-living payments

Restricted access

The Long-living payments feature is enabled on case-by-case basis. For more information, see Legal terms.

Scenarios​

The following sections will explain how to implement this feature for different scenarios.

Scenario 1. Payment request sent directly to the app​

If you have the customer's phone number and their consent to send payment requests through Vipps MobilePay, you can send payment requests directly to their app.

MobilePay payment setting URL

  1. Since you have the customer's phone number, send the create payment request where customer.phoneNumber is set.
  2. The customer will receive a push notification in their Vipps or MobilePay app.
  3. When the customer selects Show details in the payment confirmation screen, they are presented with the order information provided by the merchant without leaving the Vipps or MobilePay app.
  4. The customer approves, rejects, or postpones the payment.
  5. The user will be able to retrieve the order details in the app under Activities.

On your website, mobile app, paper document, or email, provide your customers with an option for paying with Vipps or MobilePay.

The flow for the customer will look like this:

Vipps payment request from link

  1. When they click the link or scan the QR, your system will send the create payment request.
    • If the customer is on a mobile device, the Vipps or MobilePay app opens automatically.
    • If the customer is on a desktop computer, the landing page will open and they will enter their phone number and can continue in their Vipps or MobilePay app.
  2. In the app, the customer can see the details of the payment before approving, rejecting, or delaying the payment.
  3. The user will be able to retrieve the order details in the app under Activities.

If you want to get the user's phone number as part of this process, you can request that they share their profile information. This would introduce an extra page, as shown below.

Vipps payment request from link

Customer options​

In addition to the normal approve option, the customer can deny or delay the payment.

They delay the payment by tapping Not now. It will be shown in their Activities section, and they will be reminded about it 72 and 24 hours before the deadline, if it is still unpaid.

Vipps delay

They reject the payment by tapping decline.

Vipps delay

Creating a long-living payment​

Specify expiresAt in the create payment request. The expiresAt must be between 10 minutes and 60 days in the future, or within the maximum extension limit established for your sales unit.

Unless the payment has already been completed or cancelled, we send two reminder notifications:

  • First Reminder: Sent 72 hours before the payment expires.
  • Second Reminder: Sent 24 hours before the payment expires.
note

This functionality is only available when using the WALLET payment method, since the app is required (it does not work with freestanding card payments).

After creating a payment a push message will be sent to the customer's app (specified with phoneNumber), and the customer confirms the payment.

If the customer's phone number is unknown, the request can specify userFlow as QR. This will return the QR code for a payment, including the expiration time specified. The customer scans the QR code to complete the payment flow in the app.

If a payment is initiated with the expiresAt for a sales unit that is not allowed to use the feature, the response will be an error. If this issue arises, please contact us.

To create a payment request with long-living expiry date, use the POST:/epayment/v1/payments with the following parameters :

  • paymentMethod.type - The payment method type must be WALLET.
  • reference - The ID of the payment request.
  • expiresAt - The expiration date for the payment in RFC 3339 format. This is what separates the long-living payment request from a regular payment.
  • userFlow - Must be "PUSH_MESSAGE" or "QR". Use PUSH_MESSAGE to send a push directly to the customer.
  • paymentDescription - Short description with relevant information about the payment request.
  • receipt.orderLines or receiptUrl - Order details for the payment. Note that in Norway, you must specify receipt.orderLines instead of receiptUrl. The orderlines are the same as referenced in the Order Management API. This must be present.
  • customer.phoneNumber - The customer's phone number. This is optional, and will be used if the users phone number is known in advance.
  • scope - This can be used to request the user to share their telephone number.

Payment details​

In Norway, it is mandatory to supply the payment details.

When setting the expiresAt property, it is a requirement to provide information about the products being sold. Often that would be in the form of an "invoice". This data can be used for Content monitoring.

There are two ways of adding information or an invoice via the API. Either by providing order lines or a URL to a website or a PDF file located on a server.

Orderlines vs link

If you link to a website with a PDF, then the website must be able to render the PDF itself.

Note that it's not possible to add both order lines and a URL at the same time. When doing so an error will be thrown when creating the payment.

Example​

To initiate a long-living payment, call the create payment endpoint, POST:/epayment/v1/payments, with expiresAt set to a date according to RFC 3339 format.

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 '{
   "expiresAt":"2025-06-15T23:59:59+02:00",
   "paymentDescription": "Invoice# 424243, due date: 15 June 2025",   
   "paymentMethod":{
      "type":"WALLET"
   },
   "receipt":{
      "orderLines": [
         {
            "name": "Service or product name",
            "id": "line_item_1",
            "totalAmount": 12900,
            "totalAmountExcludingTax": 10320,
            "totalTaxAmount": 2580,
            "taxRate": 2500
         }
      ],
      "bottomLine": {
         "currency": "NOK",
         "receiptNumber": "20250514-00123"
      }
   },
   "amount":{
      "currency":"NOK",
      "value":12900
   },
   "customer":{
      "phoneNumber": CUSTOMER-PHONE-NUMBER
   },
   "reference":"acme-shop-123-order123abc",
   "userFlow":"PUSH_MESSAGE"
}'

With long-living payments, it is mandatory to supply the order details through either receiptor receiptUrl. An example of receiptUrlis: "receiptUrl": "https://example.com/link/to/my.pdf".

For examples of the orderlines, see the Order details section.

Sequence diagram​

Integration sequence for the standard payment flow, where payment request is sent directly to app.

Standard payment flow

Approval necessary

Long-living payment requests are enabled by Vipps MobilePay on case by case basis to Merchants and sales units that fulfil the requirements set forth by Vipps MobilePay from time to time.

To enable Long-living payment requests, please contact your key account manager or partner manager.

In Denmark: Available upon request.

In Finland: Available to Merchants who previously had MobilePay Invoice.

In Norway: Available in special circumstances

General requirements​

The ePayment API enables setting the timeout for a payment in certain circumstances. The timeout can range from 10 minutes to the maximum allowable timeout for your sales unit, which can be up to 60 days. However, to secure a consistent user experience we advise avoiding longer than 10-minute timeouts unless they are necessary for a special use case.

For avoidance of doubt, Vipps MobilePay is not responsible if the customer doesn’t approve the payment request. Merchant will remain responsible for monitoring the status of the payment and collecting any outstanding payments.

Additional requirements for Norwegian Merchants​

  • Timeout can not exceed 24 hours.
  • The customer must be present at the time the service is performed and/or agreed upon.
  • The customer must be informed of and agree to Merchant’s terms of sale, including relevant information on payment methods and applicable charges. Vipps MobilePay may require the Merchant to verify the customer’s acceptance.
  • The Merchant may send the payment request only after the delivery of the product or service.
  • The Merchant must add purchase order lines in the payment request.
Last updated on

Help us improve our documentation

Did you find what you were looking for?