Webhooks API guide

Webhooks enable real-time communication from Vipps MobilePay to your server. Through our webhooks feature, we can automatically send messages to your application when a specific event occurs.

The Webhooks API allows you to register for receiving notification of a variety of events from our API platform, such as:

Users scanning your QR codes
Creating a payment request
Users authorizing the payment

Your registration will apply to the sales unit specified by Merchant Serial Number.

Once you have registered for an event, you will be notified when any matching events are published for the given sales unit.

The webhooks flow

Event Occurs: An event happens in Vipps MobilePay (e.g., payment authorization, QR code scan).
Webhook Triggered: Vipps MobilePay detects the event and triggers a webhook.
HTTP Request Sent: An HTTP POST request with event details is sent to the predefined webhook endpoint.
Endpoint Receives Data: Your server's endpoint listens for and processes the incoming HTTP POST request.
Process the Data: Your server processes the received data, which may involve updating a database, triggering another process, or sending a notification.
Response: Optionally, your server can send a response back to acknowledge receipt of the webhook.

note

Webhooks can provide information about payment operations to you. If you need to communicate some change to a payment, you will need to send a new API request from the API you used to create the payment. The Electric vehicle charging flow shows an example of this.

Important

Track status with both webhooks and polling.

In the rare cases where webhooks may be delayed: Poll for payment details. The merchant should not rely on webhooks alone, and should poll according to the polling recommendations.

Webhook limits

You can register up to the following number of URLs for each event type for a sales unit:

ePayment API events - Up to 25 webhook registrations per event type, per MSN.
Login API events - Up to 25 webhook registrations per event type, per MSN.
QR API events - 1 webhook registration per event type, per MSN.
Recurring API events - Up to 25 webhook registrations per event type, per MSN.

For example, a merchant can register up to 25 different URLs to receive webhooks for an ePayment event type related to a single MSN.

For partners

Partners can register the above number of webhooks for:

a specific sales unit, or
all the sales units they manage (i.e., partner webhook)

These webhook counts are completely independent of merchant webhook counts.

Retry strategy

We'll retry if:

Your server responds with an HTTP status code in the range 4xx–5xx, or
No response is received within 10 seconds.

Retries will slow down progressively and end after 7 days.

We use an exponential backoff to retry failed notifications for up to 7 days.
- Attempts 1–4: Retries happen every 2 seconds.
- Attempt 5: We wait 60 seconds before retrying.
- Attempt 6: We wait 120 seconds before retrying.
- Attempts 7–29: Retries happen every hour.
- After 29 attempts: We switch to a daily retry schedule.
After 7 days, if all retry attempts fail, the notification won't be sent again.

Important: This retry scheme may change in the future as we continuously work to improve service quality. Make sure your solution doesn't rely on this specific timing.

Delivery order

The delivery order of failed webhook notifications is guaranteed in order per registered webhook. That means your server needs to accept all preceding requests for a given payment, before any new notifications can be received for the same payment.

Example: If your server responds with HTTP 500 Server Error to an AUTHORIZATION notification, we won't send a CAPTURE notification for the same payment until one of the retry attempts for the AUTHORIZATION succeeds (e.g., with HTTP 200 OK).

Endpoint operations

👉 See the Quick start guide for a step-by-step example.

Register a webhook

Send the registration request

You can set up webhook notifications to stay updated on events that happen to your sales unit—for example, when a QR code is scanned.

To register for an event, use the API endpoint POST:/webhooks/v1/webhooks. Specify the URL where webhook notifications should be delivered.

Here's an example request:

curl -X POST https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
--data '{  
    "url": "CALLBACK-URL", 
    "events": ["epayments.payment.captured.v1"] 
}'

Make sure to replace the placeholders. What to replace:

YOUR-ACCESS-TOKEN and YOUR-SUBSCRIPTION-KEY with your API keys.
CALLBACK-URL with the URL of your web server where webhook notifications should be sent.

Successful registration

Once registered, you'll receive a confirmation response like this:

{
   "id":"497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "secret":"090a478d-37ff-4e77-970e-d457aeb26a3a"
}

tip

Take note of the secret, because you will need this for validating that the content of the webhook hasn't been tampered with. For details, see How to authenticate the webhook event.

Receive the webhook notification

Whenever your selected events occur, we will send you a notification. You will need to listen for this, authenticate it, and then process the content.

Get the reply

The webhook notification, in the form of an HTTP POST request, is sent to the URL address you supplied. Your server's endpoint listens for and processes the incoming HTTP POST request.

Failed webhook notifications are retried with an exponential backoff for up to 7 days. See Webhook retry strategy for more details.
Authenticate the reply

Validate the webhook, to ensure that the content hasn't been tampered with. For details, see How to authenticate the webhook event.
Process the payload

Once a notification is authenticated, you will be able to receive its payload. This is sent as a POST request to the callback URL you registered. For example:
```
{
   "msn":"123456",
   "reference":"24ab7cd6ef658155992",
   "pspReference":"1234567891",
   "name":"AUTHORIZED",
   "amount":{
      "currency":"NOK",
      "value":35000
   },
   "timestamp":"2023-08-14T12:48:46.260Z",
   "idempotencyKey":"49ca711a9487112e1def",
   "success":true
}
```
This is the payload from the ePayment API webhook. Each API determines the format of their payloads, so be sure to check the event formats for the applicable format.

Get a summary of all webhooks

Send GET:/webhooks/v1/webhooks to get an array of all your registered webhooks, with corresponding IDs. You can use the ID to delete the webhook, if needed.

curl -X GET https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
--data ''

Example response:

{
  "webhooks": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "url": "YOUR-CALLBACK-URL",
      "events": [
        "service.payment.captured.v1",
      ]
    }
  ]
}

Delete a webhook registration

Send DELETE:/webhooks/v1/webhooks/{id} to delete a webhook registration.

Specify the <WEBHOOK-ID> for the webhook to delete.

curl -X DELETE https://apitest.vipps.no/webhooks/v1/webhooks/<WEBHOOK-ID> \
-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' \
--data ''

Advice for switching webhooks

Here's the best way to switch webhooks smoothly:

Set up the new webhooks first: Test them thoroughly to ensure everything runs as expected.
Take down the old ones: Once you're confident the new ones are working, deactivate the old webhooks.
Minimize the overlap: Keep the transition as short as possible to avoid duplicates. If duplicates do happen, make sure you have a solid handling process in place on your end.

Heads up: At the moment, it's not possible to pause events for individual merchants or partners.

Partner webhooks

A partner webhook provides notifications for subscribed events across all sales units managed by the partner, including those created in the future. This eliminates the need for creating several MSN-specific webhooks.

How it works

As a partner, just register a webhook with your partner API keys and don't specify a Merchant Serial Number (MSN).

The webhook limits apply for your partner ID.

Webhook limits​

Retry strategy​

Delivery order​

Endpoint operations​

Register a webhook​

Send the registration request​

Receive the webhook notification​

Get a summary of all webhooks​

Delete a webhook registration​

Advice for switching webhooks​

Partner webhooks​