# 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 for a 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"
  }
}

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:

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

# 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 and unique reference sharing

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 provide a unique customer reference they were given by your platform and to warrant the donations coming from your platform are eligible for Gift Aid.

In each case the shared unique reference is what we use to reference specific charities in communications between our platforms such as within the Transaction object when sending through donations.

# Do I have to create customer references?

This is something you will need to do only where you are directing your charity customers to register with Swiftaid. Ultimately we need the context to know we are talking about the same charity when you send donation information in through the API. Typically how this works is to present the reference (being either an existing reference from your service or a new one generated for the purpose) to your charity user when you direct them to sign-up with Swiftaid so they can make a note of it and enter it in to Swiftaid when asked.

About customer references:

  • References must be unique per charity.
  • Swiftaid automatically isolates them by service, so you don't need to consider the case where you might conflict with another service.
  • The add source flow can show example input and impose input guards if you have rules around the format of your reference.
  • The add source flow can link to a help article or location on your service dashboard to help the user find their reference.

Recommendations:

  • Give them a recognisable prefix.
  • Keep them short.
  • Make them easy to read using something like BASE32.

# 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)

# 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 two 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"
}

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

Once sufficient information is available for a donation in the Swiftaid system it will automatically create a Gift Aid declaration on the donors' behalf. In the general case Swiftaid will then submit this information to HMRC working on behalf of the charity to claim for that Gift Aid, but 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 to retrieve 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"
}