Skip to main content

Donations API guide

The Donations API supplements our donations products, allowing integrators to customize the user journey after a donation has been made. All endpoints in this API only have data regarding donations made with our single donations or recurring donations solutions.

The Donations API is in early stages of development.

Note

The Donations API is not available in the test environment.

Getting started with the Donations API

The Donations API provides data for both single and recurring donations. However, only the Recurring Donations product provides API keys, so it is necessary to have recurring donations in order to use the API, even if you are only using it to get data from single donations.

For more details on how to get started and how the product works, see Donations on vippsmobilepay.com

Integrating​

note

Only keys belonging to recurring donations sales units work with the Donations API

Authentication: The Donations API uses Standard Auth and does not work with partner keys.

Endpoints​

These endpoints are available now (or very soon):

EndpointDescription
GET:/donations/v1/reports/paymentsGet a list of all single and recurring donations made to a merchant in a given interval

Payments report best practices​

The payments report endpoint (GET:/donations/v1/reports/payments) is designed to retrieve donation data, but due to performance considerations, there are important 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 every 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.
  1. Start with your desired time range: Set both from and to parameters for your initial request
  2. Process the response: Handle all payments returned in the response
  3. Check for more data: If the response contains payments, use the latest capturedAt timestamp as the new from parameter
  4. 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
Last updated on