Quick start

Before you begin

Please note: The Report API is not available in the test environment. See Limitations of the test environment.

Be aware that the API requests mentioned here are running on the production server, https://api.vipps.no.

🔥 To reduce the risk of exposure, never store production API keys in Postman or any similar tools. 🔥

The provided example values in this guide must be changed with the values for your sales unit and user. This applies for API keys, HTTP headers, reference, phone number, etc.

Python example

We have made a simple example of how to use the Report API in a Python script: Python example.

Getting your ledgers

Step 1 - Setup

You must have already signed up as an organization with Vipps MobilePay and have your API keys. See Getting started guide for help.

Get these API key values for your sales unit:

• client_id - client_id for a sales unit.
• client_secret - Client secret for a sales unit.
• Ocp-Apim-Subscription-Key - Subscription key for a sales unit (not required for accounting partners).
• Merchant-Serial-Number - The unique ID for a sales unit (optional but helpful for troubleshooting).

See How to find the API keys.

Step 2 - Get an access token

All the API endpoints require that you first obtain an API token.

It's possible to authenticate both as a merchant and as an accounting partner.

Merchants

For merchants using their API keys

Merchants use the API keys for each of their sales units with the Access Token API: Access token endpoint.

Example request to POST:/accesstoken/get:

curl -X POST 'https://api.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' \
-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' \
--data ''

Replace the value of the Vipps-System headers with your own values. See HTTP headers for more details.

note

When a partner uses partner keys for requests that are not for a specific merchant, the Merchant-Serial-Number can be omitted.

Accounting partners

For accounting partners using accounting keys

Accounting partners use accounting keys with the Specialized authentication.

The value for authorization is a string representing your Base64-encoded accounting keys, client_id and client_secret.

How to convert your keys to Base64:

Example of how to convert your client_id and client_secret to base64 with JavaScript:

const clientId = 'YOUR-CLIENT-ID';
const clientSecret = 'YOUR-CLIENT-SECRET';
const base64Credentials = btoa(`${clientId}:${clientSecret}`);
console.log(base64Credentials);

Send the API request:

Provide the Base64-encoded value in the Authorization heading in a request to POST:/miami/v1/token:

curl -X POST https://api.vipps.no/miami/v1/token \
-H 'Authorization: Basic <YOUR-BASE64-ENCODED-VALUE>' \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
-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' \
--data-urlencode 'grant_type=client_credentials'

warning

You must include the last line with 'grant_type=client_credentials', or you'll get an invalid_client error.

The Ocp-Apim-Subscription-Key HTTP header should not be sent.

It's a good idea to include the standard HTTP headers in your requests (e.g., Vipps-System-Name, Vipps-System-Version), because these will help us to debug the problem, if you have one.

An access token will be returned. For example:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>",
  "token_type": "Bearer",
  "expires_in": 900
}

This is your identity in API requests. You can use this in API requests until it expires, in 15 minutes.

Step 3 - Get all ledgers

Send GET:/settlement/v1/ledgers to get the ledgers you have access to.

curl -X GET https://api.vipps.no/settlement/v1/ledgers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

Step 4 - Get a funds ledger

Send GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate} for a list of payments/transactions.

Set:

• topic to funds.
• ledgerId to the 6-digit value that is the unique ledger ID for the ledger you want.
• ledgerDate to a value in format YYYY-MM-DD (e.g., 2023-12-31).

curl -X GET https://api.vipps.no/report/v2/ledgers/{ledgerId}/funds/dates/{ledgerDate} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

Step 5 - Get a fees ledger

Send GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate} for a list of payments/transactions.

Set:

• topic to fees.
• ledgerId to the 6-digit value that is the unique ledger ID for the ledger you want.
• ledgerDate to a value in format YYYY-MM-DD (e.g., 2023-12-31).

curl -X GET https://api.vipps.no/report/v2/ledgers/{ledgerId}/fees/dates/{ledgerDate} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

Step 6 - Get a continuous feed of data (optional)

If you want to continuously stream data as it becomes available, use the GET:/report/v2/ledgers/{ledgerId}/{topic}/feed endpoint without specifying a ledgerDate.

Set the following:

• Set topic to funds or fees, for the type of ledger you require.
• Set ledgerId to the unique ledger ID for the ledger you want.

curl -X GET https://api.vipps.no/report/v2/ledgers/{ledgerId}/{topic}/feed \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \

See: FAQ: Can I get real-time data?

Next steps

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