SDK

Not actively maintained

This SDK is not actively maintained and may not reflect the latest API features. For production integrations, we recommend using the APIs directly. See the API platform overview for available APIs.

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

• Getting authorization
• 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 vipps_mobilepay_sdk on 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).

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 the Vipps or MobilePay app before POST:/epayment/v1/test/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.