Donations API guide

Once you have access to the Donations product, you can use this API to pull donation payment reports and receive real-time webhook notifications about agreement changes.

Integration steps

Get your merchant level keys
Request an access token
Send requests to Donations API endpoints

Note

The Donations API is not available in the test environment. See Limitations of the test environment.

1. Get your merchant level keys

For the Donations API, you use a merchant level API client. This is an identity that lets us identify that a given request is coming from your organization. If you have integrated to other Vipps MobilePay APIs this differs a little as the other API clients identify you on a Sales Unit Level.

The API client will be able to retrieve tokens that can be used when making requests toward the donations API. You will be asked to give your client a name and a Client ID and a Client Secret will be generated.

Use these merchant level keys when you request an access token.

How to get the merchant level keys

This is a bit different from the other API keys in our platform. You generate the API client from the Donations tab on the developer pages found at portal.vippsmobilepay.com. The tab will only be visible once you have been approved for the Donations product.

Click For developers in the left sidebar.
Select the Donations tab.
Click Generate.
On the page that follows, you'll see the credentials. Take a copy of your credentials and store in a safe place.

We don't store the secret.
If you lose your secret, you'll need to generate a new one by clicking Regenerate client secret in the same dialog. The regenerated credentials will be displayed.

Your old secret will stop working immediately, so you'll need to update it in your system.

2. Request an access token

All requests towards the Donations API must include an Authorization header with a JSON Web Token (JWT), which we call the access token. The Access Token API allows you to get this token.

To request an access token:

Encode your merchant level keys (see Get your API client)
Send the token request

This is based on Specialized authentication.

note

If you have integrated earlier, and you're using the keys from a Recurring donations sales unit, then you will follow the Standard authentication.

2.1. Encode your merchant level keys

The token endpoint uses basic auth. The value used for the authorization header is a string representing your Base64-encoded merchant-level client-secret pair, client_id:client_secret.

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);

2.2. Send the token request

To get the token, you will send the POST:/miami/v1/token request.

In the header, include:

Authorization header with your base 64 encoded value from the previous step.

In the body, include:

grant_type=client_credentials

For example:

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' \
--data-urlencode 'grant_type=client_credentials' \

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.

If the request is successful, you'll get a response with the access token. For example:

{
    "access_token": "eyJ0eXAiOiJhdFx1MDAyQmp3dC<truncated>",
    "token_type": "Bearer",
    "expires_in": 900,
    "scope": "donations:read"
}

3. Send requests to Donations API endpoints

Use the above access token in the header of the Donations API endpoints. For example:

curl -X GET https://api.vipps.no/donations/v1/<endpoint params>
-H "Authorization: Bearer eyJ0eXAiOiJhdFx1MDAyQmp3dC<truncated>"

See list of endpoints and examples below.

Endpoints

The following endpoints are available:

Endpoint	Description
`GET:/donations/v1/reports/payments`	Get a list of all single and recurring donations made to a merchant in a given interval
`GET:/donations/v1/agreements/{agreementId}`	Get detailed information about a specific agreement

Get a list of donations payments

You can use the Get payments endpoint, GET:/donations/v1/reports/payments, to get a list of all your donation payments. The response will contain an array of payment objects that you can handle with your application.

Send the API request GET:/donations/v1/reports/payments. Include your access token and the to and from headers to specify the time interval for which you want to retrieve payments.

For example:

curl -X GET https://api.vipps.no/donations/v1/reports/payments?from=2025-10-08T06:01:09.1234567Z&to=2030-06-30T23:59:59.9999999Z
-H "Authorization: Bearer YOUR-ACCESS-TOKEN"

A successful response will include the date range and a payments array. The payments array will contain entries for all payments marked as donations in our system. Each payment object will include information such as payer, amount, currency and the time it was captured.

For example:

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

Payments report best practices

The payments report endpoint (GET:/donations/v1/reports/payments) is designed to retrieve donation data. For performance considerations there are some best practices to follow when using this endpoint.

