Back to home

Partnerships and Integrations | Double the Donation

Integrate Double the Donation Into Your Platform

Double the Donation Matching Integration

Online Donations (Required for Online Donation Tools)

This article walks through how to integrate an online donation tool with Double the Donation.

Donation Form

Confirmation Page

Troubleshooting

Page Reload

IMPLEMENTED BEFORE MARCH 2025? Check out our legacy documentation here.

The integration will collect information during the donation process and register that information with Double the Donation after the donation is complete.

Donation Form

Step 1: Include CSS and JavaScript on the page.

Include the following CSS and JavaScript somewhere on the page:

```

```

<script src="https://doublethedonation.com/api/js/ddplugin.js"></script>

<link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />

Step 2: Insert the streamlined search field.

Call this function to load the streamlined search tool in a specified DOM element.

<!--Listing 2-->

doublethedonation.plugin.v2.load_streamlined_search(dom_node, public_key, config);

Arguments

1. dom_node (HTMLElement, required): The HTML element where the streamlined search tool will be rendered.

2. public_key (string, required): Public key for the organization's Double the Donation account.

3. config (object, recommended): A configuration JSON object that may contain the following keys:

on_text_changed (callback function, highly recommended): A callback function triggered on each keystroke as the user types into the search input field. The function receives the current input value as its only argument.
on_company_changed (callback function, highly recommended): A callback function triggered when a company is selected or changed in the search results. The function receives an object representing the selected company as its only argument.
company_name (string, not recommended): Preloads the streamlined search input with the specified company name. We strongly recommend leaving as default/not setting a value, allowing donors to enter their own company name without confusion. See the Page Reloading in the Troubleshooting section below.
dtd_company_id (integer, not recommended): Preloads the streamlined search tool with a company ID from Double the Donation’s database. We strongly recommend leaving as default/not setting a value, allowing donors to enter their own company name without confusion. See the Page Reloading in the Troubleshooting section below.

The streamlined search tool’s data is not submitted to Double the Donation from the donation page. Instead, capture it using the on_text_changed and on_company_changed callbacks and pass it to the confirmation page after the donation form is submitted.

Confirmation Page

Step 1: Include CSS and JavaScript on the page.

Include the following CSS and JavaScript somewhere on the page:

```

```

<script src="https://doublethedonation.com/api/js/ddplugin.js"></script>

<link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />

Step 2: Transfer data to Double the Donation.

Register the donation with Double the Donation using the register_donation JavaScript function that is loaded into the browser in Step 1.

NOTE: You must register ALL donations with Double the Donation, even when "doublethedonation_company_id" and "doublethedonation_entered_text" are not available (e.g. when the donor skipped the streamline search tool on the donation form). More information here.

NOTE ON RECURRING DONATIONS: You must register recurring donations with Double the Donation, broken up into their recurring cadence. For example, if someone chooses to donate $25 a month, you must submit the $25 donation record of that recurring donation to Double the Donation each month. If a donor pledges to give $100 over 4 monthly installments, you must submit the $25 donation record of that donation to Double the Donation each month until complete. More information here.

A sample submission follows:

```
//Listing 2
```

 if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason

  doublethedonation.integrations.core.register_donation({

    "360matchpro_public_key": "XXXXXXXXXXXXXXXX",    // Replace this key with the client's Double the Donation public key.

    "partner_identifier": "XXXXX-123456789",    //  Replace this with your partner identifier. This will be securely provided to you by the Double the Donation Partnerships Team and is NOT the same as your partner API key.

    "campaign": "EY_2017_Fall", // You should use a field that your clients would easily recognize as the donation form or campaign that the gift came from.

    "donation_identifier": "I-YE238388",

```
    "donation_amount": 123.30,
```
```
    "donor_first_name": "John",
```
```
    "donor_last_name": "Doe",
```

    "donor_email": "john@example.com",

```
    "donor_address": {"zip": 30301,
```

                      "city": "Atlanta",

                      "state": "GA",

                      "address1": "8769 Party Central Drive",

                      "address2": "suite 901",

                      "country": "US"},

```
    "donor_phone": "123-456-7890",
```

    "donation_datetime": "2018-12-25T10:15:30-05:00",

```
    "anonymous": "false",
```
```
    "in_memoriam": "false",
```
```
     "athletic": "true",
```
```
     "recurring": "false",  
```

    "doublethedonation_company_id": 50,    // Only needed if the donor used the streamlined search field.

    "doublethedonation_entered_text": "Home Depot"    // Only needed if the donor used the streamlined search field.

```
  });
```
```
 };
```

Reference the Double the Donation Donation Data Schema for guidance.

In most cases, this code may be placed in the JQuery.ready() callback (if using JQuery) or the DomContentLoaded Event, since the code must execute after the ddplugin.js file (Step 1) is fully loaded and executed.

Step 3: Insert and initialize the workplace giving company search plugin.

Call this function to load the plugin in a specified DOM element.

```

```

doublethedonation.plugin.v2.load_plugin(dom_node, public_key, config);

Arguments

1. dom_node (HTMLElement, required): The HTML element where the streamlined search tool will be rendered.

2. public_key (string, required): Public key for the organization's Double the Donation account.

3. config (object, recommended): A configuration JSON object that may contain the following keys:

donation_identifier (string, recommended): A unique identifier for the donation record. This is used to track donor actions on the plugin.
dtd_company_id (integer, optional): Preloads the plugin with a company ID from Double the Donation’s database. Used primarily to load the plugin with the company that was selected on the streamlined search. See on_company_changed in Donation Form -> Step 2 above.
sections (array of strings, optional): An array containing the name of the workplace giving program details you wish to display to the donor. The order of the array determines the rendering order, with the first section listed appearing at the top of the plugin and the next section listed appearing below it, etc. Currently available options: "match" and "volunteer"
prioritize_available_programs (boolean, optional, default=false): Overrides the order in the sections array to prioritize sections with available workplace giving programs. If all sections have available programs, the order in the sections array is preserved. For example: If the sections array is ordered with the "match" section first and the "volunteer" section second, but the company selected does not have a matching gift program and does have a volunteer program, setting "prioritize_available_programs" to "true" will display the volunteer program section first.
size (string, optional): Renders either the "small" or "large" version of the plugin. The "large" version provides more visual design for program details but occupies more space. The "small" version, with more plain-text program details, is recommended for modal-style forms or mobile-first platforms. By default, the plugin is responsive and will load in the most appropriate size for the container. See examples of each display option below.
on_text_changed (callback function, optional): A callback function triggered on each keystroke as the user types into the search input field. The function receives the current input value as its only argument.
on_company_changed (callback function, optional): A callback function triggered when a company is selected or changed in the search results. The function receives an object representing the selected company as its only argument.

If the donor selected a company from the streamlined search field or if the donor email address has a corporate domain that matches a company entity in the Double the Donation database, the matching gift plugin presents matching gift information about that company. If not, the matching gift plugin appears blank and prompts the donor to select their company. The plugin tracks what the donor selects at this stage.

Hint: See code example below for an example of Listings 1-3 in action.

Troubleshooting

Page Reload

We detected input errors on the donation form and refreshed the page. Can we reload the streamlined search tool so that it shows the company that was selected before the donor attempted to submit the payment?

Yes. Pass the search string that the user typed as the company_name property in the config (refer to Donation Form -> Step 2 -> Arguments). If the donor had selected a company, pass the doublethedonation_company_id corresponding to the company selected to the dtd_company_id property in the config.

The search text and doublethedonation_company_id are stored in the browser's localStorage. You can use the following code: JSON.parse(localStorage.doublethedonation || "{}"); to retrieve these values. In the JSON, look for the doublethedonation_entered_text and doublethedonation_company_id properties. These properties will be missing if the donor does not use the streamlined search tool and will be cleared after the donation is registered to avoid overlap with future transactions. If needed, ensure you access this data from localStorage before registering the donation during Confirmation Page -> Step 2.

Plugin Size Examples

Small plugin:

Plugin Small Size

Large plugin:

Plugin Large Size

Code Example

<!DOCTYPE html>
<html lang="en">
<head>
    <script src="/api/js/ddplugin.js"></script>
</head>

<body>
<div>
    <div>
        <div id="plugin"></div>
        <div id="streamlined-search"></div>
    </div>
</div>

<script>
    var public_key = "N2I1ODhjY2UtZTJh";

    function text_changed_callback(entered_text){
        console.log("Entered: " + entered_text);
    };

    function company_selected_callback(company){
        console.log("Company Selected");
        console.log(company);
    };

    // Load streamlined search
    var search_elem = document.getElementById("streamlined-search");
    var search_config = {
            "dtd_company_id": 50,   // Home Depot
            "on_text_changed": text_changed_callback,
            "on_company_changed": company_selected_callback};
    doublethedonation.plugin.v2.load_streamlined_search(search_elem, public_key, search_config);

    // Load plugin
    var plugin_elem = document.getElementById("plugin");
    var plugin_config = {
            "donation_identifier": "id-1",
            "dtd_company_id": 50,   // Home Depot
            "on_text_changed": text_changed_callback,
            "on_company_changed": company_selected_callback,
            "size": "small",
            "sections": ["match", "volunteer"],
            "prioritize_available_programs": true};
    doublethedonation.plugin.v2.load_plugin(plugin_elem, public_key, plugin_config);
</script>

</body>
</html>