Reference for initializing DAFpay using React or JavaScript SDK
Recommended ImplementationEnable 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]",
address: {
line1: "123 Main St",
line2: "Suite 4",
city: "New York",
state: "NY",
postalCode: "12345"
},
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) |
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) |
address | The donor's address: line1, line2, city, state, postalCode | object (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.- 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.