# Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.changeup.com/app/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # Platform Overview ChangeUp’s Donation Management System (DMS) is a robust suite of donation tools used by merchants, platforms, and banks, all accessible via app.changeup.com or the ChangeUp APIs.

Sample ChangeUp donation components in a checkout flow. The font and color styles are fully customizable.

ChangeUp DMS is a streamlined solution that empowers customers or payers to add a donation to their payment with a single click. It is built in compliance with SOC 2 Type II, PCI-SAQ A, US Data Privacy Policy, and GDPR standards. DMS is fully configurable by its users (brand partners, store owners, service providers, etc.), and since the architecture is an API-first approach, much of the functionality is available via the ChangeUp APIs, which assist partners in building applications using ChangeUp as the backbone. **Whiteglove API Partner Accounts** accommodate *Child* accounts at the widget level to meet a variety of organizational structures. For instance, using the API, a *Partner* can enable complete control of the donation settings to a *Franchise* and the *Franchisees* for their donation management and reporting. The donation widgets have `widgetName`, `id`, and `metadata` settings. For reporting purposes, donation transactions relate to a widget ID. Whiteglove API Partners use these identifiers to organize the donation widgets within the partner's application environment. This method gives our partners independent control over their systems' structure and allows for flexible integration. ### Explore our guides and examples to integrate ChangeUp. The system offers the following functionalities: * [**Widgets**](/app/changeup-dms/widget-setup/create-a-widget)**:** Customizable front-end modules that capture donations. Multiple donate-at-checkout widgets can be created depending on what the system or giving campaign requires. * [**Widget Settings**](/app/changeup-dms/widget-setup/configure-donate-at-checkout)**:** Each widget has its attributes, design, and functionality. Settings manage the configuration and provide embeddable code snippets. Users can select which charities are presented to customers/payers at checkout, how the donation amount is calculated (RoundUp, percentage of payment, or fixed amount), whether the merchants/brands match the donation, and much more. * [**Integration**](/app/changeup-dms/widget-setup/install-widget)**:** The code and instructions required to integrate ChangeUp widgets into your application and report donation transactions to ChangeUp. * [**Analytics**](/app/changeup-dms/reporting)**:** Widget-specific dashboards provide reports on donation data. * [**Authentication and Account Management**](/app/account-settings/edit-company)**:** Manage users/multi-factor authentication, organization profile, and view activity logs.
# Setup a ChangeUp DMS account ChangeUp DMS provides an admin dashboard that allows users to manage their donation components, reports, and team. The system is accessed by invitation only and is initially configured by a ChangeUp Administrator and then shared with the partner organization.

Once the partner has access, they can add their team users, create donation widgets, and view reports.

Once you've been notified with your account creation details, open a web browser, and visit to Login.
# Implementation Overview Implementing ChangeUp is straightforward. Follow this outline to be on the right track. Breaking down the project into three phases: **Planning**, **Integration**, and **Test & QA** historically work well. ## Checklist ### Planning The planning phase is critical to get all stakeholders on the same page, set expectations, and uncover any risks as early as possible: * [ ] **Define Teams** - With enterprise partners, this typically involves CSR, Product, UX/UI, Engineering, Accounting, and Legal. * [ ] **Scoping Questions** - Decide on topics that ChangeUp will provide before integration starts. * [ ] **Project Timeline** - Refine the project timeline based on discovery during scoping questions. ### Integration This is where the hands-on work really starts. As long as planning has been completed, integration will go smoothly. * [ ] Finalize UX/UI Design * [ ] Plan for Downstream System * [ ] [Technical Implementation](#technical-implementation) ### Test & QA ChangeUp widget(s) have been tested in the partner sandbox environment, and the flow of donations in internal partner systems is configured. * [ ] Switch to [Live Environment](/app/changeup-dms/widget-setup/test-and-live-environments) * [ ] Confirm Data Transfer from [Post Transaction](/app/changeup-dms/widget-setup/implement-the-post-checkout-webhook) * [ ] QA and Launch 🚀 ## Technical Implementation Following the framework above, the steps to going live in your application are: 1. [Create a widget](/app/changeup-dms/widget-setup/create-a-widget) 2. [Configure the widget](/app/changeup-dms/widget-setup/configure-donate-at-checkout) with charities, donation type, and other settings 3. Copy [Installation](/app/changeup-dms/widget-setup/install-widget) code 4. Copy into your app 5. Test & QA 6. Go live # Widget Setup A widget is a small block of code (approx. 12k) generated by the DMS that enables embedding the donation functionality in your application.

