Skip to main content

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:

  • a QR code being scanned
  • a payment being authorized or captured

Your registration will apply to the sales unit you specify with the 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

  1. Event Occurs: An event happens in Vipps MobilePay (e.g., payment authorization, QR code scan).

  2. Webhook Triggered: Vipps MobilePay detects the event and triggers a webhook.

  3. HTTP Request Sent: An HTTP POST request with event details is sent to the predefined webhook endpoint.

  4. Endpoint Receives Data: Your server's endpoint listens for and processes the incoming HTTP POST request.

  5. Process the Data: The server processes the received data, which may involve updating a database, triggering another process, or sending a notification.

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

For a quick and seamless integration of Webhooks, explore our SDK.

Register a webhook​

Send the registration request​

You can register to get notifications for events that happen in Vipps MobilePay (e.g., get notified when a QR code is scanned). See an overview of all the events.

To register, make a POST:/webhooks/v1/webhooks request to register for the desired events. Specify the URL, where you will receive the webhook notifications.

For example:

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" \
-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" \
--data '{  
    "url": "CALLBACK-URL", 
    "events": ["epayments.payment.captured.v1"] 
}'

Replace the above placeholders with your values:

You will receive a response similar to this, confirming that the webhook registration was successful:

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

Take note of the secret, because you will need this for authenticating the notifications you receive from us.

Webhook limits​

For each sales unit (MSN), the following restrictions apply:

  • ePayment API events - Max 25 webhook registrations per event type per sales unit (MSN)
  • Login API events - Max 25 webhook registrations per event type per sales unit (MSN)
  • QR API events - Max one webhook registration per event type per sales unit (MSN)
  • Recurring API events - Max 25 webhook registrations per event type per sales unit (MSN)

For example, a merchant can register to receive webhooks for as many as 25 different URLs for any of the epayment event types relating to an MSN.

For partners

A partner can have this specified number of webhooks for every sales unit (MSNs) they manage. Partner webhook counts are completely independent of merchant webhook counts.

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.

  1. 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 About webhook retries for more details.

  2. Authenticate the reply

    The HTTP POST request must be verified before you can get the message. See the Request authentication page for details.

  3. 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 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" \
-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" \
--data ''

Example response:

{
  "webhooks": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "url": "https://example.com/callbacks",
      "events": [
        "service.payment.captured.v1",
      ]
    }
  ]
}

Delete a webhook registration​

Send DELETE:/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' \
-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' \
--data ''

About webhook retries​

Failed webhook notifications are retried with an exponential backoff for up to 7 days. After all retries are exhausted, the notification is never sent again. This applies to both new and previously created webhooks.

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.

For example, if you reply with HTTP 500 Server Error to an authorization notification, a new notification about the same payment being captured will not be sent unless you reply with a successful HTTP status code, like HTTP 200 OK, to one of the retry attempts.

Any response with HTTP status code in range 4-5xx or no response within 10 seconds will result in a retry. Delay between retries will be progressively slower to not overwhelm receivers.

Webhook timing and retry strategy

After the first failure this is the retry strategy:

  • First 4 retry attempts: Wait 2 seconds between each retry.
  • 5th attempt: Wait 60 seconds before retrying.
  • 6th attempt: Wait 120 seconds before retrying.
  • Attempts 7 to 29: Wait 1 hour between each retry.
  • After 29 attempts: Wait 1 day between each retry.

Webhooks timing and retry strategy are subject to change without further notice.

Partner webhooks​

As a partner, you can access endpoints with your usual key, client ID, and secret, without MSN. Any webhooks registered by a partner will trigger for the subscribed events from ANY sales unit registered to the given partner. This is also applicable for sales unit that are created in the future.

Help us improve our documentation

Did you find what you were looking for?