Configuring FinDock for Fundraising

This article assumes you have already gone through the main Salesforce NPC setup.

Prerequisites

• FinDock Core installed and configured
• Working ProcessingHub connection
• Working WebHub connection

Fundraising minimum configuration

The following Salesforce configuration must be completed to be able to use FinDock for Fundraising.

• Enable the Person Account feature Salesforce Setup and update user profiles for FinDock users to access the record type(s).
• Enable the Fundraising feature in Salesforce Setup
  1. Assign the Fundraising Access permission set (and license) to all FinDock users, including the integration user.
  2. Assign other Fundraising permissions to admins and other FinDock users as needed.
  3. Fundraising objects are private by default, so sharing needs to be provided to FinDock users (including the integration user) by changing org-wide sharing, modifying sharing rules, or creating custom permission sets with View All and Modify All for Gift Commitment, Gift Commitment Schedule, Gift Default Designation, Gift Designation and Gift Transaction.
  4. Create Recurring Schedule Transaction must be set to True.
  5. Set up Schedule a Gift Commitment Batch Processing Job (to enable gift transaction creation from gift commitments).
  6. Create and set a default Gift Designation.

Regarding the last point above, if no default is set, you will run into the OrgWideDefaultNotSet Salesforce error. For further information, see the Salesforce help about Gift Designations.

Please make sure you set up the rest of Fundraising as needed for your specific needs before proceeding.

Install FinDock for Fundraising

Follow the standard procedure for installing source connectors to add the Fundraising connector.

Check and assign the required permissions. If you are using custom permission set groups, ensure the package-specific permission sets are assigned.

Required configuration

The FinDock for Fundraising source connector has a few required configuration steps. There are several more advanced configuration options (see below) that should also be modified. However, you can start using the package with the minimum required configuration and the advanced configuration defaults.

Core general settings

First thing to do is set the default source for FinDock to be Fundraising.

Layout configuration

To make use of FinDock, several fields are required on the Gift Transaction, Gift Commitment and Gift Commitment Schedule layouts. Since Gift Commitment Schedules are managed through Flow screens accessible from buttons and components on the Gift Commitment, FinDock fields also need to be present on these screens.

Note that FinDock does not use the standard Payment Method field on Fundraising objects. FinDock automatically syncs values one-way, from the custom Payment Method field (fdff__Payment_Method__c) to the standard Salesforce field (paymentMethod). The payment methods added by FinDock are not automatically removed from the Salesforce picklist when deactivated in FinDock. You can, however, manually remove deactivated values if needed.

Page layouts

Update the Gift Transaction and Gift Commitment Schedule layouts with the following FinDock fields (field names ending with __c):

• Gift Transaction:
  • Payment Method
  • Payment Processor
  • Target
  • Mandate
  • Payment Profile
• Gift Commitment Schedule:
  • Payment Method
  • Payment Processor
  • Target
  • Mandate
  • Payment Profile

For your Gift Transaction page layout, we also recommend creating a custom related list to show the related Installment records on the Gift Transaction record. This makes tracking payments for gift transactions much easier.

Gift Entry template

If you are going to use Gift Entry, ensure that payment-related fields used by FinDock are included in your Gift Entry template. For example, you should include at least Payment Method and Payment Processor on the template, preferably with default values.

Flow configuration

Two important flows are required to manage gift commitment schedules for gift commitments. These flows are:

• Manage Gift Commitment Schedule
• Update Recurring Gift Commitment Schedule

These two are essential to FinDock for Fundraising since most data required for payment collection is on the Gift Transaction record, including FinDock fields. This information can also be found on the Gift Commitment Schedule record related to the gift transaction.

Adjusting screens in flows provided by Salesforce requires the flow to be cloned. This also means if Salesforce makes changes to the provided flows, the updates from Salesforce are not automatically applied to your cloned version.

Please make sure to keep your cloned flows up to date by incorporating changes to the original flow from Salesforce. For example, create a standard operating procedure you can follow when a Salesforce or FinDock flow update arrives.

Also note that when you create a clone, links from Lightning Web Components to flows like the Manage Gift Commitment component on the Gift Commitment Lightning page and all buttons linking to Flows are also lost. These need to be re-created and linked to the new cloned flow.

Flow configuration through FinDock Labs

For your convenience, FinDock supplies versions of the two gift commitment schedule flows and related components through FinDock Labs on GitHub. These can be installed by simply clicking Deploy to Salesforce in the README and authenticating your environment. Alternatively, you can clone the repository and deploy the metadata through SFDX.

The following types of components are provided unmanaged:

• Gift Commitment Schedule Management flows
• A Lightning Record page with a Manage Gift Commitment LWC component with parameterized buttons you can use in different (custom) flows to replace the Salesforce component pointing to the Salesforce Gift Commitment Schedule Management flows
• Lightning Actions linked to the right places of the flows for your layouts. These can also be used in the Action Launcher deployments based on Lightning actions (for instance on the Account layout).

For a detailed list of components and instructions on how to use them, please visit the README in the GitHub repository. Since these components are provided unmanaged, you may adjust them as you see fit to tailor them to your environment.

