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

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

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

# 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

#### Merchants, partners, and PSPs

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.

#### Donations

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.

#### Merchants, partners, and PSPs

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.

#### Donations

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.

#### Merchants, partners, and PSPs

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

#### Donations

```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).

#### Merchants, partners, and PSPs

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

#### Donations

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

#### Merchants, partners, and PSPs

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

#### Donations

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