SDKs

Our SDKs make it easier to integrate with Vipps MobilePay by providing the following functionality:

Functionality	JavaScript SDK	.Net SDK
Getting authorization	✅	✅
Initiating Checkout sessions	✅	✅
Handling payments	✅	✅
Handling Recurring agreements and charges	✅
Creating callback QRs and redirect QRs	✅
Handling webhooks	✅
Login with Vipps MobilePay	✅
Order Management	✅
Get information about users	✅

Prerequisites

As a prerequisite to using an SDK, you must have signed up as an organization with Vipps MobilePay and have your test credentials from the merchant portal.

Installation

The following steps show how to start using the SDK in an empty project:

JavaScript

The SDK is available on npm and deno.land for use in Deno, Node, or other JavaScript runtimes.

note

If you are using Deno or Bun, all you need is a recent version installed.

If you are using Node:

1. Make sure you have Node.js 20 or newer installed

2. Initialize your project in a new directory (yarn init or npm init).

3. Install the SDK into your project directory:

   npm i @vippsmobilepay/sdk or yarn add @vippsmobilepay/sdk

4. Open your package.json file and add "type": "module".

DotNet

1. Install .NET. For help, see How to install .NET.

2. Initialize your project in a new directory:

   dotnet new console

3. Install the SDK into your project directory:

   dotnet add package vipps.net

Usage

JavaScript

The SDK is packaged as an ECMAScript Module (ESM). Although CommonJS is available, we encourage using ESM. To import the SDK, add the following to your JavaScript or Typescript file.

Deno

import { Client } from "https://deno.land/x/vipps_mobilepay_sdk/mod.ts";

Node

import { Client } from "@vippsmobilepay/sdk";

tip

If you are using Typescript and would like to import the types for the APIs, simply add them to your import statement:

import { Client, CheckoutInitiateSessionRequest }

For a collection of code examples, see the Sample folder on GitHub

DotNet

Import the SDK. For example:

using Vipps.net;
using Vipps.net.Infrastructure;
using Checkout = Vipps.net.Models.Checkout;
using Epayment = Vipps.net.Models.Epayment;

Configuration and authorization

Most SDK methods will require a token. To generate it, use your API keys Remember: Keep the API keys secret.

Functionality	JavaScript SDK	.Net SDK	API
Authentication, Get access token	Client.auth.getToken	Vipps.net.VippsApi	Authorization endpoint

JavaScript

// Create a client
const client = Client({
    merchantSerialNumber,
    subscriptionKey,
    useTestMode: true,
    retryRequests: false,
});

// Get a token
const accessToken = await client.auth.getToken({
    clientId,
    clientSecret,
    subscriptionKey,
});

To run against the test environment, set useTestMode to true (default false).

If you'd like the SDK to not retry failed requests, set retryRequests to false (default true).

DotNet

using Vipps.net;
using Vipps.net.Infrastructure;

var vippsConfigurationOptions = new VippsConfigurationOptions
{
    ClientId = "CLIENT-ID",
    ClientSecret = "CLIENT-SECRET",
    MerchantSerialNumber = "MERCHANT-SERIAL-NUMBER",
    SubscriptionKey = "SUBSCRIPTION-KEY",
    PluginName = "acme-plugin",
    PluginVersion = "1.0",
    UseTestMode = true
};

var vippsApi = new VippsApi(vippsConfigurationOptions)

To run against the test environment, set useTestMode to true (default false).

Update the code samples to use your API Keys (i.e., client_id, client_secret, Ocp-Apim-Subscription-Key, and Merchant-Serial-Number).

Checkout

All Checkout API endpoints are supported. Review the Checkout documentation for details about this flow.

JavaScript

Functionality	JavaScript SDK	API
Create checkout session and get session info	Client.checkout [create, info]	Checkout API endpoints

Checkout code sample:

// Create a checkout session
const checkout = await client.checkout.create(clientId, clientSecret, {
  merchantInfo: {
    callbackUrl: "https://example.com/callbackUrl",
    returnUrl: "https://example.com/page-customer-returns-to-after-success-or-failure-or-cancel",
  },
  transaction: {
    amount: {
      currency: "NOK",
      value: 1000, // This value equals NOK 10,-
    },
    paymentDescription: "One pair of socks.",
  },
});

For checkout usage, the SDK is compatible with backend frameworks (such as Node, Deno, Remix, NextJS, Gatsby, and others). Do not use the SDK together with React, Vue, Svelte, Angular, or other frontend frameworks (except when SSR), as this could expose your API keys. Use the SDK for backend applications only.

Always keep your client keys safe and hide them from the frontend application.

See the Sample folder on GitHub.

DotNet

Functionality	.NET SDK	API
Create checkout session and get session info	Vipps.net.Models.Checkout.InitiateSessionRequest VippsApi.CheckoutService.InitiateSession	Checkout API endpoints

using Checkout = Vipps.net.Models.Checkout;

var checkoutRequest = new Checkout.InitiateSessionRequest
{
    MerchantInfo = new Checkout.PaymentMerchantInfo
    {
        CallbackAuthorizationToken = Guid.NewGuid().ToString(),
        CallbackUrl = "https://example.com/callbacks-for-checkout",
        ReturnUrl = "https://example.com/fallback-result-page",
    },
    Transaction = new Checkout.PaymentTransaction
    {
        Amount = new Checkout.Amount { Currency = "NOK", Value = 10000 },
        PaymentDescription = "Checkout description",
        Reference = Guid.NewGuid().ToString()
    }
};

var checkoutResult = await vippsApi.CheckoutService.InitiateSession(checkoutRequest);