Batching

The payment report endpoint uses a batch strategy based on timestamps, this approach ensures efficient data retrieval while maintaining performance.

Key concepts

Data update frequency: There is no need to poll for new data more often than once a minute.
Payload Size Limits: The API has built-in limits on response payload size for performance reasons
No Guarantee of Complete Intervals: You are not guaranteed to receive all payments within a given time interval in a single request
Timestamp-Based Pagination: Use the latest timestamp from the previous response as the from parameter for the next request
Dynamic Payload Size: The number of payment entries returned in each response may vary and is subject to change. Do not implement logic that depends on a specific number of payments per response.

Recommended implementation strategy

Start with your desired time range: Set both from and to parameters for your initial request
Process the response: Handle all payments returned in the response
Check for more data: If the response contains payments, use the latest capturedAt timestamp as the new from parameter
Continue pagination: Make subsequent requests with the updated from parameter until you receive an empty response

Important considerations

Timestamp Precision: Always use the exact capturedAt timestamp from the response to avoid missing payments
Duplicate Handling: Implement logic to handle duplicate payments that may appear across different payloads, the last payment of the previous payload will be included if using the exact timestamp
Empty Responses: An empty payments array indicates no more data is available for the given time range

Webhooks integration

You can receive instant notifications about important events, such as when donation agreements are started or stopped. To set up the webhooks, you need to register your receiving webhook URL as described in the Webhooks API guide. We'll send real-time notifications about donation agreement events to the URL you specify.

Agreement webhook events

Webhook event types for donation agreements:

Event type	Description
`donations.agreement.started.v1`	Donation agreement has been started
`donations.agreement.stopped.v1`	Donation agreement has been stopped
`donations.agreement.withdrawal-day-changed.v1`	Donation agreement withdrawal day has been changed
`donations.agreement.amount-changed.v1`	Donation agreement amount has been changed

Create a webhook

Register to get a webhook when a donation agreement is started, stopped, or when its amount or withdrawal day is changed.

For the callback URL, use your webhook server address.

curl -X POST https://api.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Content-Type: application/json" \
--data '{
    "url": "YOUR-CALLBACK-URL",
    "events": ["donations.agreement.started.v1"]
}'

You will receive a response similar to this, confirming that the webhook registration was successful:

{
   "id":"497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "secret":"090a478d-37ff-4e77-970e-d457aeb26a3a"
}

Agreement webhook payloads

Started event payload

When a donation agreement is started, you will receive the following payload:

Field name	Type	Description	Example
`agreementId`	string	ID of the donation agreement	`2518f497-bfad-43a6-8914-fd0168a6c221`
`startedAt`	ISO 8601 UTC date	When the agreement was started	`2026-01-31T17:26:50.8789251+00:00`

Example payload:

{
  "agreementId": "2518f497-bfad-43a6-8914-fd0168a6c221",
  "startedAt": "2026-01-31T17:26:50.8789251+00:00"
}

Stopped event payload

When a donation agreement is stopped, you will receive the following payload:

Field name	Type	Description	Example
`agreementId`	string	ID of the donation agreement	`2518f497-bfad-43a6-8914-fd0168a6c221`
`stoppedAt`	ISO 8601 UTC date	When the agreement was stopped	`2026-01-31T17:26:50.8789251+00:00`

Example payload:

{
  "agreementId": "2518f497-bfad-43a6-8914-fd0168a6c221",
  "stoppedAt": "2026-01-31T17:26:50.8789251+00:00"
}

Withdrawal day changed event payload

When the withdrawal day of a donation agreement is changed, you will receive the following payload:

