> **Description:** Step-by-step guide to making your first request with the Donations API, covering authentication for both merchants and partners.

# 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`](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](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md#how-to-get-the-api-keys):

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

You will need the following values from your [partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md#partner-keys):

- `client_id` - Client ID from your partner keys.
- `client_secret` - Client secret from your partner 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](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/specialized-authentication.md).

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:

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

**Send the token request:**

To get the token, you will send the [`POST:/miami/v1/token`](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml) request.

Provide the Base64-encoded value in the `Authorization` heading in a request.
For example:

```bash
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](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md)
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:

```json
{
  "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.

**INFO**

When you request an access token with these keys, the response includes `"scope": "donations:read"`.

#### For partners using partner keys

Partners use their partner keys with
[Standard authentication](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/standard-authentication.md).

Example request to
[`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml):

```bash
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](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) for more details.

**NOTE**

When a partner uses
[partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md)
for requests that are not for a specific merchant,
the `Merchant-Serial-Number` can be omitted.

### Step 3 - Get a list of donation payments

Send [`GET:/donations/v1/reports/payments`](https://developer.vippsmobilepay.com/redocusaurus/donations-swagger-id.yaml)
with your access token and a time range.

```bash
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:

```json
{
  "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](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md#payments-report-best-practices) for the full pagination strategy.

## Next steps

- [API guide](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md) -- full reference for all Donations API endpoints, webhooks, and agreements.
- [Report API](https://developer.vippsmobilepay.com/docs/APIs/report-api/README.md) -- use your merchant-level keys to retrieve settlement and ledger data alongside your donations.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).