Quick start

Before you begin

This document covers the quick steps for getting started with the ePayment API. You must have already signed up as an organization with Vipps MobilePay and have your test credentials from the merchant portal, as described in the Getting started guide.

Important: The examples use standard example values that you must change to use your values. This includes API keys, HTTP headers, reference, etc.

Prerequisites

Step 1 - Setup

curl
Postman

Please note: Postman is discontinuing their offline version. Use only your test keys and delete them after testing. Ensure that your company allows for cloud use before continuing.

If you wish to use Postman, import the following files:

In Postman, tweak the environment with your own values (see API keys):

client_id - Merchant key required for getting the access token.
client_secret - Merchant key required for getting the access token.
Ocp-Apim-Subscription-Key - Merchant subscription key.
merchantSerialNumber - Merchant ID.
MobileNumber - The phone number for the test app profile you have received or registered. This is your test mobile number without country code.

No setup needed :)

Step 2 - Authentication

Get an access_token from the Access token API: POST:/accesstoken/get.

curl
Postman

Send request Get Access Token

curl https://apitest.vipps.no/accessToken/get \
-H "client_id: YOUR-CLIENT-ID" \
-H "client_secret: YOUR-CLIENT-SECRET" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-X POST \
--data ''

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

Merchant Redirect QR

A merchant redirect QR contains a link to your webshop. When the user scans this with their phone, your website will open.

QR code

Generate a merchant redirect QR with: POST:/qr/v1/merchant-redirect.

curl
Postman

Send request Merchant Redirect QR > Generate QR

The qr-id variable is now set in the environment for use with subsequent calls.

Ctrl+click the link to see the QR code. Scanning the QR should open the specified URL on your phone.

The result from this request provides a URL with its own JWT token, which will expire. Get a new token by calling Get QR by id.

curl https://apitest.vipps.no/qr/v1/merchant-redirect \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-H "Idempotency-Key: 49ca711a-acee-4d01-993b-9487112e1def" \
-X POST \
-d '{
    "redirectUrl": "https://example.com/mywebshop",
    "id": "UNIQUE-QR-ID"
}'

Enter the returned link into a browser. It will show the QR code. Scanning the QR should open the specified URL on your phone.

The result from this request provides a URL with its own JWT token, which will expire. Get a new token by calling GET:/qr/v1/merchant-redirect/{qr-id}.

Relevant examples:

One-time payment QR

A one-time payment QR (also called dynamic QR) is connected to a payment. When the user scans this QR with their phone, the Vipps app will open and present them with the payment request.

If you are using the ePayment API in your solution, you do not need to use the QR API. See Dynamic QR directing to the app for payment for an example.

Legacy method for eCom API

Create a payment and get the unique payment reference.

curl
Postman

Send request Initiate Payment

The orderId and vippsLandingPageUrl variables are now in the environment of this Postman example.

curl --location 'https://apitest.vipps.no/ecomm/v2/payments/' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-X POST \
-d '{
  "customerInfo": {
    "mobileNumber": "91234567"
  },
  "merchantInfo": {
    "merchantSerialNumber": "123456",
    "callbackPrefix":"https://example.com/vipps/callbacks-for-payment-update-from-vipps",
    "fallBack": "https://example.com/vipps/fallback-result-page-for-both-success-and-failure/acme-shop-123-order123abc",
  },
  "transaction": {
    "amount": 49900,
    "orderId": "UNIQUE-PAYMENT-REFERENCE",
    "transactionText": "One pair of socks.",
}
}'

Note that orderId must be unique for each payment you create.

Take note of the URL that is returned in the response body and provide it in the POST:/qr/v1 request to generate the one-time payment QR.

curl
Postman

Send request Generate OTP QR

This supplies vippsLandingPageUrl to POST:/qr/v1 to provide a URL that can be used to show a QR code.

Ctrl+click the link to see the QR code. Scanning the QR should open the test app on your phone and allow you to complete the one-time purchase.

curl --location 'https://apitest.vipps.no/qr/v1' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>" \
-H "Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a" \
-H "Merchant-Serial-Number: 123456" \
-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" \
-X POST \
-d '{
    "url": "https://apitest.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJraWQiOiJqd3RrZXkiLCJhbGciOiJSUzI1NiJ<truncated>"
}'

Next steps

See the QR API guide to read about the concepts and details.

Quick start

Before you begin​

Prerequisites​

Step 1 - Setup​

Step 2 - Authentication​

Merchant Redirect QR​

One-time payment QR​

Next steps​