For admins and SIs - Gift Aid setup

The following sections are for administrators and system integrations who need to set up FinDock and Gift Aid.

Install Gift Aid extension

As we are focusing just on Gift Aid here, we’ll assume you have already gone through the paces of setting up FinDock Core and ProcessingHub. Once that is done and dusted, you can install and activate the Gift Aid. The installation procedure for the Gift Aid extension is the same as with other FinDock packages.

If you are using the new FinDock Setup* tab, you can go to Payment Processors & Methods and install Gift Aid from there.

If you are using the classic Setup tab, first go to the Installer in install the Gift Aid package.

To activate Gift Aid package in the "classic" setup:

1. Launch the FinDock app and click the Setup tab.
2. Click the Activate/Deactivate tab.
3. Locate the two Gift Aid entries in the list for PSP and Source.
   
4. Click the toggle in the STATUS column of both entries to activate them.
5. Click the Payment Methods button in the ACTION column of the PaymentHub-GiftAid entry.
6. Click the Active toggle to active the Gift Aid payment method, and then close the window.
7. Click the Deploy config button to roll out your configuration.

Assign permissions for Gift Aid

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

In addition, you need to give Gift Aid operations users read/write permission to all fields on the Gift Aid Declaration and Gift Aid Distribution objects. This can be done by creating your own permission set or changing profile permissions. Both objects have a Master-Detail relationship to standard Salesforce objects, so manual action is required.

Check Salesforce Period

According to HMRC rules, Gift Aid can only be claimed in a certain time period. This is done by counting back four years from the start of the current fiscal year.

This calculation is handled automatically by FinDock during the Gift Aid claim process using the Current Fiscal Year custom setting. When the Gift Aid package is installed (or updated), FinDock creates a Current Fiscal Year record (or updates an existing record in the case of a package update). The Fiscal Year defined by the Salesforce Period object is used to set the custom setting.

If for some reason the Period object is not configured, FinDock uses the first of January of the current year instead. After the initial record is created, FinDock automatically checks and updates the Current Fiscal Year custom setting as part of the Gift Aid claim submission process.

Add a target for Gift Aid claims

To send a Gift Aid claim file to HMRC, you need to create a target (account) which defines your login details and endpoint for the HMRC upload service.

To add a Gift Aid target:

Gift Aid target settings

Adjust Gift Aid settings

After you are finished with the Gift Aid target, you can adjust the general Gift Aid settings as needed. The default values are the standard recommendations from HMRC, so you can skip this procedure unless you have specific requirements. The available settings are:

• Number of cooling off days: The HMRC requires a cooling-off period (normally 30 days) for oral Gift Aid declarations before it can be used to claim Gift Aid. This cooling-off setting only applies to oral declarations.
• Max installments per payment schedule: The maximum number of installments that can be included in a single submission. HMRC advises not to exceed 500,000 claims. FinDock recommends staying well below this limit.

To modify Gift Aid settings:

Add Gift Aid component to page layout

The Gift Aid extension includes a Lightning Component called Gift Aid Declarations that shows the Gift Aid status of the donor on a specific date. The component allows you to create a new declaration as well as close all declarations for the contact.

To add the Gift Aid component:

1. Go to a Contact record.
2. Under the Salesforce settings cog in the upper right corner, select Edit Page.
3. Find the Gift Aid component under the custom (managed) list on the left or search for “Gift Aid.”
4. Drag the Gift Aid component to your Lightning page layout and click Save.

The Gift Aid Declarations component can be placed on the following objects:

• Contact (Standard)
• Gift Commitment (Fundraising)
• Gift Commitment Schedule (Fundraising)
• Gift Transaction (Fundraising)
• Installment (FinDock)
• Opportunity (Standard)
• Person Account (Standard)
• Recurring Donation (Nonprofit Success Pack)
• Recurring Payment (FinDock)

For more information on page layouts, see the Salesforce Page Layouts article.

Using the Payment API for Gift Aid declarations

If you are using the FinDock Payment API to collect donations through a webform, for example, you can include Gift Aid actions in the form integration. Below are examples for creating and closing Gift Aid declarations.

Gift Aid declarations added via the FinDock Payment API go through automatic normalization of postal codes. The normalization adds capitalization and spacing to the postal code to conform to HMRC requirements if:

• The overseas indicator is false, and
• The provided string results in a valid UK post code after normalization.

If neither is true, then the provided postal code is left as is. (You can always find the original postal code string in the RAW message field on the Inbound Report record.)

Create a Gift Aid declaration

Create a Gift Aid declaration as part of a new payment.

{
    "SuccessURL":"http://success.com",
    "FailureURL":"http://failure.com",
    "Payer":{
        "ContactId": "0032p00002djAK9AAM"
    },
    "PackageActions": {
        "PaymentHub-GiftAid": {
          "CreateGiftAidDeclaration": {
            "dateMade": "2024-12-15",
            "startDate": "2025-01-01",
            "endDate": "2025-12-31",
            "houseNameOrNumber": "12",
            "postalCode": "L68 0AQ",
            "overseas": "false",
            "acquisitionMethod":"Written"
          }
        }
      },
   "Settings": {
       "SourceConnector": "PaymentHub"
    }
}

Close all Gift Aid declarations

Stop collecting Gift Aid by closing all Gift Aid declarations as part of a new payment.

{
    "SuccessURL":"http://success.com",
    "FailureURL":"http://failure.com",
    "Payer":{
        "ContactId": "0032p00002djAK9AAM"
    },
   "PackageActions": {
        "PaymentHub-GiftAid": {
          "CloseAllGiftAidDeclarations": {
            "closeDate": "2024-12-31",
            "closeReason": "Unemployed",
            "comments": "Free text"
          }
        }
      },
   "Settings": {
       "SourceConnector": "PaymentHub"
    }
}