> **Description:** Step-by-step guide to quickly set up and test webhook notifications, with examples for endpoint configuration and event handling.

# Quick start

This guide walks you through registering webhooks.

If you're new to the platform, see
[Getting started](https://developer.vippsmobilepay.com/docs/getting-started.md)
for information about API keys, product activation, and the test environment.

## Step 1 - Setup

You will need the following values from your [sales unit API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-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 and PSPs).

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.

You will need the following values from your [merchant-level keys](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md#how-to-get-the-api-keys):

* `client_id` - Client ID from your merchant-level keys.
* `client_secret` - Client secret from your merchant-level keys.

## 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`](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml).
For example:

```bash
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](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) for details.

See [Donations API guide](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md) for step-by-step instructions on requesting an access token.

Then use your token in the `Authorization` headers for the endpoints in this file.

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`](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types).

For a complete list of event types, see [events](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md).

For the callback URL, use your webhook server address.

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

```bash
curl -X POST https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
--data '{
    "url": "YOUR-CALLBACK-URL",
    "events": ["epayments.payment.created.v1"]
}'
```

A successful registration returns a response like this:

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

You can verify your webhook registration with [`GET:/webhooks/v1/webhooks`](https://developer.vippsmobilepay.com/redocusaurus/webhooks-swagger-id.yaml).

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

```bash
curl -X GET https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
--data ''
```

The response looks like this:

```json
{
  "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`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml).
See [Create payment](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/create.md) for details.

```bash
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"
}'
```

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-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:

```json
{
  "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](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types).

In production, validate the webhook to ensure the content hasn't been tampered with.
See [How to authenticate the webhook event](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication.md) for details.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).