SDK

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

• Getting authorization
• Initiating Checkout sessions
• Creating and managing payments
• Creating and managing Recurring payments
• Working with webhooks

Prerequisites

As a prerequisite to using the SDK, you must have signed up as an organization with Vipps MobilePay and have gotten all the prerequisites for accessing the test environment.

Installation

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

The SDK is available on npm and deno.land for use in Deno, Bun, 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".

Usage

The SDK is packaged as an ECMAScript Module (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, type CreatePaymentRequest }

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

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	API
Authentication, Get access token	Client.auth.getToken	Authorization endpoint

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

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

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

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.

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.

ePayment

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

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

To manually approve a payment, send your test user a payment request through the API or SDK. Open the Merchant Test app. You may need to refresh it by swiping down on the screen. Then, you should see the payment request screen. Approve the payment.

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

See the Sample folder on GitHub.

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.

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.

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 SDK is open-source and publicly available. Questions, bug reports, and pull requests are always welcome on GitHub.

• JavaScript SDK GitHub