Reference

Donors

The Swiftaid API helps you manage the donor information required for Gift Aid declarations to be created, allowing you to optimise your user experience when the donor is already known to the Swiftaid service and has an authorisation on file. also freeing you and your charities from needing to store the PII necessary to meet HMRC requirements.

Interactions with the Swiftaid API regarding donors are all typically scoped using a unique id for each donor, to obtain this unique id you can fetch it from the API using the donors' email address or phoneNumber.

For the sake of optimisation you may want to store this unique id after your initial query, but this id will remain a consistent reference for this donor between you and Swiftaid and you will receive the same id should you repeat the fetch with the same email address.

Donor Information Matching Flow

Where your donation flow doesn't gather simple unique identifiers like Email address or telephone number that enables a simple lookup for a user unique id the Swiftaid service can now provide matching functionality which will attempt to achieve an unambiguous match to a donor account using a selection of identifiers. To use this endpoint you send through what information you have and the Swiftaid service will work through them in a set order of operation attempting to locate an existing donor account that matches them.

{
  "email": "tony.stark@example.com",
  "phoneNumber": "+447911123456",
  "card": {
    "par": "11111111111111111111111111111",
    "cardholderName": "Mr T Stark",
    "bin": "444400",
    "last4": "4446"
  },
  "address": {
    "postcode": "string",
    "houseNo": "string"
  },
  "donationDate": "2022-04-12T20:07:29.588Z"
}

Where a donor had an active intermediary authorisation with Swiftaid in a previous financial year; within certain circumstances retrospective Gift Aid declarations may be available, for this use case the date the donation was made can be supplied, in general this property can be omitted and the check is made for a donor with an active authorisation for the current financial year.

Where a match is achieved a unique identifier of the match will be returned, this match ID can be used as donor attribution for a subsequent donation.

Authorisation

A donor needs to authorise Swiftaid as a donor intermediary (opens new window) in order to allow Gift Aid declarations to be created, this authorisation covers all donations for the donor to any charity registered with HMRC for Gift Aid and the Swiftaid service. This authorisation needs to be renewed each financial year, that being the period of the 1st March → April 5th (the following year).

The Swiftaid API allows you to query for a given unique id whether an active authorisation is currently on file, if there is no authorisation on file for the donor then you'll need to capture/confirm the donors' current name and address and prompt them with an authorisation declaration that they'll need to agree to, otherwise you can skip this process if there is already an authorisation on file from the donor using another service connected with Swiftaid or a prior login to your service.

Once you've committed the authorisation for a donor they're ready for Gift Aid on any eligible donations made through any platform connected to Swiftaid.

We have reference designs of a UI flow that satisfies HMRC requirements, you can use these with the included assets to help you quickly update your donation flow with compliant Gift Aid functionality:

• Gift Aid flow for single donations (opens new window)
• Gift Aid flow for fundraising donations (opens new window)

Linked Accounts

An account represents permission by a donor to find donations made using that method, for example a donation made using a specific card, phone number or online account identified by an email address.

Payment Account Reference Where donations are being taken using a payment card, Swiftaid allows you to set a payment account reference (PAR) so that donations from the donor can be detected based on the transaction information. PAR is increasingly being supported by payment services with it typically being returned as part of the transaction authorisation data.

Card Account While PAR typically gives a better match we understand that it is not always available and as such Swiftaid can make efforts to match donor accounts based on a combination of other card data such as the last 4 digits and cardholder name in combination with address data.

Phone Number If you additionally capture phone numbers for your users this allows you to store these numbers against the donors' account to enable easier matching with the donors' existing authorisation for mobile based charitable platforms.

Swiftaid does not currently perform a confirmation flow of the phone number, so it is expected that you have verified the user has control of the number before it is set as an account.

Charity on-boarding

In order that that Swiftaid can submit Gift Aid claims to HMRC on behalf of a charity it needs the following:

1. The charity must be registered for Gift Aid with HMRC.
2. Swiftaid must be assigned as a nominee for the charity.
3. A warrant on file from an authorised official of the charity that donations coming to them from your platform are eligible for Gift Aid (opens new window).
4. A shared unique reference number we can use between our platforms to reference the charity, typically we can use HMRC customer number for this purpose.

Nominee assignment

Swiftaid provides a web portal that an authorised official for a charity can use to enrol the charity and get them set-up ready for processing Gift Aid on donations made to them via your service.

If your service collects donations in to an intermediate charity or foundation which then disburses these funds to the individual charities then an authorised official for your intermediate entity must sign-up with Swiftaid.

