Integrating Connect (DAFpay)

Installation

Chariot Connect (DAFpay button) comes as a small JavaScript package. It can be loaded directly from the Chariot CDN or installed via NPM or Yarn. When loading from the CDN, it must always be loaded directly from https://cdn.givechariot.com, rather than included in a bundle or hosted yourself.

1
<script src="https://cdn.givechariot.com/chariot-connect.umd.js"></script>

Add Chariot Connect

Chariot provides a simple-to-use web component that allows you to implement the Chariot Connect (DAFpay) button with a single line. Add Chariot-Connect component where you want the DAFpay button to appear.

1
<chariot-connect id="chariot" cid="GENERATED_CONNECT_IDENTIFIER"></chariot-connect>

A nonprofit’s cid (Connect ID) should be retrieved from your database after the nonprofit has been registered with Chariot.

username: good-user
password: password123

Pre-populate data into your Connect Session

Chariot accepts information before it launches a Connect session. To provide this information, leverage the onDonationRequest function from the Chariot element. As suggested above, pre-populating this information is completely optional, however you can use metadata if you want to associate the payment or session with any data in your system.

1
// get the element from the DOM
2
const chariot = document.getElementById("chariot")
3
4
// provide a callback that returns the donation data
5
chariot.onDonationRequest(async () => {
6
  return {
7
    amount: 25000, //this is $250.00 USD
8
    firstName: "Michael",
9
    lastName: "Scott",
10
    email: "michaelScott@theoffice.com",
11
    address: {
12
      line1: "123 Main St",
13
      line2: "Suite 4",
14
      city: "New York",
15
      state: "NY",
16
      postalCode: "12345"
17
    },
18
    designation: "My Special Designation",
19
    metadata: {
20
      fundraiserTag: "marathon"
21
    },
22
  }
23
})

The given donation data must match the following schema to be accepted by Chariot:

Capture your grant intent

When a user completes a Chariot Connect session you will receive a grant intent. After you submit your own donation form, don’t forget to call the Create Grant API to complete the transaction.

Most workflows proceed as follows:

1. Listen for the CHARIOT_SUCCESS event to receive the grant intent after a Chariot Connect session.
   1. If you would like to collect any additional information from the user such as additional contact information you can do so at this step. If the Chariot Connect session is the last step in your donation form this is not necessary.
2. Submit your own donation form before converting the grant intent into a completed grant.
3. Have your backend call Chariot’s Create Grant API to complete the grant (and capture the grant intent).

1
// get the element from the DOM
2
const chariot = document.getElementById('chariot');
3
4
chariot.addEventListener('CHARIOT_SUCCESS', ({ detail }) => {
5
    // Record the grant intent information so that you can
6
    // capture the transaction once your form is submitted.
7
});

Response Objects

1
  {
2
    "workflowSessionId":"79e772be-547d-4c9c-8b76-4ac4ed4c441a", //Id of the Connect session
3
    "grantIntent": {
4
      "userFriendlyId": "100020", //The user-friendly identifier for the grant intent
5
      "fundId": "bbf485dd-a056-4a9d-89a8-06e201cdbf7f", //Id of the donor advised fund
6
      "amount": 2000, //The grant amount expressed in units of cents; USD only
7
      "metadata": {} // The same metadata object that was passed in the onDonationRequest callback referenced above
8
    }
9
  }

Exit Reasons

Recurring Donations (Beta)

Chariot enables a donor to not only initiate a one-time grant, but also allows donors to initiate recurring grants through their Donor Advised Fund. Currently, Chariot allows donors to submit MONTHLY recurring grants for all of our DAF integrations, however we are actively trying to expand this functionality across all of our various integrations.

Recurring donations are a powerful way to generate consistent revenue streams for nonprofits and they make up a large majority of the DAF grants that are distributed to charity each year.

When a user completes a Chariot Connect session for a recurring donation, instead of receiving a grant intent as part of the CHARIOT_SUCCESS event, you will receive a recurringGrantIntent.

1
  {
2
    "workflowSessionId":"79e772be-547d-4c9c-8b76-4ac4ed4c441a", //Id of the Connect session
3
    "recurringGrantIntent": {
4
      "userFriendlyId": "100020", //The user-friendly identifier for the grant intent
5
      "fundId": "bbf485dd-a056-4a9d-89a8-06e201cdbf7f", //Id of the donor advised fund
6
      "amount": 2000, //The grant amount expressed in units of cents; USD only
7
      "frequency": "MONTHLY", // The frequency of the recurring schedule for the donation
8
      "metadata": {} // The same metadata object that was passed in the onDonationRequest callback referenced above
9
    }
10
  }

After you submit your own donation form, don’t forget to call the Create Recurring Grant API to complete the transaction.

Advanced Customizations

Disabling Chariot Connect

To prevent Connect from initiating until form validation is performed, passing false to the onDonationRequest will stop the button from launching.