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 quick start is designed for use with a payment flow using the ePayment API. The same profile sharing flow works with the other APIs, and the basic steps are also covered here for the Recurring API.

Before you begin​

Sign up as an organization with Vipps MobilePay and get your API keys.

You will need the sales unit API keys for a test sales unit:

  • client_id - Client ID for the sales unit.
  • client_secret - Client secret for the sales unit.
  • Ocp-Apim-Subscription-Key - Subscription key for the sales unit.
  • merchantSerialNumber - The unique ID (MSN) for the sales unit.

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

The example values in this guide must be replaced with the values for your sales unit and user. This applies to API keys, HTTP headers, references, phone numbers, and similar values.

Your first user info with the ePayment API​

Step 1 - Setup​

No setup is needed. Continue to Step 2.

Step 2 - Get an access token​

Get an access_token from the Access Token API: POST:/accesstoken/get. This provides you with access to the API.

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.

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

Step 3 - Request a simple payment with profile flow​

Provide the scope object in the POST:/epayment/v1/payments call. This contains the information types that you want access to, separated by spaces (e.g., "name address email phoneNumber birthDate").

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' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
    "amount": {
        "value": 49900,
        "currency": "NOK"
    },
    "paymentMethod": {
        "type": "WALLET"
    },
    "customer": {
        "phoneNumber": 4712345678
    },
    "reference": UNIQUE-PAYMENT-REFERENCE,
    "userFlow": "WEB_REDIRECT",
    "returnUrl": "https://example.com/redirect?reference=UNIQUE-PAYMENT-REFERENCE",
    "paymentDescription": "Purchase of socks",
    "profile": {
        "scope": "name phoneNumber address birthDate"
    }
}'

Step 4 - Complete the payment​

Open the redirectUrl link that is returned, and it will take you to the landing page. The phone number of your test user should already be filled in, so you only have to click Next.

You will be presented with the payment in the app, where you can complete the payment.

Step 5 - Get the sub for the payment​

Call the GET:/epayment/v1/payments/{reference} endpoint. The unique identifier, sub, can be retrieved in the payment details under profile.

curl -X GET https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE \
-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 "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \

Step 6 - Get the user info​

Send request GET:/vipps-userinfo-api/userinfo/{sub} with the sub variable from the previous call.

curl -X GET https://apitest.vipps.no/vipps-userinfo-api/userinfo/{sub} \
-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 "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \

Example response:

{
    "address": {
        "address_type": "home",
        "country": "NO",
        "formatted": "Robert Levins gate 5, 0154\nOSLO\nNO",
        "postal_code": "0154",
        "region": "OSLO",
        "street_address": "Robert Levins gate 5"
    },
    "birthdate": "2000-02-01",
    "family_name": "User",
    "given_name": "Test",
    "name": "Test User",
    "other_addresses": [],
    "phone_number": "4712345678",
    "phone_number_verified": true,
    "sid": "687a31ad9ba1de74",
    "sub": "9fe5d0e3-4702-4113-a154-90bc68063325"
}

Profile sharing with the Recurring API​

The basic steps are the same as for the ePayment API: ask for consent when you draft the agreement, get the sub from the agreement, then get the user info.

Complete Step 1 - Setup and Step 2 - Get an access token first. See the Recurring API quick start for the full agreement flow.

Step 1 - Draft an agreement with a profile scope​

Provide the scope property in the POST:/recurring/v3/agreements call.

curl -X POST https://apitest.vipps.no/recurring/v3/agreements \
-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' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
    "interval": {
        "unit": "WEEK",
        "count": 2
    },
    "pricing": {
        "amount": 1000,
        "currency": "NOK"
    },
    "merchantRedirectUrl": "https://example.com/redirect-url",
    "merchantAgreementUrl": "https://example.com/agreement-url",
    "phoneNumber": "12345678",
    "productName": "Test product",
    "scope": "name phoneNumber address birthDate"
}'

Step 2 - Approve the agreement​

Open the vippsConfirmationUrl link that is returned, and complete the agreement in the app. You must accept the consent card before you can approve the agreement.

Take note of the agreementId.

Step 3 - Get the sub for the agreement​

Call the GET:/recurring/v3/agreements/{agreementId} endpoint and take the sub value from the response.

curl -X GET https://apitest.vipps.no/recurring/v3/agreements/YOUR-AGREEMENT-ID \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \

Step 4 - Get the user info​

Send request GET:/vipps-userinfo-api/userinfo/{sub}, exactly as in Step 6 - Get the user info.

Next steps​

See the Userinfo API guide for more details.

Last updated on