If your service merely facilitates donations made directly from a donor to a charity then your service will need to direct your charity customers to complete this process directly with Swiftaid as part of your on-boarding process.

Warrant

For the case where you are registering an intermediate entity you can go to Donation sources and then follow the instructions to Add a donation source manually, Swiftaid support will then create the source on your account and send you through a unique customer reference to use.

Where your service is going to have to direct your charity customers through to sign-up with Swiftaid, getting warrants and unique references in place for each is more complicated, so for this case we typically get the Swiftaid charity portal set-up so that your customers can set this up themselves. We do this by adding your service to the list of donation sources that show in the Donation sources page. The charity official is then asked directly by Swiftaid to warrant the donations coming from your platform are eligible for Gift Aid.

When querying charity information from Swiftaid for a given HMRC customer number it returns information including whether the charity has warranted donations from your service.

{
  "warranted": true
}

Donations

Eligibility

A donation needs to meet HMRC eligibility requirements (opens new window) in order to be Gift Aid eligible.

Donor

When a donation is sent to Swiftaid it has to be matched to a specific donor and their Gift Aid intermediary authorisation held within the Swiftaid system in order that a Gift Aid declaration can be created. To match a donation to a specific donor Swiftaid will need the donor property of the donation object to include a unique reference that it knows in association to the donor, E.g. the donor unique id used above to submit authorisation and/or account information.

"donor": {
  "type": "uid",
  "value": "dnr_0123456"
}

Swiftaid currently supports identification of the donor who made a donation by several different unique identifiers, these being

• Donor Id (uid)
• Payment Account Reference (par)
• Email Address (email)
• Phone Number (phone)
• Match Id (match)
• Declaration Id (declaration)

Transaction

In addition to matching the donor it came from Swiftaid will also need to match a donation to the charity to which it intended so that the Gift Aid declaration can be filed correctly. To match a donation to a specific charity Swiftaid will need the transaction property of the donation object to include suitably unique information about the transaction, currently Swiftaid can match donations to charities in several ways:

Direct As part of opening up production access between your service and Swiftaid your service can be added as a donation source to the Swiftaid charity dashboard, this enables charities to register with Swiftaid that your service is a source of donations to them, when they do this they will be asked to input a unique reference related to your service (such as their customer number), you can then use this reference number to directly attribute donations to this charity.

"transaction": {
  "type": "direct",
  "id": "your_unique_reference"
}

HMRC Customer Id When a charity registers for Gift Aid with HMRC they receive a customer number, this takes the form of 1 or 2 letters followed by up to 5 numbers, this can be used to directly attribute donations.

"transaction": {
  "type": "hmrcId",
  "id": "SA12345"
}

Terminal Info It may be the case where specific information about the charity is not known or configurable at the point of donation, such as a contactless card payment terminal. In this case Swiftaid can identify to which charity the donation was made using a combination of identifiers that occur as part of making a card transaction.

"transaction": {
  "type": "terminal",
  "mid": "123456789123456",
  "desc": "merchant*descriptor",
  "tid": "12345678",
  "auth": "123456"
}

Nominee Handled If your service is a nominee for charities collecting Gift Aid on their behalf from HMRC before disbursing funds to individual charities then using the nominee handled transaction reference indicates to Swiftaid that Gift Aid declaration should be to your service rather than individual charities with an option to include a friendly reference to the target charity so when donation information is presented to donors this can be made clear.

"transaction": {
  "type": "nominee",
  "charityName": "Local Church",
  "createDeclaration": true,
  "fileDeclaration": true
}

Setting createDeclaration to true indicates to Swiftaid that your service is expecting Swiftaid to create a Gift Aid declaration from this donation donation data but that your service will handle filing it with HMRC and so Swiftaid will assume that once created it need take no further action on the declaration other than make it available to you.

Setting fileDeclaration to true indicates to Swiftaid that your service is expecting Swiftaid to both create a Gift Aid declaration and then also file this declaration with HMRC, to do this Swiftaid will need to have been assigned as a nominee for your platform with HMRC.

Gross and Net

According with HMRC instruction Gift Aid can only be claimed for the amount of money that reaches the Charity's bank account for a given donation. Where your platform takes processing fees for a transaction before the money is transferred to the charity (rather than invoicing for the value after transferring all of the money) then Swiftaid needs to be informed of the value that reached the charity using netAmount. If the entire donation amount reaches the charity then this field can be omitted and Swiftaid will work purely based on the grossAmount for the donation value.

Amounts should be formatted as a total of currency units, I.e. £5.00 is sent as 500

Currency

