Integrating Connect (DAFpay)

Reference for initializing DAFpay using React or JavaScript SDK

Recommended Implementation

Enable by Default: DAFpay supports transactions for all eligible 501(c)(3) organizations, allowing DAFpay to function on a donation form prior to the completion of the nonprofit’s onboarding with Chariot. Thus, we advise setting DAFpay as a default payment option across your donation pages. This will improve fundraising outcomes and help develop relationships with key donors!

Express Checkout Option: DAFpay offers the capability to automatically gather crucial donor information, such as names, email addresses, physical addresses, and more. Additionally, DAFpay provides Intelligent Donation Recommendations, taking into account factors like the donor’s account balance. For this reason, we recommend featuring DAFpay as an Express Checkout option, making it visible early in the donation process, before donors are prompted to input their information or decide on a donation amount. This enhances conversion rates and encourages larger donations.

Please don’t hesitate to contact us at support@givechariot.com with any questions!

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.

Note: For testing purposes in the sandbox environment the following credentials will log in to any DAF provider.

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
2const chariot = document.getElementById("chariot")
3
4// provide a callback that returns the donation data
5chariot.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:

ParameterDescriptionType
amountThe donation amount in cents. e.g., for a $20 donation, enter 2000.

If this value is not passed in, Chariot will use the user’s account balance to recommend a donation amount. This can lead to significantly larger donation amounts.
number (optional)
firstNameThe donor’s first namestring (optional)
lastNameThe donor’s last namestring (optional)
emailThe donor’s email address. Must be in email formatstring (optional)
phoneThe donor’s phone number. Please provide the phone number with the country code and without special charactersstring (optional)
noteA note the donor wants to send to the nonprofitstring (optional)
anonymousIndicates if this donation should be sent anonymously (default: false)boolean (optional)
designationThe designation to include on the grant. If this is left blank, “Where needed most” will be used. Note that including a custom designation may cause the grant approval process to take longer. Designations over 100 characters will be truncated.string (optional)
addressThe donor’s address: line1, line2, city, state, postalCodeobject (optional)
metadataAn object with a set of name-value pairs. You can use this object to include any miscellaneous information you want to tie to the workflow session.object (optional)
fundIdThe ID of the preselected DAF provider.

If this value is provided, the donor will not be shown the default DAF dropdown and will instead be taken straight to that DAF’s login.
string (optional)
frequencyThe recurring frequency of the DAF grant (if it’s a recurring gift). This parameter allows the following possible enum values: ONE_TIME, MONTHLY. If not provided, the grant will default to a ONE_TIME grant. For more information on recurring donations, please see the section belowstring (optional)

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).

Submitting your own donation form before capturing the grant ensures consistency between your systems and Chariot.

1// get the element from the DOM
2const chariot = document.getElementById('chariot');
3
4chariot.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 }
Event NameDescriptionMetadata Type
CHARIOT_INITThe init event is called when the Chariot Connect script is initialized and ready to be run. This is useful to be able to know when Chariot Connect is initialized and ready to be used.No metadata is provided for this event.
CHARIOT_SUCCESSThe success event contains a final summary of the Connect workflow session. It contains the workflow session id and relevant donation information.

Once you receive the success event don’t forget to complete the transaction by calling the Create Grant or Create Recurring Grant route based on the grant intent data.
OnSuccessMetadata
CHARIOT_EXITThe exit event is called when a user exits without successfully completing the flow, when an error occurs during the flow, or when a user confirms an unintegrated grant.OnExitMetadata

Exit Reasons

Exit ReasonDescription
USER_EXITUser exited the flow.
UNINTEGRATED_DAFDAF is not integrated with Chariot.
UNINTEGRATED_GRANT_CONFIRMEDUnintegrated grant confirmed with Chariot.
CID_NOT_FOUNDConnect Identifier is not found.
INELIGIBLE_ORGANIZATIONThis Organization is not eligible to receive DAF donations.
CREDENTIALS_ERRORInvalid credentials.
INVALID_CARDInvalid card number.
TFA_ERRORTwo-factor authentication error.
ZERO_AMOUNTGrant amount is zero.
SERVICE_DEACTIVATEDNonprofit’s Connect is deactivated (active = false).
ACCESS_RESTRICTEDUser’s DAF sponsor account electronic access is restricted.
EIN_NOT_FOUNDDAF sponsor does not support grants to the Nonprofit.
CONNECTION_FAILEDConnection to the DAF sponsor failed.
SESSION_NOT_FOUNDUser session is not found and may have expired.
CUSTOM_ERRORCustom error.
INTERNAL_ERRORInternal error.
INSTITUTION_DOWN_ERRORDAF sponsor institution is down; user should try again later.
NO_CHARITABLE_ACCOUNTSDonor has no charitable accounts in the logged in account.
INVALID_PRESELECTED_DAFPreselected DAF is invalid.
INACTIVE_CARDInactive card.

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.

If your platform is interested in leveraging DAFpay to power recurring donations, please reach to the Chariot team directly.

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.

Note that if your platform enables recurring donations through Chariot, you will need to differentiate which of Chariot’s APIs you use to capture the donation based on the information of the CHARIOT_SUCCESS event.

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.