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.

Installing and activating Gift Aid

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 package. The installation procedure for the Gift Aid extension is the same as with other FinDock packages, so just go on over to the FinDock Installer to take care of that.

The process for activation, however, is slightly different.

To activate the Gift Aid package:

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.

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 permissions for Gift Aid

For the Gift Aid extension itself, you need to assign the GiftAid FLS permission to the integration user (used for ProcessingHub and WebHub) and for operations users who work with Gift Aid.

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.

To manage Gift Aid declarations through the Payment API, for example, using FinDock Giving Pages, you need to also give the integration user read/write permission to all fields on the Gift Aid Declaration object.

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 create a Gift Aid target:

1. Launch the FinDock app and click the Setup tab.
2. Scroll down and click the PaymentHub-GiftAid tile.
3. Click Create Target.
   
4. On the next screen click Add Target.
   
5. Give the Gift Aid target a clear, transparent name and select the target type PaymentHub GiftAid.
6. Fill in the target settings. Each setting has a tooltip to help you fill in the correct information. See the table below for additional information.
7. Click Save when you are ready.

Gift Aid target settings

Setting	Description
Authorised Official First Name	The first name of the person within your organisation authorised to work with HMRC.
Authorised Official Phone Number	The phone number where HMRC can reach the Authorised Official.
Authorised Official Postal Code	The postal code of the Authorised Official.
Authorised Official Surname	The surname of the person within your organisation who is authorised to work with HMRC.
Charity Registration Number	Your charity registration number with the Charity Commission.
Charity Regulator	The acronym of your regional Charity Regulator. Enter CCEW (Charity Commission for England and Wales), CCNI (Charity Commission for Northern Ireland) or OSCR (Office of the Scottish Charity Regulator).
HMRC Reference	Your charity reference at HMRC. For Gift Aid testing purposes, use the HMRC integration testing credentials reference: AB12345
Charity Name	The official name of your charity as registered with HMRC.
Test Mode	If Test Mode is enabled, files are sent to the HMRC test API endpoint.
Upload Copy To Chatter	If enabled all files exchanged with HMRC are uploaded to Chatter. If disabled, only the Submission file and HMRC receipt are uploaded to Chatter. When in Test Mode, the uncompressed submission file is uploaded to Chatter, otherwise the compressed version is uploaded.
Username & Password	Enter your 12-digit user ID and the password for the HMRC online services. For Gift Aid testing purposes, use the HMRC integration testing credentials (Username = 323412300001, Password = testing1)

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.

To modify Gift Aid settings.

1. In the FinDock app, click the Setup tab.
2. Scroll down and click the PaymentHub-GiftAid tile.
3. Adjust the settings as needed.
   • 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.
4. Click Save when you are done.

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

info

If you are using Giving Pages, you can include an option for donors to declare Gift Aid under the payment method configuration for the page.

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": "2019-12-15",
            "startDate": "2021-01-01",
            "endDate": "2021-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": "2020-12-15",
            "closeReason": "Unemployed",
            "comments": "Free text"
          }
        }
      },
   "Settings": {
       "SourceConnector": "PaymentHub"
    }
}