A donation needs to include the ISO4217 currency code for the currency it was made in, currently only GBP is supported.

Donation vs settled time

HMRC stipulates that Gift Aid can only be claimed on settled funds, as such Swiftaid will not create a Gift Aid declaration for a donation until a settlementDate is present for any given donation. For the case where there is a delay before settlement is confirmed (like an overnight batch process for example) then the donation can be sent to Swiftaid at the time the donation is made where it will be available to view right away on the Swiftaid donor portal and the settlementDate can then be set later when known, at which point the declaration process will proceed.

Should the settlement process fail for any reason then the donation can be deleted from the service using the Swiftaid API.

Refunds

Should a donor request a refund for a donation given via your charitable platform then you can signal a delete to the Swiftaid API and the appropriate action will be taken to cancel out any declaration that may have been made, and following on from that make any adjustment needed to a future claim for that charity.

Gift Aid Declarations

WARNING

The typical use case of Swiftaid is that once sufficient information is available for a donation in the Swiftaid system it will act as a donor intermediary to automatically create a Gift Aid declaration on the donors' behalf, Swiftaid will also then act as a nominee on behalf of the charity to submit this information to HMRC directly to claim for that Gift Aid.

Some limited provision has been added to the system to give external access to Gift Aid declarations created by Swiftaid, or to allow for the import of externally created Gift Aid declarations but these are designed around specific use cases or require specific agreements in place and you should consult with Swiftaid before basing your integration on these features.

Reading Gift Aid declarations created by Swiftaid

Where your platform has the relevant agreement in place with the charities and you want to do the submission to HMRC yourself it can be enabled that once the declaration is created it is made available for retrieval by your platform rather than being submitted directly by Swiftaid.

The declaration will contain enough information to make a charity claim submission to the HMRC Transaction Engine.

{
  "donationId": "1234567890abcdef",
  "donor": {
    "firstname": "Bob",
    "lastname": "Smith",
    "addressLine1": "Unit 1",
    "addressLine2": "1 High Street",
    "city": "Guildford",
    "county": "Surrey",
    "postcode": "GU1 1AA",
    "country": "UK"
  },
  "nomineeCharityRef": "Local Church",
  "status": "declared",
  "amount": 470,
  "donatedOn": "2018-07-17T10:02:34",
  "matchedRetrospectively": false
}

Retrospective declarations

Retrospective declarations are a special case where a donation has been made in a previous financial year where the donor had an active Gift Aid intermediary authorisation with Swiftaid but the statement for that tax year is not yet closed so Gift Aid declarations can still be created and counted within that previous tax year.

A declaration is considered as having been matched retrospectively when the date of the donation (transaction time value) represents an earlier point in time than the real time the match operation was done to identify the donor.

Importing enduring Gift Aid declarations into Swiftaid

Provided you show the specific type of flow to your donors you can collect from them what is referred to within the legislation as an enduring Gift Aid declaration. The scope of these declarations is limited to between a specific donor and a specific charity but has the benefit of being allowed to go back four tax years and does not require annual renewal by the donor.

Swiftaid still requires a warrant from the target charity to handle enduring declarations, and will reject declarations when no warrant exists. In the sandbox environment a charity with HMRC customer id SA12345 is already "enrolled" so that you can test this functionality.

When donations are submitted to Swiftaid referencing a declaration the system will confirm the HMRC customer number of the charity that is the target of the donation matches that of the declaration before it accepts that donation, the donor information from that declaration is then used when making the Gift Aid submission to HMRC on behalf of the charity.

[
  {
    "id": "string",
    "hmrcCustomerId": "SA12345",
    "startDate": "2017-04-06T00:00:00.000Z",
    "createdDate": "2021-10-14T09:10:03.000Z",
    "sourceRef": "2021/cust_01234.wav",
    "donor": {
      "firstname": "Tony",
      "lastname": "Stark",
      "addressLine1": "14 High Street",
      "addressLine2": "Town Centre",
      "city": "Guildford",
      "county": "Surrey",
      "postcode": "GU1 1AA",
      "country": "UK"
    }
  }
]

As part of supporting enduring declarations donors may write to you when they wish to end the declaration or have changed their name and address, a PATCH operation is provided to allow for updates to a declaration filed with Swiftaid. When a declaration has an end date set; any donations referencing that declaration, dated later than that end date, will be rejected by Swiftaid.

If a donors communicates that they have changed their mind over having given an enduring declaration within their legally allowed cooling off period, or it was filed in error, a DELETE operation is provided. This will remove the declaration from Swiftaid and reverse any Gift Aid claimed against it.