Integrating Connect (DAFpay)

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

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

npm install --save react-chariot-connect

yarn add react-chariot-connect

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.

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

import React, { useState } from 'react';
import ChariotConnect from 'react-chariot-connect';

const App = () => {
    return (
        <div>
            <ChariotConnect
                cid="GENERATED_CONNECT_IDENTIFIER"
            />
        </div>
    );
};

A nonprofit's cid (Connect ID) should be retrieved from your database after the nonprofit has been registered with Chariot. For now, feel free to use this cid for testing purposes: test_15b867c559e3c73a80cd69efd115cb928cb9874625291f756f7273446bcd8f88.

Note: For testing purposes in a 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.

// get the element from the DOM
const chariot = document.getElementById("chariot")

// provide a callback that returns the donation data
chariot.onDonationRequest(async () => {
  return {
    amount: 25000, //this is $250.00 USD
    firstName: "Michael",
    lastName: "Scott",
    email: "[email protected]",
    metadata: {
      fundraiserTag: "marathon"
    },
  }
})

import React, { useState } from 'react';
import ChariotConnect from 'react-chariot-connect';

const App = () => {
    const onDonationRequest = () => {
        return {
            amount: 25000, //this is $250.00 USD
            firstName: "Michael",
            lastName: "Scott",
            email: "[email protected]",
            metadata: {
                fundraiserTag: "marathon"
            },
        }
    }

    return (
        <div>
            <ChariotConnect
                cid="GENERATED_CONNECT_IDENTIFIER"
                onDonationRequest={onDonationRequest}
            />
        </div>
    );
};

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

Parameter	Description	Type
amount	The 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)
firstName	The donor's first name	string (optional)
lastName	The donor's last name	string (optional)
email	The donor's email address. Must be in email format	string (optional)
phone	The donor's phone number. Please provide the phone number with the country code and without special characters	string (optional)
note	A note the donor wants to send to the nonprofit	string (optional)
anonymous	Indicates if this donation should be sent anonymously (default: false)	boolean (optional)
metadata	An 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)

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:

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.
Submit your own donation form before converting the grant intent into a completed grant.
Note: Submitting your own donation form before converting the grant ensures consistency between your systems and Chariot.
Have your backend call Chariot's Create Grant API to complete the grant (and capture the grant intent).

// get the element from the DOM
const chariot = document.getElementById('chariot');

chariot.addEventListener('CHARIOT_SUCCESS', ({ detail }) => {
		// Record the grant intent information so that you can
    // capture the transaction once your form is submitted.
});

import React, { useState } from 'react';
import ChariotConnect from 'react-chariot-connect';

const App = () => {
  const onSuccess = (r) => {
		// Record the grant intent information so that you can
    // complete the transaction once your form is submitted.
  };
  const onExit = (e) => console.log('exit', e);
  const onDonationRequest = () => {
    // your logic
  }

  return (
    <div>
        <ChariotConnect 
          cid="GENERATED_CONNECT_IDENTIFIER" 
          onDonationRequest={onDonationRequest} 
          onSuccess={onSuccess} 
          onExit={onExit} 
        />
    </div>
  );
};

Response Objects

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

{
    "workflowSessionId": "79e772be-547d-4c9c-8b76-4ac4ed4c441a", // Id of the Connect workflow session.	
    "nodeId": "consent-node-id", // The id representing the pane where the user exited the Connect flow.
    "fundId": "bbf485dd-a056-4a9d-89a8-06e201cdbf7f", // The id of the donor advised fund that the user selected.
    "reason": "USER_EXIT", // An enum giving a reason to why the modal exited.
    "description": "User exited the flow" // A human readable string containing a brief sentence explaining the exit reason.
}

Event Name	Description	Metadata Type
`CHARIOT_INIT`	The 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_SUCCESS`	The 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 route.	`OnSuccessMetadata`
`CHARIOT_EXIT`	The 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

enum ExitReason {
  USER_EXIT = "USER_EXIT", // User exited the flow
  UNINTEGRATED_DAF = "UNINTEGRATED_DAF", // DAF is not integrated with Chariot
  UNINTEGRATED_GRANT_CONFIRMED = "UNINTEGRATED_GRANT_CONFIRMED",  // Unintegrated grant confirmed with Chariot
  CID_NOT_FOUND = "CID_NOT_FOUND", // Connect Identifier is not found
  CREDENTIALS_ERROR = "CREDENTIALS_ERROR", // Invalid credentials
  INVALID_CARD = "INVALID_CARD", // Invalid card number
  TFA_ERROR = "TFA_VERIFICATION_ERROR", // Two-factor authentication error
  ZERO_AMOUNT = "ZERO_GRANT_AMOUNT", // Grant amount is zero
  SERVICE_DEACTIVATED = "SERVICE_DEACTIVATED", // Nonprofit's Connect is deactivated (active = false)
  ACCESS_RESTRICTED = "ACCOUNT_ACCESS_RESTRICTED", // User's DAF sponsor account electronic access is restricted
  EIN_NOT_FOUND = "NONPROFIT_NOT_FOUND", // DAF sponsor does not support grants to the Nonprofit
  CONNECTION_FAILED = "CONNECTION_FAILED", // Connection to the DAF sponsor failed
  SESSION_NOT_FOUND = "SESSION_NOT_FOUND", // User session is not found and may have expired
  CUSTOM_ERROR = "CUSTOM_ERROR", // Custom error
  INTERNAL_ERROR = "INTERNAL_ERROR", // Internal error
  INSTITUTION_DOWN_ERROR = "INSTITUTION_DOWN_ERROR", // DAF sponsor institution is down; user should try again later
}

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.