API guide

Webhooks enable real-time communication between Vipps MobilePay and your application. 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

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: The 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.

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 the full list of events.

To register, make a POST:/webhooks/v1/webhooks request to register for the desired events. Specify the endpoint address, 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:

YOUR-ACCESS-TOKEN - Access token
YOUR-SUBSCRIPTION-KEY - Subscription key for the API product
YOUR-MSN - Merchant Serial Number for the sales unit
CALLBACK-URL - The url of the web server where we should send the webhook notifications.

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.

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 About webhook retries for more details.
Authenticate the reply

The HTTP POST request must be verified before you can get the message. See the Request authentication page for details.
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 notification

Send GET:/webhooks/v1/{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 1 to 5 failed attempts, wait 2 seconds before sending a new notification.
After 6 to 10 attempts, wait 20 seconds.
After 11 to 15 attempts, wait 1 minute.
After 16 to 38 attempts, wait 1 hour.
After more than 38 attempts, wait 1 day.

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.

Register a webhook​

Send the registration request​

Receive the webhook notification​

Get a summary of all webhooks​

Delete a webhook notification​

About webhook retries​

Partner webhooks​