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.

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.

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