Skip to main content

Installing and configuring Gift Aid


The GiftAid for FinDock extension is available as a single package that contains both the ability to register the declarations, and file the claims with HMRC. Install the package in Salesforce using the install link provided to you. The procedure for installation is the same as for FinDock Extensions as described in Installing FinDock Packages.


The process for activation might seem a little different than other FinDock packages, this is because the Gift Aid is both a Source and a Payment Extension. Hence, the activation tab will contain two different records for Gift Aid.

To activate the GiftAid package, peform the following steps:

  1. Navigate to the FinDock setup page by opening the App Launcher (the 3×3 grid button on the top left of the page, just below the Salesforce cloud logo), enter “FinDock” in the search box and click the FinDock app and select Setup in the navigation.
  2. Click the Activate/Deactivate tab.
  3. Locate the 2 GiftAid related records in the list of available packages
    Gift Aid setup related records
  4. Activate the GiftAid-Source package by clicking the Status Toggle, After activation you will see a Green Success message at the top of the list.
    Gift Aid source successfully activated
  5. Next, activate the PaymentHub-GiftAid record. Again, you will see a green Success Message.
  6. Now that both GiftAid packages are successfully activated, we can activate the GiftAid payment method. Next to the PaymentHub-GiftAid Status toggle, click the "Payment Methods" Button.
  7. On the dialog, click the Activate button, and after activation, click the Default Toggle. Your GiftAid extension is now fully activated and ready to be used.
    Gift Aid payment method



Since our June '19 release the GiftAid for FinDock package comes with a permission set named GiftAid FLS which can be assigned to Gift Aid users. This permission set provides a user with extra permissions need in order to use the GiftAid for FinDock package. Permissions to the objects 'Gift Aid Declaration' and 'Gift Aid Distribution Scenario' aren't included in this permission set. So you still need to give your users access to these objects and fields by creating your own permission set or by changing the profile permissions. The underlying reason for this is a Salesforce limitation which prevents Managed Packages, like FinDock, to add permission sets which grants users access to a custom object with a Master-Detail relationship to a standard object. Both 'Gift Aid Declaration' and 'Gift Aid Distribution Scenario' have a Master-Detail relationship to a standard object.

Permissions when using Advanced Gift Aid#

When using 'Advanced Gift Aid' make sure that your users have read/write access to the following fields on Gift Aid Declaration. You can manage this in profiles or permission sets:

  • End Date
  • Confirmation Date
  • Close Reason
  • Cooling Off Period End Date
  • In Cooling-off Period
  • Valid Now

If you are planning to use the Payment API for managing the Gift Aid Declarations, then also grant your Salesforce Site Guest User with:

  • Create & Update Object Access on Gift Aid Declaration
  • Read/write Field Level Security on all fields of Gift Aid Declaration

Creating a Gift Aid Target#

To upload the Gift Aid Claim file with HMRC, you will need to create a Target whichs holds the login details and end-point for the HMRC upload service.

Target creation is managed through the ProcessingHub setup page. To create a new target and configure it, follow these steps in order:

  1. Navigate to the FinDock setup page by opening the App Launcher (the 3×3 grid button on the top left of the page, just below the Salesforce cloud logo), enter “FinDock” in the search box and click the FinDock CPM app and select Setup in the navigation.
  2. Click on the ProcessingHub tile to open up the ProcessingHub setup page.
  3. Click on the Targets tab.
  4. Click the Add Target button to create a new target.
  5. On the New Target dialog, give this Target the name of one of the accounts you wish to configure.
  6. Select the Target type: “PaymentHub GiftAid”
  7. Click Save to store the Target.

Creating new Gift Aid target

Configuring the Target#

After you have created one or more targets, we can configure all their settings. In the list of targets, click the arrow icon, and click Settings. The settings screen for this particular target is opened. For Gift Aid, all fields are mandatory.

Gift Aid target

  • Authorized Official First Name: The First name of the person within your organisation who is authorised to deal with HMRC.
  • Authorized Official Phone Number: The phone number on which HMRC can reach the Authorized Official.
  • Authorized Official Postal Code: The postal code of the Authorized Official.
  • Authorized Official Surname: The Surname name of the person within your organisation who is authorised to deal with HMRC.
  • Charity Registration Number: Your charity registration number.
  • Charity Regulator: The acronym of your Charity Regulator, please use: - CCEW, for Charity Commission for England and Wales - CCNI, for Charity Commission for Northern Ireland - OSCR, for the Office of the Scottish Charity Regulator
  • HMRC Charities Reference: Your charity reference at HMRC.
  • Charity Name: The name of your Charity as know by HMRC.
  • Record per file: The maximum numbers of records per file allowed by HMRC is 500 000.
  • Test Mode: If Test Mode is enabled, files are send to the HMRC Test end-point. Please note that the HMRC test end-point does not provide content validation.
  • 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. In all cases, only compressed submission files are send to HMRC.
  • XML API Password and XML API Username: Please fill with the credentials you have obtained from HMRC for the use of the HMRC online services. For information about the enroll can be found here

Gift Aid setup#

When Advanced Gift Aid is enabled, our solution comes with a Gift Aid setup which can be opened from the FinDock setup from the PaymentHub-GiftAid tile.

Gift Aid setup

On this page you can specify:

  • The duration of the cooling-off period for oral gift aid declarations. The defalt is 30 days, which is the official duration. Based on industry best practices we recommend to not change this value.
  • The maximum number of installments that will be included in a payment schedule and offered to HMRC at once. The default is 250.000, which is the HMRC recommendation. HMRC advises not to offer more than 500.000 claims in one run.

Configure page-layouts#

When you make use of the Advanced Gift Aid you need to make use of a Lightning Component "Gift Aid Declarations' that:

  • Shows Gift Aid status on a specific date, today by default.
  • Allows for creating a new Gift Aid Declaration
  • Allows for closing all Gift Aid Declarations.

Gift Aid declarations

This component can be placed on: Contact Record Page, Installment Record Page, Opportunity Record Page, NPSP Recurring Donation Record Page. In case of another page than Contact, the primary lookup to Contact will be used as Contact.

When you still use the Standard Gift Aid solution (FinDock for GiftAid installed before November '19 and never enabled Advanced Gift Aid), the following is important:

  • You need to make the new Gift Aid Declaration object visible to the end-user and to add the Gift Aid Declaration Related List to the active Contact Page-layout.
  • You need to make the new Gift Aid related fields on the Installment object visible to the end-user, make sure to add them to the relevant page-layouts on the Installment Object.
  • You won't be able to make use of the Lightning component as described above.

For more information on page-layouts and how to configure/change page-layouts, see the Salesforce Page Layouts article.

Global Apex Class GiftAid#

This class can be used to further automate and customize Gift Aid logic. It contains the following methods. Method and parameters describe the functionality:

  • Global static void closeAllGiftAidDeclarations(Id contactId, Date closeDate, String closeReason, String comments)
  • Global static gaid.GiftAid.Status getGiftAidDeclarationStatus(Id contactId, Date onDate)
  • Global static Boolean hasValidGiftAidDeclaration(Id contactId, Date onDate)

gaid.GaidAid.Status values are: global enum Status {InCoolingOffPeriod, NotValid, Valid}