Skip to main content

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 focussing just on Gift Aid her, 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.
    Gift Aid activation
  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 ProcessingHub tile.
  3. Click the Targets tab.
  4. Click Add Target to create a new 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

SettingDescription
Authorised Official First NameThe first name of the person within your organisation authorised to work with HMRC.
Authorised Official Phone NumberThe phone number where HMRC can reach the Authorised Official.
Authorised Official Postal CodeThe postal code of the Authorised Official.
Authorised Official SurnameThe surname of the person within your organisation who is authorised to work with HMRC.
Charity Registration NumberYour charity registration number with the Charity Commission.
Charity RegulatorThe 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 Charities ReferenceYour charity reference at HMRC. For Gift Aid testing purposes, use the HMRC standard testing reference: AB12345
Charity NameThe official name of your charity as registered with HMRC.
Test ModeIf Test Mode is enabled, files are sent to the HMRC test API endpoint.
Upload Copy To ChatterIf 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.
XML API Username & PasswordEnter the credentials you obtained from HMRC for the use of the HMRC online services. For Gift Aid testing purposes, use the HMRC standard testing credentials: XML API Username = 323412300001, XML API 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 days cooling-off period: For oral Gift Aid declarations, HMRC requires a cooling-off period before the declaration can be used to claim Gift Aid. This setting defines the cooling-off period for oral Gift Aid declarations only.
    • 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.

Gift Aid declaration compnent

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.

This component can also be placed on the following objects:

  • Installment
  • Opportunity
  • Recurring Donation

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.

Create a Gift Aid declaration#

Create a Gift Aid declaration as part of a new payment. All writable fields on Gift Aid Declaration can be included in the CreateGiftAidDeclaration block.

{    "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"    }}