Quick start

This guide takes you through registering webhooks and testing the results from ePayment API requests.

Explore the other pages of this API guide for more details about each endpoint and to learn about special features.

Before you begin

You must have already signed up as an organization with Vipps MobilePay and have your API keys.

Get these API key values for your sales unit (How to find the API keys):

• client_id - Client_id for a test sales unit.
• client_secret - Client_id for a test sales unit.
• Ocp-Apim-Subscription-Key - Subscription key for a test sales unit.
• merchantSerialNumber - The unique ID for a test sales unit.

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

Step 1 - Set up Postman (if applicable)

curl

warning

🔥 Do not store production keys in the Postman cloud. 🔥

To prevent your sensitive data and credentials from being synced to the Postman cloud, store them in the Current Value fields of your Postman environment.

Open Postman and do the following:

1. Import the following files:

   • Webhooks API Postman collection
   • Global Postman environment

2. Select to use the imported global environment.

3. In the global environment, update the Current Value field with your own values for the following:

   • callbackUrl - This is your webhook server
   • client_id
   • client_secret
   • Ocp-Apim-Subscription-Key
   • merchantSerialNumber
   • internationalMobileNumber

Postman

No setup needed for curl.

Step 2 - Get an access token

For the following steps, you will need an access_token from the Access token API: POST:/accesstoken/get. This provides you with access to the API.

curl

Send request 'Get Access Token'

Postman

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

For production, include all the Vipps-System headers so that we can help with debugging any problems. For details, see HTTP headers.

The property access_token should be used for all other API requests in the Authorization header as the Bearer token.

Step 3 - Register a webhook

Register to get a webhook when we create a payment. This is the epayments.payment.created.v1 event.

For a complete list of event types, see events.

For the callback URL, use your webhook server address.

curl

Send request 'Register'

Postman

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

You will receive a response similar to this, confirming that the webhook registration was successful:

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

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

curl

Send request 'Get All'

Postman

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

You'll get a response 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

Send request "Create Payment - Web redirect"

Postman

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.come/redirect?reference=abcc123",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'

Step 5 - View the webhook

You should get a new POST event in your webhook server 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": "2025-02-19T16:26:32.099Z",
  "idempotencyKey": "7c8b81e7-b08b-46e4-9729-191cb801c132",
  "success": true
}

This matches the payload format for the ePayment API events.

For your production implementation, you should validate the webhook, to ensure that the content hasn't been tampered with. For details, see How to authenticate the webhook event.