# Documentation

# Introduction

Swiftaid is a service that fully automates the process of creating Gift Aid declarations on behalf of donors and filing Gift Aid charitable claims with HMRC on behalf of charities.

Swiftaid is designed to sit alongside and complement a charitable giving service, so if you are currently building a solution that allows people to give money to charity then integrating the Swiftaid service will unlock the ability for your eligible users to boost the money received by good causes they are choosing to donate to at no cost to themselves.

Discourse Swiftaid community (opens new window)

Join our Swiftaid community, we're always happy to help and answer any questions.

# Getting Started

  1. Reach out to dev support to get a sandbox account.
  2. Head over to our active API specification where you can use your sandbox keys to try out the API.

# Authentication

The Swiftaid API implements the OAuth 2.0 (opens new window) client credentials (opens new window) flow for authorising other applications to interact with it based on them having valid client id and client secret values.

WARNING

The client credentials flow is designed for backend to backend interaction and it is critical that client secrets are never included in public (mobile or browser-based) applications.

# How it works

  1. Your application authenticates with the Swiftaid Authorization Server using its Client ID and Client Secret (/oauth/token endpoint).
  2. The Swiftaid Authorization Server validates your Client ID and Client Secret.
  3. The Swiftaid Authorization Server responds with an Access Token.
  4. Your application can use the Access Token to call the Swiftaid API.
  5. The Swiftaid API responds with requested data.

# Example authorisation flow

# Request Token

To access the Swiftaid API, you must request an Access Token for it. To do so, you will need to POST to the token URL.

curl --request POST \
  --url 'https://auth.swiftaid.co.uk/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data audience=https://sandbox.swiftaid.co.uk/integrations/v1

Parameters

Parameter Name Description
grant_type Set this to "client_credentials".
client_id Your application's Client ID.
client_secret Your application's Client Secret.
audience The audience for the token, which is the Swiftaid API. The example includes the address for the sandbox instance of the API.

# Response

If all goes well, you'll receive an HTTP 200 response with a payload containing access_token, token_type, and expires_in values:

{
 "access_token":"eyJz93a...k4laUWw",
 "token_type":"Bearer",
 "expires_in":86400
}

# Call the Swiftaid API

To call the Swiftaid API from your application, you must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

curl --request GET \
  --url 'https://sandbox.swiftaid/co.uk/integrations/v1/donors?type=email&value=bruce.banner@example.com' \
  --header 'authorization: Bearer ACCESS_TOKEN' \
  --header 'content-type: application/json'

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

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

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

Before donations can be received from your platform the charity has to add your platform as a donation source in their Swiftaid charity dashboard, this is primarily because they have to warrant that donations coming from your platform are eligible for Gift Aid (opens new window), during that process we can ask for a unique reference which we can then use to reference the charity in communications between our platforms such as when sending through donations in the Transaction object.

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

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

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