Manual flow configuration

If you would like to create your own custom flows from scratch, you can clone and manually configure the Gift Commitment Schedule flows yourself. Once cloned, you need to adjust the flow screens and add specific fields. Make sure to map these fields to their values on Gift Transaction through the flows variables:

• Manage Gift Commitment Schedules:
  • Create Recurring Gift Commitment Schedule
    • Payment Method
    • Payment Processor
    • Target
    • Payment Profile
    • Mandate
• Update Recurring Gift Commitment Schedule
  • Update Payment Method
    • Payment Method
    • Payment Processor
    • Target
    • Payment Profile
    • Mandate
  • Upgrade Downgrade
    • Payment Method
    • Payment Processor
    • Target
    • Payment Profile
    • Mandate

Once you’ve completed your configuration of the flows, make sure to update all references, like quick action buttons, to these flows.

Tributes

The FinDock for Fundraising package includes special package actions for donation tributes. For custom front-end integrations, you can set several parameters through the Payment API. Use GET /PackageActions from the /services/apexrest/cpm/v2/PackageActions endpoint to retrieve the available parameters and their descriptions.

Tributes are also a built-in feature of Giving Pages when FinDock for Fundraising is used. The tribute configuration is part of the Payment Form setup under the Amounts & Frequency settings.

There you can define the tribute itself.

In addition, you can collect details to send out a tribute message.

Tribute details gathered through FinDock are automatically mapped to the corresponding fields on Gift Tribute.

Advanced configuration

Though not required, we strongly recommend adjusting the defaults provided by FinDock in the advanced configuration areas of FinDock for Fundraising. The defaults can be used to familiarize yourself with features and capabilities, but most real cases require further configuration and customization.

Record type exclusion

Use the Excluded Gift Transactions Record Types selector to remove specific record types from the source connector installment handling logic.

When a gift transaction with an excluded record type is created or updated, no installment actions are triggered in FinDock.

Person Account record types

Record types are always important, but they take on additional significance with the use of person accounts. So, do take time to plan and set default org and profile record types.

We recommend explicitly setting the record type for online payment collection. With Giving Pages, that means adding the Person Account record type Id to the payment form as an additional input field. For information about using record types in payment intent messages, please see the Payment API Reference.

Deduplication considerations

Accounts are not deduplicated with Person Accounts, so you need to specify record types in your deduplication rules.

Field mapping

To maintain synchronized data between FinDock and Fundraising objects, FinDock uses managed and custom field mappings.

The extension settings include Custom Mapping and FinDock Managed Mapping. The latter is provided as reference of the mapping details maintained by FinDock. The Custom Mapping table is where you can add your own mappings as needed.

For each mapping relation, you need to specify the Salesforce object and field, the FinDock object and field, as well as the sync direction. The direction setting is particularly important and should be carefully considered. The syncing options are:

← Only sync when the field changes on FinDock object
→ Only sync when the field changes on the Salesforce object
⇆ Sync when the field changes on either the FinDock or Salesforce object

Status mapping

The status mapping between Gift Commitment and Installment is pre-defined by FinDock . The mapping table is included in the FinDock for Fundraising setup for reference only.

The status mapping needs to be rigid to prevent payment management flows from inadvertently breaking the status update rules for Gift Commitment. For further information about Gift Commitment Status, please refer to Salesforce Help Gift Transaction.

Campaign and Outreach Source Code

With Salesforce Fundraising, Outreach Source Code has a central role in campaign fundraising management. You can still use Campaign Ids when setting up new donations through the FinDock Payment API or Giving Pages (and PayLinks), but the value of the Source Code field on Outreach Source Code should be included to enable easy evaluation of outreach efforts for a given campaign.

To leverage Source Code, you need to first add the Source Code field to the Installment object. Then, with the custom field mapper in FinDock for Fundraising, map the Installment SourceCode field to the Gift Transaction OutreachSourceCodeId field. The sync direction depends on the use case, but bi-directional syncing is recommended.

To use Source Code on a Giving Pages or PayLinks payment form, simply add it as a hidden input field on the form. For instructions, see Add additional form fields.

Using the FinDock Payment API, the Source Code needs to be passed in the SalesforceFields section of a OneTime or Recurring message block. For example:

{
  "OneTime":{
    "Amount": 10.0,
    "SalesforceFields": {
      "SourceCode__c": "a-unique-code-value"
    }
  }
}

API considerations and examples

There are two characteristics of the Salesforce Fundraising features that require additional attention when using the FinDock Payment API:

• Fundraising uses Person Accounts: more information on how to use Person Accounts with our API can be found in our API reference.
• Since recurring donations are defined by two objects, Gift Commitment and Gift Commitment Schedule, a prefix GiftCommitment is required to set SalesforceFields on the Gift Commitment object. Fields without prefix are assumed to be set on the Gift Commitment Schedule object.
  Example: GiftCommitment.GiftVehicle is set on the Gift Commitment, while GiftVehicle would be set on the Gift Commitment Schedule if available.