Example donate-at-checkout widget featuring two charities and the supersize option active.

There are four steps to create and install a donate-at-checkout widget: {% content-ref url="/pages/RSBsAiwSyrhyBqjsX6Yx" %} [Create a widget](/app/changeup-dms/widget-setup/create-a-widget) {% endcontent-ref %} {% content-ref url="/pages/4kWC8DIXff6zdBsiNmPh" %} [Configure Donate-at-Checkout](/app/changeup-dms/widget-setup/configure-donate-at-checkout) {% endcontent-ref %} {% content-ref url="/pages/tHokMG4M06IrsKXFyteD" %} [Install widget](/app/changeup-dms/widget-setup/install-widget) {% endcontent-ref %} {% content-ref url="/pages/9M7RBJYpLwDfahHoxbVf" %} [Implement the post-checkout webhook](/app/changeup-dms/widget-setup/implement-the-post-checkout-webhook) {% endcontent-ref %} # Create a widget {% hint style="info" %} [Widget creation API Docs](https://documenter.getpostman.com/view/25013896/2sBXinGACm) {% endhint %}

### Determine Live or Test Learn about the [different environments](broken://pages/ds48bIV74fY4NP5IdnRO) to decide where the widget should be created. ### Create New Widget Clicking Create New Widget opens a modal where you name the new widget.

In the modal, add a recognizable name. This could be the name of a website where it will live or be tied to a specific giving campaign like Black History Month or Giving Tuesday. Something that will be clear to the rest of your team. ### Edit Widget Once the widget is saved, Edit by clicking on the row or in the Actions column on the Donation Widget list.

### Configure Widget Now that widget has been created, all the controls for editing and configuring will be available. Jump to [Configure Donate-at-Checkout](/app/changeup-dms/widget-setup/configure-donate-at-checkout) for details. # Configure Donate-at-Checkout {% hint style="info" %} [Widget configuration API docs](https://documenter.getpostman.com/view/25013896/2s93eeSA1U#c860eb4a-a2a4-4be9-9569-d67a094d87de) {% endhint %} With the widget created, the settings sections are broken down into: * [Choose the charity or charities to support](#01-charities) * [Manage the donation format and who is giving](#02-manage-donation) * [Supersize options](#03-supersize) ## **01 Charities** Search for charities, and choose up to three to display in the widget. Search by name or EIN to find the organization you're looking for. In some cases, there will be multiple entries for the same charity (this is usually because there are different locations of the same organization) so be sure to know the city/town or country, as those will be revealed in the autocomplete menu.

Charity search with component preview on right.

### **Activate Charity Descriptions** Inform payers about the causes being supported by exposing short charity descriptions that pop up in a modal when the charity logos are clicked upon.

## **02 Manage Donation** Who makes the donation (merchant or customer, or merchant matching customer), donation format (RoundUp, percentage, or fixed amount), text settings, and display settings.

### Who Makes the Donation? Define who will be funding the donation presented in the widget:

Selection controls for who is making the donation.