Field name	Type	Description	Example
`agreementId`	string	ID of the donation agreement	`34580d79-0628-4ed5-bb0a-75a6f2a6fae1`
`changedAt`	ISO 8601 UTC date	When the withdrawal day was changed	`2026-02-15T17:00:22.1234567Z`
`withdrawalDay`	integer	New withdrawal day (1–28)	`12`
`nextPeriodKey`	string (optional)	Billing period key for the next withdrawal. Format: `YYYY-MM` (e.g. March 2026 is `2026-03`). Omitted or null when the next billing period is not yet determined (e.g. before the first schedule has been initialized).	`2026-03`

Example payload (when next period is known):

{
  "agreementId": "34580d79-0628-4ed5-bb0a-75a6f2a6fae1",
  "changedAt": "2026-02-15T17:00:22.1234567Z",
  "withdrawalDay": 12,
  "nextPeriodKey": "2026-03"
}

When the next billing period is not yet determined, nextPeriodKey may be omitted or null.

Amount changed event payload

When the amount of a donation agreement is changed, you will receive the following payload:

Field name	Type	Description	Example
`agreementId`	string	ID of the donation agreement	`34580d79-0628-4ed5-bb0a-75a6f2a6fae1`
`changedAt`	ISO 8601 UTC date	When the amount was changed	`2026-02-15T17:00:22.1234567Z`
`amount`	object	New amount	See below
`amount.value`	integer	Amount in minor units (e.g. øre/cents)	`20000`
`amount.currency`	string	ISO 4217 currency code	`DKK`

Example payload:

{
  "agreementId": "34580d79-0628-4ed5-bb0a-75a6f2a6fae1",
  "changedAt": "2026-02-15T17:00:22.1234567Z",
  "amount": {
    "value": 20000,
    "currency": "DKK"
  }
}

Get agreement details

After receiving a webhook notification about a new agreement, you can retrieve detailed information about the donation agreement using the agreement endpoint.

Send the API request GET:/donations/v1/agreements/{agreementId} with your access token.

For example:

curl -X GET https://api.vipps.no/donations/v1/agreements/2518f497-bfad-43a6-8914-fd0168a6c221
-H "Authorization: Bearer YOUR-ACCESS-TOKEN"

A successful response will include comprehensive details about the donation agreement, including payer information, schedule, and amount.

For example:

{
  "id": "2518f497-bfad-43a6-8914-fd0168a6c221",
  "recipientHandle": "NO:6666",
  "startedAt": "2026-01-31T17:26:50.8789251+00:00",
  "schedule": {
    "interval": "MONTHLY",
    "withdrawalDay": 10
  },
  "amount": {
    "currency": "NOK",
    "value": 2300
  },
  "payer": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "phoneNumber": "4712345678",
    "address": {
      "country": "NO",
      "city": "Oslo",
      "postalCode": "0154",
      "addressLine1": "Robert Levins gate 5"
    },
    "email": "user@example.com",
    "emailVerified": true
  }
}

For more details, see the spec GET:/donations/v1/agreements/{agreementId}.

For more details about webhooks, see the Webhooks API guide.

Integration steps​

1. Get your merchant level keys​

How to get the merchant level keys​

2. Request an access token​

2.1. Encode your merchant level keys​

2.2. Send the token request​

3. Send requests to Donations API endpoints​

Endpoints​

Get a list of donations payments​

Payments report best practices​

Batching​

Key concepts​

Recommended implementation strategy​

Important considerations​

Webhooks integration​

Agreement webhook events​

Create a webhook​

Agreement webhook payloads​

Started event payload​

Stopped event payload​

Withdrawal day changed event payload​

Amount changed event payload​

Get agreement details​

Integration steps

1. Get your merchant level keys

How to get the merchant level keys

2. Request an access token

2.1. Encode your merchant level keys

2.2. Send the token request

3. Send requests to Donations API endpoints

Endpoints

Get a list of donations payments

Payments report best practices

Batching

Key concepts

Recommended implementation strategy

Important considerations

Webhooks integration

Agreement webhook events

Create a webhook

Agreement webhook payloads

Started event payload

Stopped event payload

Withdrawal day changed event payload

Amount changed event payload

Get agreement details