API Documentation

Authentication

To authenticate and access the API, include the following header in your requests:

X-API-Key: {your-api-key}

Endpoints

Query Transactions

Use the following endpoint to query transactions:

GET https://api.donationpay.org/v1.0/transactions/

Query Parameters:

  • start_date (optional): Start date of the date range to filter transactions
  • end_date (optional): End date of the date range to filter transactions
  • email (optional): Email address to filter transactions
  • min_amount (optional): Minimum amount of transactions to filter
  • max_amount (optional): Maximum amount of transactions to filter
  • donor_full_name (optional): Full name of the donor to filter transactions
  • donor_last_name (optional): Last name of the donor to filter transactions

Example Request:

GET https://api.donationpay.org/v1.0/transactions/?start_date=2023-01-01&end_date=2023-06-30&email=john@example.com

Example Response:

{
        "data": [
          {
            "id": "abc12345",
            "date": "2023-05-15",
            "request_uri": "/donate",
            "email_address": "john@example.com",
            "transaction_status": "Completed",
            "transaction_amount": 100.0,
            "refund_amount": 0.0,
            "refund_date": null,
            "billing_full_name": "John Doe",
            "billing_name_first": "John",
            "billing_name_last": "Doe",
            "billing_address": "123 Main St",
            "billing_city": "San Francisco",
            "billing_state": "CA",
            "billing_zip_code": "94110",
            "billing_country": "US",
            "custom_fields": [JSON]{
              "field_1": "Custom Value 1",
              "field_2": "Custom Value 2"
            }
          },
          {
            "id": "def67890",
            "date": "2023-04-20",
            "request_uri": "/give",
            "email_address": "jane@example.com",
            "transaction_status": "Refunded",
            "transaction_amount": 50.0,
            "refund_amount": 50.0,
            "refund_date": "2023-04-21",
            "billing_full_name": "Jane Smith",
            "billing_name_first": "Jane",
            "billing_name_last": "Smith",
            "billing_address": "456 Oak St",
            "billing_city": "Berkeley",
            "billing_state": "CA",
            "billing_zip_code": "94707",
            "billing_country": "US",
            "custom_fields": [JSON]{
              "field_1": "Custom Value A",
              "field_2": "Custom Value B"
            }
          }
        ]
      }

Code Examples

cURL

curl -X GET -H "X-API-Key: {your-api-key}" https://api.donationpay.org/v1.0/transactions/

PHP

<?php
            $url = "https://api.donationpay.org/v1.0/transactions/";

            $options = array(
                'http' => array(
                    'header' => "X-API-Key: {your-api-key}",
                    'method' => 'GET'
                )
            );

            $context = stream_context_create($options);
            $response = file_get_contents($url, false, $context);

            if ($response === false) {
                // Handle error
            } else {
                $data = json_decode($response, true);
                // Handle response
            }
            ?>

Ruby

require 'net/http'
            require 'json'

            url = URI.parse('https://api.donationpay.org/v1.0/transactions/')
            req = Net::HTTP::Get.new(url.path)
            req['X-API-Key'] = '{your-api-key}'

            res = Net::HTTP.start(url.host, url.port) do |http|
              http.request(req)
            end

            if res.is_a?(Net::HTTPSuccess)
              data = JSON.parse(res.body)
              # Handle response
            else
              # Handle error
            end

Python

import requests

            url = 'https://api.donationpay.org/v1.0/transactions/'
            headers = {
                'X-API-Key': '{your-api-key}'
            }

            response = requests.get(url, headers=headers)

            if response.status_code == 200:
                data = response.json()
                # Handle response
            else:
                # Handle error

Java

