Quick start

This guide takes you through registering webhooks.

Before you begin

client_id - Client_id for a test sales unit.
client_secret - Client_secret for a test sales unit.
Ocp-Apim-Subscription-Key - Subscription key for a test sales unit.
merchantSerialNumber - The unique ID for a test sales unit.

If you're new to the platform, see Getting started for information about API keys, product activation, and the test environment.

The provided example values in this guide must be changed with the values for your sales unit and user. This applies for API keys, HTTP headers, reference, phone number, etc.

Step 1 - Setup

If using Postman, download the following files and import them into Postman. Select the global environment as your active environment and update the Current Value field with your own values for the API keys and international mobile number. 🔥 Do not store production keys in the cloud. 🔥

Step 2 - Get an access token

For the following steps, you will need an access_token from the Access token API: POST:/accesstoken/get. This provides you with access to the API.

curl
Postman

Send request "Get Access Token"

curl -X POST 'https://apitest.vipps.no/accesstoken/get' \
-H "Content-Type: application/json" \
-H 'client_id: YOUR-CLIENT-ID' \
-H 'client_secret: YOUR-CLIENT-SECRET' \
-H 'Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY' \
-H 'Merchant-Serial-Number: YOUR-MSN' \
--data ''

For production, include all the Vipps-System headers so that we can help with debugging any problems. For details, see HTTP headers.

The property access_token should be used for all other API requests in the Authorization header as the Bearer token.

Step 3 - Register a webhook

For a complete list of event types, see events.

For the callback URL, use your webhook server address.

curl
Postman

Send request "Register"

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": "YOUR-CALLBACK-URL", 
    "events": ["epayments.payment.created.v1"] 
}'

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"
}

You can check for your webhook registration with GET:/webhooks/v1/webhooks.

curl
Postman

Send request "Get All"

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 ''

You'll get a response like this:

{
  "webhooks": [
    {
      "id": "25f48471-6ac7-4df9-81b2-e239540b7566",
          "url": "YOUR-CALLBACK-URL",
          "events": [
              "epayments.payment.created.v1"
          ]
    }
  ]
}

Step 4 - Trigger an event

Initiate a payment with: POST:/epayment/v1/payments. See Create payment for details.

curl
Postman

Send request "Create Payment - Web redirect"

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' \
-d '{
  "amount": {
    "currency": "NOK",
    "value": 49900
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": "YOUR-PHONE"
  },
  "reference": "acme-shop-123-order123abc",
  "returnUrl": "https://yourwebsite.com/redirect?reference=abcc123",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'

Step 5 - View the webhook

You should get a new POST event in your webhook server with content similar to this:

{
  "msn": "123456",
  "reference": "acme-shop-123-order123abc",
  "pspReference": "dd8e0a8e-2b26-40ed-98f1-1d5832fc129f",
  "name": "CREATED",
  "amount": {
    "currency": "NOK",
    "value": 49900
  },
  "timestamp": "2025-02-19T16:26:32.099Z",
  "idempotencyKey": "7c8b81e7-b08b-46e4-9729-191cb801c132",
  "success": true
}

This matches the payload format for the ePayment API events.

For your production implementation, you should validate the webhook, to ensure that the content hasn't been tampered with. For details, see How to authenticate the webhook event.

Before you begin​

Step 1 - Setup​

Step 2 - Get an access token​

Step 3 - Register a webhook​

Step 4 - Trigger an event​

Step 5 - View the webhook​