Long-living payment requests

Available for Vipps.

Available for MobilePay in selected markets at the Vipps MobilePay joint platform launch.

💥 From Q4 2023, we will additionally send a push notification to the user when the payment is getting close to expiring. 💥

Vipps MobilePay offers Long-living payment requests for creating invoices and payments that can be postponed up to 28 days.

Please note: The user experience, including the standard timeout, should be as consistent as possible, so this should only be used in special cases. To request this feature, please contact your key account manager, your partner manager, or customer service.

Vipps

MobilePay

Prerequisites

Webhooks for ePayment events

Register a webhook to alert you when your payment requests are approved.

What are webhooks?

When changes happen to your payment request, events are triggered (for example: Authorized, Terminated, Aborted, Cancelled, Expired, and many more).

You can register to receive these events, which is useful for programming an appropriate and quick response.

The webhook will send a message to your web server at the URL you specify.

Here is an example HTTP POST:

POST:/webhooks/v1/webhooks

{  
    "url": "https://example.com/mystore_website_backend",
    "events": ["epayments.payment.authorized.v1"]
}

Use the secret to authenticate the message with HMAC. For examples, see Webhooks API: Request authentication.

The payload from the ePayment webhooks will be in this form:

{
    "msn": "123456",
    "reference": "24ab7cd6ef658155992",
    "pspReference": "1234567891",
    "name": "AUTHORIZED",
    "amount":
    {
        "currency": "NOK",
        "value": 35000
    },
    "timestamp": "2023-08-14T12:48:46.260Z",
    "idempotencyKey": "49ca711a9487112e1def",
    "success": true
}

Note that the payload of the webhook depends on the originating service, in this case the ePayment API.

Customer's phone number

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

If you don't know your customer's phone number, you can start by sending them a link to your own landing page. There, you can trigger a payment request through Vipps MobilePay, which will request their phone number automatically.

Details

Step 1. Create a payment request

Send a create payment request, where customer.phoneNumber is set.

The customer will receive a push notification in their Vipps or MobilePay app.

Detailed example

Your system can send the payment request by using the createPayment endpoint.

Specify the WALLET payment method. This functionality is only available when using WALLET, since the app is required.

Specify expiresAt with a value between 10 minutes and 28 days (40320 minutes) in the future.

Set userFlow to PUSH_MESSAGE to send a push directly to the customer. Attach the receipt simultaneously.

You can also add the receipt at this time.

Here is an example HTTP POST:

POST:/epayment/v1/payments

With body:

{
  "amount": {
    "value": 300000,
    "currency": "NOK"
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": 4791234567
  },
  "receipt":{
    "orderLines": [
      {
        "name": "Accident insurance",
        "id": "12345",
        "totalAmount": 150000,
        "totalAmountExcludingTax": 112500,
        "totalTaxAmount": 37500,
        "taxPercentage": 25,
      },
      {
        "name": "Travel insurance",
        "id": "12345",
        "totalAmount": 150000,
        "totalAmountExcludingTax": 112500,
        "totalTaxAmount": 37500,
        "taxPercentage": 25,
      },
    ],
    "bottomLine": {
      "currency": "NOK",
    },
   "receiptNumber": "0527013501"
  },
  "reference": 1648738112,
  "userFlow": "PUSH_MESSAGE",
  "expiresAt":"2024-08-04T00:00:00Z",
  "returnUrl": "http://www.merchant.com/redirect?reference=2486791679658155992",
  "paymentDescription": "Spendings"
}

See ePayment API: Long-living payments for more details.

Step 2. Customer approves the payment

The payment request will appear in the customer's Vipps or MobilePay app, where they can select to pay or cancel.

To get confirmation that payment was approved, monitor your webhooks.

Once the payment is approved, update the status in your system.

Since you have already attached order information to this payment, the customer will be able to see this in their Vipps or MobilePay app. When they select Show details in the payment confirmation screen, they are presented with the order information without leaving the app.

Note that, for long-living payments, customers also have the option of soft-dismissing the payment and postponing it for later.

Step 3. Capture the payment

Capture the payment and confirm that it was successful.

Detailed example

POST:/epayment/v1/payments/{reference}/capture

With body:

{
  "modificationAmount": {
    "value": 300000,
    "currency": "NOK"
  }
}

Sequence diagram

Sequence diagram for the standard online payment flow, where payment request is sent directly to app.