Skip to main content

Quick start

View as Markdown (opens in a new tab)
Install AI tools

Give your assistant up-to-date guidance for our APIs, with our plugin or without it.

The plugin is still under development. See the AI tools page for details.

Run both commands, in order.

claude plugin marketplace add vippsas/agent-toolkit
claude plugin install vipps-developer@agent-toolkit

For troubleshooting, see the full instructions.

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.

With sales unit or partner keys​

Follow these steps if you authenticate with sales unit API keys or partner keys. If you have merchant-level keys for Donations, follow With Donations merchant-level keys instead.

Step 1 - Setup​

You will need the following values from your sales unit 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.

No setup is needed. Continue to Step 2.

Step 2 - Get an access token​

All the API endpoints require that you first obtain an API token. Get an access token with POST:/accesstoken/get.

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.

With Donations merchant-level keys​

Step 1 - Setup and get an access token​

You will need the following values from your merchant-level keys:

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

See Donations API guide for step-by-step instructions on requesting an access token.

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

Step 2 - Register a webhook​

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

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

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" \
--data ''

Step 3 - Trigger an event​

Initiate a payment with: POST:/epayment/v1/payments.

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 4 - View the webhook​

Your webhook server should receive a POST event like the one in Step 5 - View the webhook.

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