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

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

> **Full site overview:** For an overview of the entire site, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# 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).

## Getting donation payments

### Step 1 - Setup

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

#### Merchants

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.

#### Partners

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 your values.
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.

#### Merchants

#### 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` header 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"`.

#### Partners

#### 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.