import java.net.HttpURLConnection;
            import java.net.URL;
            import java.io.BufferedReader;
            import java.io.InputStreamReader;

            public class APIClient {
                public static void main(String[] args) {
                    try {
                        URL url = new URL("https://api.donationpay.org/v1.0/transactions/");
                        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
                        connection.setRequestMethod("GET");
                        connection.setRequestProperty("X-API-Key", "{your-api-key}");

                        int responseCode = connection.getResponseCode();

                        if (responseCode == HttpURLConnection.HTTP_OK) {
                            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
                            String inputLine;
                            StringBuilder response = new StringBuilder();

                            while ((inputLine = in.readLine()) != null) {
                                response.append(inputLine);
                            }
                            in.close();

                            String responseData = response.toString();
                            // Handle response
                        } else {
                            // Handle error
                        }
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }
            }

Payment Pages

Use the following endpoints to retrieve a list of payment pages or details of a specific payment page:

Endpoints:
  • List All Payment Pages
    GET https://api.donationpay.org/v1.0/pages
  • Get a Specific Payment Page
    GET https://api.donationpay.org/v1.0/pages?page_id={page_id}
Headers:
Header Description
X-API-Key Your unique API key (required)
Query Parameters:
Parameter Description
page_id The unique ID of the payment page (optional). If provided, the response will return details for this specific page.
Example Requests:

1. List All Payment Pages

GET https://api.donationpay.org/v1.0/pages/

2. Get a Specific Payment Page

GET https://api.donationpay.org/v1.0/pages?page_id=abcd1234
Example Responses:

1. List All Payment Pages

{
        "data": [
            {
                "id": "abcd1234",
                "name": "Donation Page 1",
                "path": "donation-page-1",
                "title": "Support Our Cause",
                "created": "2024-11-01T12:00:00Z",
                "active": true
            },
            {
                "id": "efgh5678",
                "name": "Donation Page 2",
                "path": "donation-page-2",
                "title": "Help the Community",
                "created": "2024-11-05T14:30:00Z",
                "active": true
            }
        ]
    }

2. Get a Specific Payment Page

{
        "data": {
            "id": "abcd1234",
            "name": "Donation Page 1",
            "path": "donation-page-1",
            "title": "Support Our Cause",
            "active": true,
            "template_settings": {
                // Template-specific configurations
            },
            "minimum_amount": 10.00,
            "giving_option_settings": {
                // Settings for giving options
            },
            "amount_options": [
                {
                    "label": "$25",
                    "value": 25
                },
                {
                    "label": "$50",
                    "value": 50
                }
            ],
            "custom_fields": [
                {
                    "field_name": "Your Name",
                    "field_type": "text"
                },
                {
                    "field_name": "Your Message",
                    "field_type": "textarea"
                }
            ],
            "text_above_form": "

Thank you for considering a donation!

", "text_below_form": "

Your support means the world to us.

", "cc_submit_text": "Donate with Credit Card", "ach_submit_text": "Donate via ACH", "headline": "Make a Difference Today", "receipt_settings": { // Receipt-related settings }, "donor_info_settings": { "phone": true, "email": true }, "multiple_amount_selector_settings": { // Settings for amount selectors }, "upsell_settings": { // Upsell configurations } } }
Error Responses:

1. Invalid API Key

{
        "error": "Invalid API key"
    }

2. Page Not Found

{
        "error": "Payment page not found"
    }

3. Invalid Endpoint

{
        "error": "Invalid endpoint"
    }

4. Method Not Allowed

{
        "error": "Method not allowed"
    }
Field Descriptions:
Field Description
id The unique public ID of the payment page.
name The name of the payment page.
path The URL path for the payment page.
title The title of the payment page.
created The creation timestamp of the payment page.
active Indicates whether the payment page is active.
template_settings JSON object containing template-related settings.
minimum_amount The minimum donation amount allowed.
giving_option_settings JSON object for giving option configurations.
amount_options Array of available donation amounts with their labels and values.
custom_fields Array of custom fields to collect additional information.
text_above_form HTML content displayed above the payment form.
text_below_form HTML content displayed below the payment form.
cc_submit_text The text displayed on the Credit Card submit button.
ach_submit_text The text displayed on the ACH submit button.
headline The headline text displayed on the payment page.
receipt_settings JSON object containing receipt configurations (subject, body, etc.).
donor_info_settings JSON object for donor information collection settings (e.g., phone, email).
multiple_amount_selector_settings JSON object for configuring multiple amount selectors.
upsell_settings JSON object for upsell configurations.

Payouts

Use the following endpoint to retrieve payout details or a list of recent payouts:

GET Payout List

Fetch a list of recent payouts (up to 100) for the account associated with the provided API key:

GET https://api.donationpay.org/v1.0/payouts/

Example Response:

{
          "data": [
            {
              "ID": "po_1JsLfD2eZvKYlo2CvDL8EB0z",
              "Amount": 1000,
              "Arrival Date": "2023-08-15",
              "Method": "standard",
              "Statement Descriptor": "Donation Payout"
            },
            {
              "ID": "po_1JsLgE2eZvKYlo2CdDL8FB2f",
              "Amount": 2500,
              "Arrival Date": "2023-08-14",
              "Method": "standard",
              "Statement Descriptor": "Donation Payout"
            }
          ]
        }

GET Specific Payout

Use the following endpoint to retrieve the details of a specific payout by its payout ID:

GET https://api.donationpay.org/v1.0/payouts/?payout_id={payout_id}

Query Parameters:

  • payout_id (required): The ID of the specific payout to retrieve details.

Example Request:

GET https://api.donationpay.org/v1.0/payouts/?payout_id=po_1JsLfD2eZvKYlo2CvDL8EB0z

Example Response:

{
          "data": [
            {
              "Amount": 100.00,
              "Fee": 3.00,
              "Name": "John Doe",
              "Email": "john@example.com",
              "Address": {
                "line1": "123 Main St",
                "city": "San Francisco",
                "state": "CA",
                "postal_code": "94110",
                "country": "US"
              }
            },
            {
              "Amount": 250.00,
              "Fee": 7.50,
              "Name": "Jane Doe",
              "Email": "jane@example.com",
              "Address": {
                "line1": "456 Oak St",
                "city": "Berkeley",
                "state": "CA",
                "postal_code": "94707",
                "country": "US"
              }
            }
          ]
        }

Error Responses

If an error occurs, the following response structure is returned:

{
          "error": "Error message describing the issue"
        }

Support

This API documentation provides an overview of the available endpoints, authentication requirements, and sample code examples in different programming languages. Use the provided examples to integrate with the DonationPay API and retrieve transaction and payment page information. For questions, please contact your account representative or email support@donationpay.org.