Skip to main content

Quick start

Before you begin​

Production only

The Donations API is not available in the test environment. All requests in this guide use the production server, https://api.vipps.no.

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

Getting donation payments​

Step 1 - Setup​

You must have already been approved for the Donations product with Vipps MobilePay.

You will need the following values from your merchant-level keys:

  • client_id - Client ID from your merchant-level keys.
  • client_secret - Client secret from your merchant-level keys.

The example values in this guide must be replaced with the values for your sales unit and user. This applies to API keys, HTTP headers, references, and similar values.

Step 2 - Get an access token​

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

For merchants using merchant-level keys​

Merchants use their merchant-level keys with Specialized authentication.

The value for authorization is a string representing your Base64-encoded API 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 a list of donation payments​

Send GET:/donations/v1/reports/payments with your access token and a time range.

curl -X GET 'https://api.vipps.no/donations/v1/reports/payments?from=2025-01-01T00:00:00Z&to=2025-12-31T23:59:59Z' \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN"

A successful response includes a payments array with all donation payments in the given period:

{
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-12-31T23:59:59Z",
  "payments": [
    {
      "externalReference": "spring-promotion-2025",
      "agreementId": "79458f91-82b5-4c38-a886-56df6a6b7980",
      "payer": {
        "name": "Ada Lovelace",
        "phoneNumber": "4712345678"
      },
      "capturedAt": "2025-10-24T14:15:22Z",
      "pspReference": "11268125611",
      "transactionReference": "11268125611",
      "recipientHandle": "api:922061",
      "amount": "50001",
      "currency": "NOK"
    }
  ]
}

If the response contains payments, use the latest capturedAt timestamp as the from parameter in your next request to page through all available data. See Payments report best practices for the full pagination strategy.

Next steps​

  • API guide — full reference for all Donations API endpoints, webhooks, and agreements.
  • Report API — use your merchant-level keys to retrieve settlement and ledger data alongside your donations.
Last updated on