Skip to main content

Quick start

This guide walks you through registering webhooks.

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

Step 1 - Setup​

Get your API keys:

  • client_id - Client ID for a sales unit.
  • client_secret - Client secret for a sales unit.
  • Ocp-Apim-Subscription-Key - Subscription key for a sales unit.
  • Merchant-Serial-Number - The unique ID for a sales unit (required for partners).

Replace all example values in this guide with the values for your sales unit and user. This applies to API keys, HTTP headers, references, and phone numbers.

Step 2 - Get an access token​

All the API endpoints require that you first obtain an API token.

Get access token with POST:/accesstoken/get. For example:

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

In production, include all Vipps-System headers to aid debugging. See HTTP headers for details.

Use the access_token value as the Bearer token in the Authorization header for all subsequent API requests.

Step 3 - Register a webhook​

Register a webhook for the payment created event: epayments.payment.created.v1.

For a complete list of event types, see events.

For the callback URL, use your webhook server address.

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

A successful registration returns a response like this:

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

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

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

The response looks 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 -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​

Your webhook server should receive a POST event 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": "2026-01-19T16:26:32.099Z",
  "idempotencyKey": "7c8b81e7-b08b-46e4-9729-191cb801c132",
  "success": true
}

This matches the payload format for the ePayment API events.

In production, validate the webhook to ensure the content hasn't been tampered with. See How to authenticate the webhook event for details.

Last updated on