Example of a one-time gift from an individual donor

{
 "SuccessURL": "https://www.example.com/success",
 "FailureURL": "https://www.example.com/error",
 "Payer": {
   "Account": {
     "RecordTypeName": "PersonAccount",
     "SalesforceFields": {
       "FirstName": "John",
       "LastName": "Johnson",
       "PersonEmail": "johnjohnson@test.com"
     }
   }
 },
 "OneTime": {
   "Amount": "50"
 },
 "PaymentMethod": {
   "Name": "Creditcard",
   "Processor": "PaymentHub-Stripe"
 },
 "Settings": {
   "SourceConnector": "FinDock-for-Fundraising"
 }
}

Example of a one-time gift with a tribute from an individual donor

{
 "SuccessURL": "https://www.example.com/success",
 "FailureURL": "https://www.example.com/error",
 "Payer": {
   "Account": {
     "RecordTypeName": "PersonAccount",
     "SalesforceFields": {
       "FirstName": "John",
       "LastName": "Johnson",
       "PersonEmail": "johnjohnson@test.com"
     }
   }
 },
 "OneTime": {
   "Amount": "50"
 },
 "PaymentMethod": {
   "Name": "Creditcard",
   "Processor": "PaymentHub-Stripe"
 },
 "Settings": {
   "SourceConnector": "FinDock-for-Fundraising"
 },
 "PackageActions": {
  "FinDock-for-Fundraising": {
    "CreateGiftTribute": {
      "type": "memorial",
      "honoreeName": "Tribute Honoree",
      "notificationChannel": "email",
      "notificationContactName": "Tribute Recipient",
      "notificationEmail": "tribute@example.com",
      "notificationMessage": "Thank you for your tribute!"
    }
  }
}

Example of a one-time gift from a business donor

{
 "SuccessURL": "https://www.example.com/success",
 "FailureURL": "https://www.example.com/error",
 "Payer": {
   "Account": {
     "RecordTypeName": "Business",
     "SalesforceFields": {
       "Name": "MyBusiness"
     }
   },
   "Contact": {
     "SalesforceFields": {
       "FirstName": "John",
       "LastName": "Johnson",
       "Email": "johnjohnson@test.com"
     }
   }
 },
 "OneTime": {
   "Amount": "50"
 },
 "PaymentMethod": {
   "Name": "Creditcard",
   "Processor": "PaymentHub-Stripe"
 },
 "Settings": {
   "SourceConnector": "FinDock-for-Fundraising"
 }
}

Example of a recurring donation from an individual donor

{
 "SuccessURL": "https://www.example.com/success",
 "FailureURL": "https://www.example.com/error",
 "Payer": {
   "Account": {
     "RecordTypeName": "PersonAccount",
     "SalesforceFields": {
       "FirstName": "John",
       "LastName": "Johnson",
       "PersonEmail": "johnjohnson@test.com"
     }
   }
 },
 "Recurring": {
   "Amount": "50",
   "Frequency": "Monthly",
   "StartDate": "2023-03-12"
 },
 "PaymentMethod": {
   "Name": "Creditcard",
   "Processor": "PaymentHub-Stripe"
 },
 "Settings": {
   "SourceConnector": "FinDock-for-Fundraising"
 }
}

FinDock Payments (MOTO) for Fundraising

With the FinDock Payment component component, agents can accept credit card payments directly from Salesforce by manually entering the donor details into the component. For a full explanation of the setup and supported PSPs, please refer to Configuring FinDock MOTO. For information on how to use the component, see Using FinDock MOTO.

With Salesforce Fundraising, the component can be effectively leveraged when added, for example, to Gift Transaction and Gift Commitment.

When using the component, there are two key implications to keep in mind:

• Recurring requires a schedule: to use MOTO with Gift Commitment, the commitment record must have an active Gift Commitment Schedule record.
• Future gift transactions change: changes made via the component on Gift Commitment automatically update related Gift Commitment Schedule records and change future Gift Transaction records accordingly.

Gift Aid and Fundraising

The Gift Aid for FinDock package is compatible with Salesforce Fundraising with some important caveats.

While the Gift Aid data model remains the same, Person Accounts, rather than Contacts, are central. Therefore, the Gift Aid Declaration component should be added to record layouts for Person Account.

Please also keep in mind Person Account considerations when using Gift Aid package actions via the Payment API, such as explicitly declaring Record Type.

Migrating to Fundraising

If you need to migrate donor and payment data to Fundraising, please refer to our general migration guidance for the essential considerations when planning a migration.

Under normal operating scenarios, the FinDock for Fundraising solution automatically handles record creation and syncing between Gift Transaction and Installment. A new gift transaction triggers a new installment, and vice versa.

Particularly when migrating historical data, you may not want to create new Installment records for all migrated gift transactions. Already closed and collected transactions, for example, may not need corresponding installments.

For this scenario, you can use the advanced setting Disable installment creation for migration to temporarily block installment creation. The setting toggle is under Advanced Settings (below the field mappings) in the source connector setup.