HMRC (Gift Aid) Charity Repayment Claims
A library for charities and CASCs to claim Gift Aid (including Small Donations) from HMRC, (*1)
, (*2)
'Gift Aid' is a UK tax incentive that enables tax-effective giving by individuals to charities
in the United Kingdom. Gift Aid increases the value of donations to charities and Community
Amateur Sports Clubs (CASCs) by allowing them to reclaim basic rate tax on a donor's gift., (*3)
'HMRC Charity Repayment Claims' is a library for submitting Gift Aid claims to HMRC., (*4)
Installation
The library can be installed via Composer. To install, simply add
it to your composer.json file:, (*5)
{
"require": {
"justinbusschau/hmrc-gift-aid": "0.*"
}
}
And run composer to update your dependencies:, (*6)
$ curl -s http://getcomposer.org/installer | php
$ php composer.phar update, (*7)
Some notes on the library and Data Persistance
From the introduction to the IRMark Specification:, (*8)
There is legislation in place that states that in the case of a civil dispute between the
Inland Revenue (IR) and a taxpayer with regards to an Internet online submission, the
submission held by the Inland Revenue is presumed to be correct unless the taxpayer can
prove otherwise. In other words the burden of proof is on the taxpayer. There is therefore
a requirement to enable the IR Online services and software that uses the services to provide
a mechanism to aid a taxpayer to prove whether or not the submission held by IR is indeed the
submission they sent., (*9)
That is a very roundabout way of saying the XML that you submit must include a signiture of some
sort. The signature can be used to prove that what the HMRC received is actually what you
intended to send. HMRC will, in their turn, include a similar signiture in any responses they
send to you. In the case of submissions to the HMRC Government Gateway, this signature is the
IRmark (pronounced IR Mark)., (*10)
It is strongly recommended that both the XML that you send and the XML that you receive should
be stored in case there is any dispute over the claim - be that a dispute over the submission
of the claim or over the content of the claim itself., (*11)
This library will generate the appropriate IRmark signature for all outgoing messages and check
the IRmark on all incoming messages. This library, however, does not attempt to store or in any
way persist any data whatsoever. This means that your application will need to store a number of
pieces of information for use during dispute resolution. Having said that, it is not necessary
to store ALL messages sent to or received from the gateway. The following is a recommended set
of data to be stored by your application., (*12)
-
HMRC Correlation ID This will be generated by HMRC when you send your request and returned
in all subsequent messages. You will also need to supply this correlation ID when submitting
any messages or queries related to the claim. While it is not essential to store this, I do
recommend it., (*13)
-
The Claim Request The communication protocol requires a number of messages to be exchanged
in the course of a claim submission. I recommend storing only the initial claim request as this
is the message that will contain all the claim data. Other messages simply facilitate the
assured delivery of that initial message., (*14)
-
The Claim Response This is not necessarily the first message you get back after sending
your Request - there will be polling and other protocol messages first. HMRC will first verify
the validity of the submitted claim (note this is verifying that the structure of the
message is valid and that the data conforms to the required standards). Once this is done you
will receive a response message with an acknowledgement similar to this:, (*15)
HMRC has received the HMRC-CHAR-CLM document ref: AA12345 at 09.10 on 01/01/2014. The
associated IRmark was: XXX9XXX9XXX9XXX9XXX9XXX9XXX9XXX9. We strongly recommend that you
keep this receipt electronically, and we advise that you also keep your submission
electronically for your records. They are evidence of the information that you submitted
to HMRC.
See the sample source code below to see how and where to extract the above data from the
library., (*16)
Basic Usage
Preparing your data
The first thing you need is to identify both the organisation(s) and the individual
submitting the Gift Aid claim., (*17)
The Vendor data identifies the company and software product used to submit the claims. Each
vendor is assigned a Vendor ID and is required to identify the software that will submit the
claims. To obtain an ID, please see the
Charities Online Service Recognition Process., (*18)
$vendor = array(
'id' => '4321',
'product' => 'ProductNameHere',
'version' => '0.1.2'
);
The Authorised Official is an individual within the organisation (Charity or CASC) that
has been previously identified to HMRC as having the authority to submit claims on behalf of
the organisation. That individual will register for an account to log in to Charities Online
and the user ID and password are required when submitting claims. The additional data sent
with the claim - name and contact details - must be consistent with that held by HMRC., (*19)
$authorised_official = array(
'id' => '323412300001',
'passwd' => 'testing1',
'title' => 'Mr',
'name' => 'Rex',
'surname' => 'Muck',
'phone' => '077 1234 5678',
'postcode' => 'SW1A 1AA'
);
Each Charity or CASC that is registered with HMRC will have two identifiers. The first is the
Charity ID which is a number issued by HMRC when registering as a charity. The second is the
Charities Commission Reference which is issued by the relevant charity regulator. We also
need to know which regulator the charity is registered with., (*20)
$charity = array(
'name' => 'A charitible organisation',
'id' => 'AB12345',
'reg_no' => '2584789658',
'regulator' => 'CCEW'
);
Finally, you will need to build a list of all donations for which you want to claim a Gift Aid
repayment. For each donation you will also need to know the name and last known address of the
donor., (*21)
$claim_items = array(
array(
'donation_date' => '2014-01-01',
'title' => 'Mr',
'first_name' => 'Jack',
'last_name' => 'Peasant',
'house_no' => '3',
'postcode' => 'EC1A 2AB',
'amount' => '123.45'
),
array(
'donation_date' => '2014-01-01',
'title' => 'Mrs',
'first_name' => 'Josephine',
'last_name' => 'Peasant',
'house_no' => '3',
'postcode' => 'EC1A 2AB',
'amount' => '876.55'
)
);
And now that you have all the data you need, you can submit a claim., (*22)
Preparing to send a request
This applies to all cases below. Whenever you need to send something to HMRC you will need to
prepare the gaService object as shown here., (*23)
$gaService = new GiftAid(
$authorised_official['id'],
$authorised_official['passwd'],
$vendor['id'],
$vendor['product'],
$vendor['version'],
true // Test mode. Leave this off or set to false for live claim submission
);
$gaService->setCharityId($charity['id']);
$gaService->setClaimToDate('2014-01-01'); // date of most recent donation
$gaService->setAuthorisedOfficial(
new AuthorisedOfficial(
$authorised_official['title'],
$authorised_official['name'],
$authorised_official['surname'],
$authorised_official['phone'],
$authorised_official['postcode']
)
);
$gaService->setClaimingOrganisation(
new ClaimingOrganisation(
$charity['name'],
$charity['id'],
$charity['regulator'],
$charity['reg_no']
)
);
Submitting a new claim
Once you have prepared the gaService object and collected your donations and donor data, you
are ready to send the claim., (*24)
$gaService->setCompress(true);
$response = $gaService->giftAidSubmit($claim_items);
if (isset($response['errors'])) {
// TODO: deal with the $response['errors']
} else {
// giftAidSubmit returned no errors
$correlation_id = $response['correlationid']; // TODO: store this !
$endpoint = $response['endpoint'];
}
if ($correlation_id !== NULL) {
$pollCount = 0;
while ($pollCount < 3 and $response !== false) {
$pollCount++;
if (
isset($response['interval']) and
isset($response['endpoint']) and
isset($response['correlationid'])
) {
sleep($response['interval']);
$response = $gaService->declarationResponsePoll(
$response['correlationid'],
$response['endpoint']
);
if (isset($response['errors'])) {
// TODO: deal with the $response['errors']
}
} elseif (
isset($response['correlationid']) and
isset($response['submission_response'])
) {
// TODO: store the submission_response and send the delete message
$hmrc_response => $response['submission_response']; // TODO: store this !
$response = !$gaService->sendDeleteRequest();
}
}
}
Submitting adjustments with a claim
If you submit a claim and then subsequently need to reverse or refund a donation for which
you have already claimed Gift Aid, you will need to submit an adjustment with your next claim.
The adjustment value is set to the value of the refund you have already been paid for the
refunded donation. In other words if you claim Gift Aid on a £100.00 donation you will be paid
£25.00 by HMRC. If you subsequently refund that £100.00 you submit an adjustment to HMRC for
the £25.00., (*25)
Prepare the gaService object and your claim items as usual, but before calling giftAidSubmit
add the adjustment as shown below., (*26)
// submit an adjustment to a previously submitted claim
$gaService->setGaAdjustment('34.89', 'Refunds issued on two previous donations.');
Querying a previously submitted claim
Prepare the gaService object in the usual way and then call requestClaimData. This will
return a list of all previously submitted claims with status. It's a good idea to delete older
claim records - if nothing else it prevents having to download them all every time you need to
call requestClaimData., (*27)
$response = $gaService->requestClaimData();
foreach ($response['statusRecords'] as $status_record) {
// TODO: deal with the $status_record as you please
if (
$status_record['Status'] == 'SUBMISSION_RESPONSE' AND
$status_record['CorrelationID'] != ''
) {
$gaService->sendDeleteRequest($status_record['CorrelationID'], 'HMRC-CHAR-CLM');
}
}
For more information on the Gift Aid scheme as it applies to Charities and Community Amateur
Sports Clubs, and for information on Online Claim Submission, please see the
HMRC website., (*28)
For information on developing and testing using HMRC Document Submission Protocol, please see
HMRC Software Developers., (*29)
Wallogit.com