**Customer**: The customer donates, either RoundUp, Fixed Amount, or Percent. The amount is auto-calculated based on the shopping cart total and displayed in the widget. **Customer + Merchant Matching**: If the customer elects to donate, then the Merchant matches the donation. **Merchant**: The donation is made by the Merchant. An example of this may be "1% of sales" for a specific campaign or time of year (Pride, Black History Month, Breast Cancer, Women's Empowerment, etc.). ### What's the Donation Format? Define what type of donation is going to be presented in the widget:

Selection controls for what the donation format is.

**RoundUp**: Amount is calculated based on the cart's total, after shipping and taxes. **Fixed Amount**: A predefined amount to charge as a donation. $1.00, $0.50, $3.00, etc. **Percentage of Sale**: Calculates the percentage before shipping and taxes. Focused on the percentage of purchased products, for instance: 1%, 0.5%, 3%, etc. ### Display Settings Options that affect the layout and whether charity logos are displayed. ChangeUp recommends displaying charity logos for a more engaging user experience.

**Show charity logos at checkout**: Enable or hide charity logos in the widget. **Opt-in checkbox placement**: There are two options for this setting. With heading, or with description:

### Text Settings Customize the text in the widget being created. The Donation/Format settings above have default text that suits the context. Edit the text at any time to publish to your widget. The Reset button reverts the text to the system defaults.

The blue item is a dynamic element that shows a calculated value.

## **03 Supersize** Configure an optional amount to add to a donation, for instance, either $1, $5, or $10. **Supersize**: On or Off. Hides or shows the Supersize option in the widget **Select Amount Options**: Choose amounts to be presented in the widget **Customize Text**: Optional; edit the Supersize headline in a way that matches the brand; "Would you like to increase your donation?", "Add to your donation?"

Supersize feature activated in the preview window.

# Install widget ## JavaScript Embeddable Widget Once a widget is configured and saved, it is ready to be installed. The Integrate tab in the component Settings will provide the client-side JavaScript required to place the resulting embed code within the existing page layout. The CSS is exposed within the Integrate section of the component for demonstration purposes. This should be integrated into the existing CSS structure within the destination application and can be modified to match the native styles of your platform or website. Multiple donation widgets can be configured to handle different checkout flows (for example if one brand has multiple websites and wants to feature different charities on each), or A/B testing.

Integration page showing embed code and widget preview.

## Event listeners In order to capture component actions, such as donation opt-in, opt-out, charity selected, etc., event listeners need to be set up. These event listeners will interact with your platform to add/remove/update the appropriate line items for the donation details. For example, the cart subtotal needs to be sent to ChangeUp for RoundUp calculation to take place. Basic implementation code: ```html

``` # Implement the post-checkout webhook The post-checkout webhook is required to record the completion of the donation. The webhook will have a set of required and optional fields to capture relevant details for the donation. The donation webhook URL is unique to each widget in ChangeUp DMS. This webhook URL is meant to be called from a server, not the client (as the URL should be considered a secret). {% hint style="info" %} [View the API docs for more details on the post-donation webhook](https://documenter.getpostman.com/view/25013896/2s93eeSA1U#b66dfc71-c4dd-4281-bf90-40771f040014) {% endhint %} ### Webhook Donation Recording and Reporting Upon receiving the webhook, ChangeUp processes the incoming data to record the donation using a queuing system. Once processed, the donation details are recorded and stored for real-time reporting purposes. A “record” date can be adjusted in the widget settings for the donation widget to actualize the donation in the database. The reconciliation date allows for special policies such as refunds. Reports will identify donations as “pre-record” and “post-record” dates and can be used for reconciliation. Reports can be filtered by donation widget and time range. Reports of all donation transactions can be downloaded for reconciliation purposes.
# Test and Live Environments The DMS has two environments where donation widgets are created and managed: Test and Live. Set the toggle to the required environment when creating widgets for integration testing or building production-ready widgets.

Environment switch in different settings.

### Sandbox Development Widgets created under the Test Mode will only report data to Test reports and cannot, under any circumstances, be used on a production website. They will not work, and no donations will be collected. ### Production Applications Switch to Live once ready to deploy production widgets that will record donations and charities and collect the data for [analytics](/app/changeup-dms/reporting). # Deactivating a widget 1.To deactivate a widget first go to the widget menu and select the widget you want to deactivate: ![](https://cdn.filestackcontent.com/hQ4EkabLTSyZut7ky1lq) 2.Go to the right-hand menu, click the down arrow next to “Integrate”, and select deactivate Widget.

3.Once the widget is deactivated the status in the widget screen will change to red.

# Promoting a widget If you have a widget that was created in “Test Mode” and you will like that Widget to be copied to the “Live Mode” with the same settings and configuration, follow these steps: 1.Turn the “Test Mode” toggle on .

2.Select the widget you want to promote. ![](https://cdn.filestackcontent.com/4fX2RZeuR1SmpKtMaU9r) 3.Go to the right-hand menu, click the down arrow next to “Integrate”, and select “Copy to live”

4\. When you switch back to "Live Mode" you will see the promoted widget in the widget list. # Checkout Preview If you want to preview your widget on a test checkout page follow these steps. 1.Select the widget you want to see the checkout preview. ![](https://cdn.filestackcontent.com/HoFQXwoNRymk0jKakbup) 2.Go to the right-hand menu, click the down arrow next to “Integrate”, and select “Checkout Preview”

3.Select and API Key

4.You can change the number of items in your cart. Everytime you refresh the page the items will randomly change . ![](https://cdn.filestackcontent.com/870CnB8QpGLGOUTlruYy) # Reporting Once transactions are reported to ChangeUp they are viewable in the Reports section ### Sample Reports

Sample changeup donations report — Sample donation activity report

# Viewing Reports Go to the Reports tab from the main navigation at the top of the page. The report shows a variety of findings. Filtering by date will refresh the page and refine the complete dashboard.

Date filter for the Reporting dashboard.

# Download Data There are two options for downloading report data, either at the chart level or a filtered transaction list. ### Chart Download A menu icon is shown at the top right of the charts on the Reports page. Open the menu and select Download (when available). This will generate a CSV of just the chart's data as a downloaded file.

Chart menu allowing a Pivot or Download of the data being displayed.

### Transaction List From the Reports page, View All Transactions.

On the Reports > Transactions page, there is a Download button to the right of the date filters.

Download as CSV to generate a copy of the filtered results shown in the table. # Embed Reports The following is example code for generating an embeddable URL for a report. Your account manager can assist with the dashboard, necessary filters, and the reporting API key. Custom reporting dashboards can be tailored to client specifications. ```javascript const {createHmac} = require("crypto"); const key = 'Your ChangeUp Reporting Secret API Key'; // the dashboard you want to embed const dashboard = 'dsh_01GRS8C4BVZ8X9N7E86Z82DQG9' // compose the data object with filters and dashboard const data = encodeURIComponent( JSON.stringify({ dashboard, filters: { "Date Range": "last_month", "Aggregation": "day", "ClientId": "YourClientId", // more filters can be added based on dashboard design } }) ); // create the encrypted signature const signature = createHmac("sha256", key).update(data).digest("hex"); // compose the embed url const embedUrl = `https://reporting.changeup.com/embed/dashboard/${dashboard}?data=${data}&signature=${signature}` java ``` ### Sample Reports

# Using Report Filters 1.Go to the main page and select reports.

2.You can select from the custom predefined date ranges or input a custom range.

3.You can also add extra filter by clicking “Add filter” you can filter by: * Cause * Widget * Donor (merchant or customer donation)

4.Once you have selected the filters the dashboard will refresh automatically. ![](https://cdn.filestackcontent.com/yjjlltdVSXZrRe65Q81D) # Canceling a Transaction There are three states that a transaction reported to ChangeUp can possibly have:

1. **Pending**: When a transaction has been reported but is delayed (according to the [post-checkout webhook](/app/changeup-dms/widget-setup/implement-the-post-checkout-webhook)), awaiting completion. 2. **Complete**: A transaction has passed the delay duration or has no delay and is finalized in the system. The transaction cannot be canceled and will be included in the monthly donation remittance. 3. **Canceled**: The transaction has been canceled before completion and is no longer included in the monthly donation total. ## How to cancel a transaction ### Navigate to Reports > View All Transactions The View Transactions button is on the main Reports page in the top right side of the page.

### Filter results There may be hundreds or thousands of results. Filter by date to find the transaction in question.

### Choose Transaction Once the transaction has been found, open the item's menu.

### Cancel Transaction Choose Cancel Transaction from the item menu.

### Confirm Cancelation Confirm this action; it cannot be undone once this transaction has been canceled.

### See canceled transaction Once the modal closes, the transaction will have a new status icon showing indicating the cancelation, this will ensure that it is not included in any donation remittance.

# View transactions details To see the transaction details follow these steps: 1\. In the report home screen click on "View All Transactions"

2\. The transaction will be displayed, you can filter by date range.

3\. If. you want to download all the transaction in a CSV file click on "Download".

4\. If you want to see a specific transaction detail click on the three dots and click "View Details"

5\. The details will be displayed.

# Donation Invoicing ChangeUp provides a monthly donation report. Upon approval of this report, remit the aggregate amount of donations to ChangeUp, who will manage the distribution of funds to the end charities. ChangeUp also supports automated invoicing to partners and merchants. # Edit Company ### Profile Menu > Account Settings > Company Personalize the DMS account by adding company information and a logo. Upload a logo image that is 150x150 and either a PNG, JPG or GIF.

# Manage Users ### Profile Menu > Account Settings > Users

From the User page, you may [Invite New Users](/app/account-settings/manage-users/invite-users). From the ellipsis action menu on each row, if you have the correct permissions (as a User), you can: * Reset Two-factor Authentication - Confirm you want to reset this user’s MFA settings. This will require them to reset their MFA the next time they log in. * Resend a User Invitation - Resend the invitation for this user. * Delete a User - Confirm you want to delete the user. This action cannot be undone. # Invite Users

Invite New User opens the Invitation modal:

Enter the new user's Full Name, Email Address, and choose permissions: | Permission | Access | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | User | Full access to the DMS account. Ability to create and manage widgets, add users, edit company info, and view reports. | | View Only | Limited access to the DMS. This user is intended to be only a viewer for reports. They have no editing capabilities and cannot create new widgets or users. | The Send Invitation button saves the information and transmits the invitation email to the new user. The invitation email will walk the new user through the steps required to set up their account, including [Two-factor Authentication](/app/account-settings/manage-users/two-factor-authentication). # Two-factor Authentication When you either set up Two-factor Authentication (2fa) for the first time or if it has been reset the following screen appears upon login. Open a mobile device and using an authentication app (Google Auth, Duo, Authy, etc.) scan the code to add ChangeUp DMS to your auth app.

Enter the six-digit code to Verify your account. Once the code verifies you will be automatically logged in to the DMS.

# Reset MFA To reset the MFA (Multiple Factor Authentication) for a user follow these steps. 1.Go to the top right menu and click the green round icon next to support:

2.Select “Users” from the Menu

3.Click the 3-doted menu of the user you want to reset the MFA.

4\. Click “Confirm MFA Reset”

# Forgot Password If you forget your password, just click Forgot your password? On the login screen.

A new page will open where you enter your email address so the system can send a password reset notification.

If the email is in the ChangeUp system and attached to an account you will receive an email with a Create New Password link.

Opening the link brings you to the Change your Password screen. Enter a new password following the security requirements: * Minimum 16 characters * At least one uppercase and lowercase character * At least one numeric character * At least one special character (!, @, #, $, etc.)

Once the new password meets the requirements all the hint text will turn green. Change Password.

Now you can Login to your account using the new credentials.

# Invite users to my account To invite new users to your account follow these steps: 1\. Go to the top right menu and click the green round icon next to support:

2\. Select “Users” from the Menu

4\. Click “Invite New User”

5\. Complete the information requested and click “Send Invitation”

# Resending a user invitation Invitation to the DMS expires 24 hours after being sent. If you need to resend an invitation here are the steps. 1.Go to the top right menu and click the green round icon next to support:

2.Select “Users” from the Menu

3.Click the 3-doted menu of the user you want to resend the invitation.

4.Click “Resend Invitation”

# Deleting a user If you want to delete a user, follow these steps: 1.Go to the top right menu and click the green round icon next to support: ![](https://cdn.filestackcontent.com/dcjHSz9TPeIzPKeE2heA) 2.Select “Users” from the Menu

3.Click the 3-doted menu of the user you want to delete and click "Delete User"

4.Click “Yes! Delete User” to confirm .

# View Activity Logs ### Profile Menu > Account Settings > Logs

Choose Logs on the Account Settings menu

The Activity Log explains what happened, by whom, and when. For audit purposes, the logs can continually be reviewed to monitor changes to widgets, users and the overall Partner account.

The Logs main view showing activity filtered by date.

Clicking on any line item opens the log detail panel.

# API Key ### Profile Menu > Account Settings > API Key

Go to API Key in Account Settings

### Confirm Environment Before creating a new API Key, ensure the desired environment is selected in the header.

### Create New API Key Create New API Key to open the API modal.

### Name the New API Key

### Create API Key

### Copy Secret Key {% hint style="info" %} Once the Secret Key is revealed, the only opportunity to copy it is now. ChangeUp will not save the Secret Key and it cannot be retrieved. Copy and store in a secure location. The Client ID will always be available on the API Keys page. {% endhint %}

The new API Key is now ready for use:

# Billing Information 1.Go to the top right menu and click the green round icon next to support to display the “Account Settings”

2.Select “Billing” from the Menu

3.Click “View Billing Portal” to see any amounts due of invoice history.

# Create API Keys To create your API keys follow these steps 1.Go to the top right menu and click the green round icon next to support to display the “Account Settings”

2.Select “API Key” from the Account Settings menu

3.Click “Create New API Key”

\* **Important**: remember that if the environment toggle is in “Test Mode” you will be creating API Keys for your staging environment and in Live mode for production. 4.Add a name to the API Key and click “Create API Key”

5.The API key will be displayed.

**Important**: Secret keys are not saved, be sure to copy and save your key in a secure place. # APIs ChangeUp has different APIs for different purposes. They are structured in the following categories: Components, Donations, and Reporting. ### Components API {% hint style="info" %} [Enable creating and maintaining donation widgets (Donate-at-Checkout as an example). Search for charities to use in donation widgets.](https://documenter.getpostman.com/view/25013896/2sBXinGACm) {% endhint %} ### Donations API {% hint style="info" %} [Create donations, fetch donation data, and cancel donations.](https://documenter.getpostman.com/view/25013896/2sBXinGACm) {% endhint %} # ChangeUp DMS ## Fetch and filter donations > List all donation(s) associated with a partner account in a paginated list. ```json {"openapi":"3.1.0","info":{"title":"ChangeUp DMS","version":"1.0.0"},"servers":[{"url":"https://donations.api.changeup.com"}],"paths":{"/v1/donations":{"get":{"summary":"Fetch and filter donations","parameters":[{"name":"limit","in":"query","description":"Limit of records to return","schema":{"type":"integer"}},{"name":"page","in":"query","description":"Which page to return. This endpoint is paginated.","schema":{"type":"integer"}},{"name":"charityId","in":"query","description":"(Optional) - Filter by charity Id","schema":{"type":"string"}},{"name":"transactionId","in":"query","description":"(Optional) - Your transaction id used to create the donation(s)","schema":{"type":"string"}},{"name":"startDate","in":"query","description":"(Optional) - Filter donations with a start date MM/DD/YYY","schema":{"type":"string"}},{"name":"endDate","in":"query","description":"(Optional) - Filter donations with a end date","schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"(Optional) - sort asc or desc","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"(Optional) - sort by any field","schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":false,"description":"(Required) ","deprecated":false,"schema":{}},{"name":"x-client-id","in":"header","required":false,"description":"(Required) ","deprecated":false,"schema":{}}],"responses":{"200":{"description":"Sucess","content":{"application/json":{"schema":{"type":"object","properties":{"docs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"partnerId":{"type":"string"},"daf":{"type":"string"},"dafAccountType":{"type":"string"},"amount":{"type":"integer"},"causeId":{"type":"string"},"charityId":{"type":"string"},"transactionId":{"type":"string"},"currency":{"type":"string"},"country":{"type":"string"},"jobId":{"type":"null"},"invoiceId":{"type":"null"},"receipt":{"type":"null"},"environment":{"type":"string"},"type":{"type":"string"},"transactionOrderDate":{"type":"string","format":"date-time"},"reason":{"type":"null"},"source":{"type":"string"},"widgetId":{"type":"string"},"delayReportBy":{"type":"integer"},"status":{"type":"string"},"invoiced":{"type":"boolean"},"generateReceipt":{"type":"boolean"},"invoicedAt":{"type":"null"},"reportTransactionAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"benevityDonationCreatedAt":{"type":"string","format":"date-time"},"benevityResponse":{"type":"array","items":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"funds":{"type":"object","properties":{"amount":{"type":"integer"},"source":{"type":"string"},"paymentType":{"type":"string"},"currencyCode":{"type":"string"}}},"state":{"type":"object","properties":{"processingStatus":{"type":"string"},"statusLastUpdated":{"type":"string","format":"date-time"}}},"destination":{"type":"object","properties":{"recipientId":{"type":"string"}}}}}}}}}}}}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"lastPage":{"type":"integer"},"currentPage":{"type":"integer"},"perPage":{"type":"integer"},"prev":{"type":"null"},"next":{"type":"integer"}}}}}}}}},"description":"List all donation(s) associated with a partner account in a paginated list."}}}} ``` ## Create donation > Send a single or batch of donations.\ > \ > Creates a single donation or batch donations. Batch donations accepts a limit of 15 per request. to any nonprofit.\ > \ > \> \*\*Note:\*\* To schedule a future to be posted at a future date, set the delayReportBy field (e.g., a value of 5 will delay the report for 5 days). This allows you to cancel a donation before it is finalized. Please note that once a donation is posted after the delay period, it cannot be cancelled. The maximum allowable delay is 90 days. ```json {"openapi":"3.1.0","info":{"title":"ChangeUp DMS","version":"1.0.0"},"servers":[{"url":"https://donations.api.changeup.com"}],"paths":{"/v1/donations":{"post":{"summary":"Create donation","parameters":[{"name":"x-api-key","in":"header","required":false,"description":"(Required) - API Key Secret","deprecated":false,"schema":{}},{"name":"x-client-id","in":"header","required":false,"description":"(Required) - Client Secret","deprecated":false,"schema":{}}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"id":{"type":"string"},"sourceId":{"type":"string"},"status":{"type":"string"},"transactionId":{"type":"string"}}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}},"description":"Send a single or batch of donations.\n\nCreates a single donation or batch donations. Batch donations accepts a limit of 15 per request. to any nonprofit.\n\n> **Note:** To schedule a future to be posted at a future date, set the delayReportBy field (e.g., a value of 5 will delay the report for 5 days). This allows you to cancel a donation before it is finalized. Please note that once a donation is posted after the delay period, it cannot be cancelled. The maximum allowable delay is 90 days.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"array","items":{"type":"string"}},"properties":{"type":"object","properties":{"donations":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"items":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"array","items":{"type":"string"}},"properties":{"type":"object","properties":{"amount":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"}}},"delayReportBy":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"}}},"causeId":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"}}},"transactionId":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"}}},"currencyCode":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"}}},"metadata":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"}}}}}}}}}}}}}}}}}}}} ``` ## Fetch donation by id > Use to fetch the status and details of a single donation by Id ```json {"openapi":"3.1.0","info":{"title":"ChangeUp DMS","version":"1.0.0"},"servers":[{"url":"https://donations.api.changeup.com"}],"paths":{"/v1/donations/{id}":{"get":{"summary":"Fetch donation by id","parameters":[{"name":"x-api-key","in":"header","description":"(Required) ","schema":{"type":"string"}},{"name":"x-client-id","in":"header","description":"(Required) ","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"partnerId":{"type":"string"},"daf":{"type":"string"},"dafAccountType":{"type":"string"},"amount":{"type":"integer"},"causeId":{"type":"string"},"charityId":{"type":"string"},"transactionId":{"type":"string"},"currency":{"type":"string"},"country":{"type":"string","format":"color"},"jobId":{"type":"string"},"invoiceId":{"type":"null"},"receipt":{"type":"null"},"environment":{"type":"string"},"type":{"type":"string"},"transactionOrderDate":{"type":"string","format":"date-time"},"reason":{"type":"string"},"source":{"type":"string"},"widgetId":{"type":"string"},"delayReportBy":{"type":"integer"},"status":{"type":"string"},"invoiced":{"type":"boolean"},"generateReceipt":{"type":"boolean"},"invoicedAt":{"type":"null"},"reportTransactionAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"benevityDonationCreatedAt":{"type":"null"},"benevityResponse":{"type":"array"},"widget":{"type":"object","properties":{"id":{"type":"string"},"widgetName":{"type":"string"}}},"charity":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"}}}}}}}}},"description":"Use to fetch the status and details of a single donation by Id"}}}} ``` ## Cancel a donation > Cancel a donation that has not been posted to a DAF. When a donation is posted, it goes from:\ > \ > \*\*PENDING\*\* -> \*\*COMPLETED\*\*\ > \ > Donation(s) marked as \*\*COMPLETED\*\* cannot be canceled.\ > \ > Once a donation is canceled, the status will be marked as \*\*CANCELED.\*\*\ > \ > \| \*\*Field\*\* | \*\*Type\*\* | \*\*Description\*\* |\ > \| --- | --- | --- |\ > \| reason | String | \`Optional\` \
Reason for canceling the donation | ```json {"openapi":"3.1.0","info":{"title":"ChangeUp DMS","version":"1.0.0"},"servers":[{"url":"https://donations.api.changeup.com"}],"paths":{"/v1/donations/{id}/cancel":{"patch":{"summary":"Cancel a donation","parameters":[{"name":"x-api-key","in":"header","description":"(Required) ","schema":{"type":"string"}},{"name":"x-client-id","in":"header","description":"(Required) ","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}},"description":"Cancel a donation that has not been posted to a DAF. When a donation is posted, it goes from:\n\n**PENDING** -> **COMPLETED**\n\nDonation(s) marked as **COMPLETED** cannot be canceled.\n\nOnce a donation is canceled, the status will be marked as **CANCELED.**\n\n| **Field** | **Type** | **Description** |\n| --- | --- | --- |\n| reason | String | `Optional`
Reason for canceling the donation |","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}}}} ``` # Security Practices ### Compliance ChangeUp is fully compliant with SOC 2 Type II, PCI-SAQ A, US Data Privacy Policy, and GDPR. ### Data Security & Governance ChangeUp encrypts data at rest and in transit for all of our customers. We use tools like Amazon Web Service’s Key Management System (KMS) to manage encryption keys using hardware security modules for maximum security in line with industry best practices. ChangeUp employs data security governance principles by focusing on sensitive data protection and privacy, conducting, deleting unnecessary data, and consolidating data silos, whether they are on-premises or in the cloud, to ensure project alignment with business objectives. ### Application Security ChangeUp regularly engages some of the industry’s best application security experts for third-party penetration tests. Our penetration testers evaluate the source code, running application, and the deployed environment. ChangeUp also uses high-quality static analysis tooling provided by GitHub Advanced Security such as CodeQL, Secrets Scanner, and Dependabot to secure our product at every step of the development process. ### Infrastructure Security ChangeUp uses Amazon Web Services to host our application. We make full use of the security products embedded within the AWS ecosystem, including KMS, GuardDuty, and Inspector. In addition, we deploy our application using containers run on AWS-managed services, meaning we typically do not manage servers or EC2 instances in production. \