This SDK offers typed request and response classes. These .NET classes might not be up-to-date if you are on the bleeding edge of our APIs, or if you use features that are not generally available.

All request objects have a property called AdditionalProperties. This is a dictionary that, if set, will merge with the request object.

AdditionalProperties example

InitiateSessionRequest initiateSessionRequest = new()
{
    Transaction = new PaymentTransaction()
    {
        Amount = new Amount()
        {
            Currency = "NOK",
            Value = 49000
        },
        PaymentDescription = "Hei"
    },
    AdditionalProperties =
    {
        { "Configuration", new { AcceptedPaymentMethods = new[] { "WALLET", "CARD" } } }
    }
};

All response objects have a property called RawResponse that contains the response in the form of a JSON Object.

RawResponse example:

var response = vippsApi.CheckoutService.InitiateSession(initiateSessionRequest);
var cancellationUrl = response.RawResponse["cancellationUrl"].ToString();

ePayment

All the ePayment API endpoints are supported. Review the ePayment documentation for details about this flow.

JavaScript

Functionality	JavaScript SDK	API
Handle payment states and modifications	Client.payment [cancel, capture, create, forceApprove, history, info, refund]	ePayment API endpoints

// Create a payment
const payment = await client.payment.create(token, {
  amount: {
    currency: "NOK",
    value: 1000, // This value equals 10 NOK
  },
  paymentMethod: { type: "WALLET" },
  customer: { phoneNumber: "4712345678" },
  returnUrl: `https://yourwebsite.com/redirect`,
  userFlow: "WEB_REDIRECT",
  paymentDescription: "One pair of socks",
});

note

Important: All test users must manually approve at least one payment in Vipps or MobilePay app before POST:/epayment/v1/payments/{reference}/approve can be used for that user. If this has not been done, you will get an error. This is because the user needs to be registered as "BankID verified" in the backend, and this happens automatically in the test environment when using the Vipps or MobilePay app, but not with "force approve".

Your implementation will need webhooks to get the status of epayments. See Webhooks for examples.

See the Sample folder on GitHub.

DotNet

Functionality	.Net SDK	API
Handle payment states and modifications	Vipps.net.Models.Epayment.CreatePaymentRequest vippsApi.EpaymentService [CancelPayment``CapturePayment, CreatePayment, ForceApprovePayment, GetPaymentEventLog, GetPayment, RefundPayment]	ePayment API endpoints

using Epayment = Vipps.net.Models.Epayment;

var ePaymentReference = Guid.NewGuid().ToString();

var epaymentRequest = new Epayment.CreatePaymentRequest
{
    Amount = new Epayment.Amount
    {
        Currency = Epayment.Currency.NOK,
        Value = 100 // 100 øre = 1 KR
    },
    PaymentMethod = new Epayment.PaymentMethod { Type = Epayment.PaymentMethodType.WALLET },
    UserFlow = Epayment.CreatePaymentRequestUserFlow.WEB_REDIRECT,
    Reference = ePaymentReference,
    PaymentDescription = "Pair of socks",
    ReturnUrl = "https://example.com/fallback-result-page",
    Customer = new Epayment.Customer { PhoneNumber = CustomerPhoneNumber }
};

var epaymentResult = await vippsApi.EpaymentService.CreatePayment(epaymentRequest);

Console.WriteLine("Open this link and approve the payment:" + epaymentResult.RedirectUrl);

Your implementation will need webhooks to get the status of epayments. See Webhooks API guide for more details.

Recurring

All the Recurring API v3 endpoints are supported. Review the Recurring documentation for details about this flow.

Functionality	JavaScript SDK	API
Recurring: Agreement	Client.recurring.agreement [create, forceAccept, info, list, update]	Recurring API: Agreement endpoints
Recurring: Charges	Client.recurring.charge [cancel, capture, create, info, infoById, list, refund]	Recurring API: Charge endpoints

See the Sample folder on GitHub.

QR

QR API Merchant redirect QR codes and Merchant callback QR codes are supported. Review the QR documentation for details about these flows.

Functionality	JavaScript SDK	API
QR: Merchant redirect QR codes	Client.qr.redirect [create, delete, info, list, update]	QR API: Merchant redirect QR endpoints
QR: Merchant callback QR codes	Client.qr.callback [create,createMobilePayQR, delete, info, list]	QR API: Merchant callback QR endpoints

See the Sample folder on GitHub.

Webhooks

All the Webhooks API v1 endpoints are supported. Review the Webhooks documentation for details about this flow.

Functionality	JavaScript SDK	API
Webhooks	Client.webhook [register, list, delete]	Webhooks API endpoints

See the Sample folder on GitHub.

Login

Review the Login documentation before implementing this flow.

Functionality	JavaScript SDK	API
Login	Client.login.discovery	Login API: OpenID configuration endpoint

See the Sample folder on GitHub.

Order Management

Review the Order Management documentation for details about this flow.

Functionality	JavaScript SDK	API
Manage Orders	Client.order [info, addReceipt, addImage, addCategory]	Order Management endpoint

See the Sample folder on GitHub.

Userinfo

Review the Userinfo documentation for details about this flow.

Functionality	JavaScript SDK	API
Get information about users	Client.user.info	Userinfo endpoint

See the Sample folder on GitHub.

Error handling

Errors, including network failures, misconfiguration, or temporarily unavailable services, may arise. Please try to handle all potential errors thrown by the SDK.

Getting involved

The SDKs are open-source and publicly available. Questions, bug reports, and pull requests are always welcome on GitHub.

• JavaScript SDK GitHub
• .NET SDK GitHub

Help me

If you aren't sure what to do, see the Getting started page.