Double the Donation Matching Integration
      Back to home
      1. Partnerships and Integrations | Double the Donation
      2. Integrate Double the Donation Into Your Platform
      3. Double the Donation Matching Integration

      Additional Integration Customization (Optional for Relevant Platforms)

      This article walks through optional, advanced integration customization options.

      Condensed Matching Gift Plugin

      Promise Creation

      Custom Fields

      Company ID from Donor Email

       

      The following integration documentation is optional and typically reserved for versions 2 and higher of integrations. It is highly recommended to launch your Double the Donation integration partnership with a standard V1 as described in this documentation for online donation forms and this documentation for CRMs.

       

      Please discuss the following optional advanced integration development with the Double the Donation Partnerships Team before beginning work.

      Condensed Matching Gift Plugin

      Some donation form styles have less space on the confirmation page than the standard Double the Donation matching gift plugin requires. In these cases, the partner may use a condensed version of the matching gift plugin to better fit their confirmation pages.

       

      To use the condensed matching gift plugin, add the following code to line 5 the standard matching gift plugin code ( Step 3 here):

       

      1. var DDCONF = {API_KEY: "360MATCHPRO_PUBLIC_KEY", CONDENSED: true, COMPANY: dtd_selected_company};

       

      The condensed matching gift plugin will appear as follows:

       

       

      Contact the Partnerships Team for a full demo of the condensed plugin.

      Promise Creation

      Do not implement Promise Creation unless you have discussed creating matching gift records in your platform with the Double the Donation Partnerships Team.

       

      Call the get_updated_donations endpoint. We recommend calling this endpoint at least every 24 hours, if not more frequently.

       

      If a promise should be created, you will see the following (example):

       

      1. {
      2.         ...
      3.         "promise_amount": 100,
      4.         "promise_created_at": "2021-09-15T17:37:42.09607Z",
      5.         ...
      6.     }

       

      If a promise should NOT be created, you will see the following:

       

      1. {
      2.         ...
      3.         "promise_amount": null,
      4.         "promise_created_at": null,
      5.         ...
      6.     }

       

      Promise definitions:

      1. promise_amount: The amount of the matching gift 360MatchPro anticipates the client will receive. This could be different from the original donation amount for several reasons, most commonly because the company program matches 2:1 (e.g., the original gift of $100 is matched by the company at $200).

      2. promise_created_at: Timestamp of the event that triggered the promise creation. In 360MatchPro, this is the donation moving into one of the statuses indicated by the client in their settings.

       

      Promise Creation notes:

      1. Each individual Double the Donation client determines in their own account the business logic surrounding promise creation. Specifically, they select which matching gift statuses trigger the creation of a promise.

      2. It is highly likely that you will receive multiple promise updates for the same donation since the business logic that triggers a promise creation update is based upon statuses, which change multiple times over the course of the Double the Donation timeline. Prioritize the promised amount in the update with the most recent timestamp.

      3. Promise amounts are editable from the Double the Donation user interface. If you receive a "promise_amount" of 0 instead of null, that means the promised amount was manually updated to 0 by the Double the Donation client. Discuss what to do in this scenario with the Double the Donation Partnerships Team during your integration build. Our most frequent recommendation is to delete the promise record in your system in this scenario.

      Custom Fields

      Add the custom_fields value to the register_donation API call or JavaScript function ( Step 2 here for online donation forms;  here for CRMs; schema here; Swagger here).

       

      Use the following syntax:

       

      1. {
      2.         ...
      3.         "custom_fields": {
      4.             "CustomField1Label": "custom field 1 value",
      5.            "CustomField2Label": "custom field 2 value"
      6.         }
      7.         ...
      8.     }

       

      Note that in this documentation, we use "label" to refer to the name of the field being collected, which will be the same for all donations, and "value" to refer to the particular value passed in for that field for an individual donation. For instance, "donor_email" is the label and " test@test.com " is the value.

       

      A sample request follows (custom fields in lines 12-14):

       

      1. {
      2.         "360matchpro_public_key": "xxxxxxxx",
      3.         "campaign": campaign,
      4.         "donation_identifier": donation_uuid,
      5.         "donation_amount": "$123.30",
      6.         "donor_first_name": "test1",
      7.         "donor_last_name": "test2",
      8.         "donor_email": "test@doublethedonation.com",
      9.         "donor_phone": "404-1231234",
      10.         "doublethedonation_company_name_input": null,
      11.         "doublethedonation_company_id": 245,
      12.         "custom_fields": {
      13.             "Salutation": "Mr",
      14.             "Division": "Advancement"
      15.         }
      16.     }

       

      In the above sample request, the custom fields are Salutation (line 13) and Division (line 14), and the values captured for those fields are "Mr" for "Salutation" and "Advancement" for "Division".

       

      Notes about custom fields:

      1. There is no character limit or restriction to the values that can be collected in a custom field.

      2. Only one level of custom fields can be entered - values cannot be nested into more levels. For example, "custom_fields": {"level1": {"level2": "level2value"}} would not work.

       

      Custom fields in the 360MatchPro client portal:

      1. Custom fields can be displayed as columns within the "Donations" tab of the 360MatchPro client portal.  Custom fields cannot be filtered for, searched, or sorted in the "Donations" tab of the portal as of now.

      2. Custom fields can be used as variables within Double the Donation automated emails. They will appear in the list with other default variables with the label provided when the value is passed into 360MatchPro via the register_donation endpoint. For instance, in the above sample request, "Salutation" and "Division" would appear as variables available for use in automated emails, and an automated email to the sample donor would populate "Mr" and "Advancement" for those variables. More about email variables here.

      3. Custom fields will appear in CSV exports from Double the Donation and in the API endpoints when fetching donation data.

      4. Custom fields can be used for inclusions and exclusions. More about inclusions/exclusions here.

      Company ID from Donor Email

      Do not implement Company ID from Donor Email unless you have discussed this approach with the Double the Donation Partnerships Team. This endpoint is not applicable to almost all partners.

       

      In rare cases, integration partners do not have access to the original unique transaction ID of a donation. In these cases, these partners can provide a donor's email address and receive Double the Donation's best guess at that donor's company.

       

      Call the donor-info-by-donor-email endpoint. Provide the donor's email address, the nonprofit client's private API key, and a timeframe you would like Double the Donation to check for employment information. Based on industry standards, we recommend defaulting to a timeframe of the previous 6 months.

         

        Responses from the endpoint include:

        1. Company ID: If Double the Donation discovers a company associated with the email address within the timeframe, the endpoint will return a company ID. You may use this company ID to call other endpoints, including the companies/{company_ID} endpoint, for more information about the company's matching gift program.

        2. Error: Email blacklisted in 360MatchPro: The donor's email is on the nonprofit client's blacklist.

        3. Error: Unknown company: The donor's employer is unknown.

        4. Error: Ineligible for matching gifts: The donor is ineligible for matching gifts.

        5. Error: Email not found in 360MatchPro: The email address provided isn't found in the client's 360MatchPro account in the timeframe.

         

        Workflow notes:

        1. If there is more than one match-eligible donation associated with the email address in the time window, Double the Donation will return the most recently associated company name.

        2. If the most recent donation does not have a company name, Double the Donation will continue searching backward within the timeframe until it finds a company name.

        3. If any of the donations in the time window are ineligible, the ineligible error message will be returned, unless there's a more recent donation with a company name. If there's a more recent donation with an unknown company status, the ineligible status will take priority.