Charities Online Service
Technical Pack and Test Service Guidance
Contents
Introduction
Getting Started
Test and Live Services
3
3
LTS
Gateway Reflector Service
Live
4
5
7
8
9
9
9
9
9
9
9
10
10
11
Recognition
Donor Information
GAD Title
GAD Postcode
GAD Total
Other Guidance
Converting a password into MD5
Compression
Known Issues
Support and contact information
Change History
V1.1
2
23/09/2015
Introduction
This document aims to help developers create software to submit online Gift Aid Claims via the
XML channel.
The XML file must:




be valid to the schemas and schema documentation that can be found in the RIM Artefacts
be valid to the Charities Online Service Non-Form Validation Rules
contain the correct IRmark - This is a security hash that must be calculated and included with
every submission to HMRC. For more information on the IRmark see the technical pack: HMRC
IRmark
Contain valid test credentials when using the test service (and live credentials for the live
service).
The XML file is submitted to HMRC through the Government Gateway. The XML instance is sent
via a HTTP 1.1 request to the Government Gateway server. Please see the Gateway Reflector
Service section for more information.
Getting Started
You should register with us as a software developer using the online form
In return, you will be provided with a unique 4 digit 'Vendor ID' and also the credentials necessary
to access the test services. These consist of a Username, Password and HMRC Charities reference
which must be present in your XML file for submissions to the Gateway Reflector Service.
V1.1
3
23/09/2015
Test and Live Services
We do not provide an end to end test service so as part of your development you will have to use
the 2 separate services – Local Test Service and Independent Software Vendor site which are
described below:
 Local Test Service (LTS)
This is a locally installed application which allows you to test the claim data or ‘Body’ of the
submission against the Gift Aid repayment schema and business rules (found in the RIM
Artefacts) in your own environment. It is important that you follow the installation instructions
in the document ‘Installing and running the Local Test Service on Windows’.
Note: When downloading the LTS you will need to use your 4 digit Vendor ID.
When you run the Update Manager, you will see that there are 2 sets of artefacts available for
download as shown in the diagram below:


schema (v1.0) became obsolete on 5th April 2015 so you don’t need to install these
artefacts
schema (v2.0) is the current version in the Live service so these are the artefacts you
need to install and against.
Responses will be returned based on the outcome of your submission indicating if the file has
passed or failed validation. The application WILL NOT perform a full validation on the
GovTalkHeader. Please make sure that you include the correct Namespace in your submission.

xmlns=http://www.govtalk.gov.uk/taxation/charities/r68/2
When testing to LTS you must include and populate the <GatewayTimeStamp> element with
your own timestamp in the GovTalkHeader of your file as this is used as part of the validation.
For example: <GatewayTimestamp>2012-11-15T10:05:59.005</GatewayTimestamp>
When sending returns to the Live service, you should either include an empty
<GatewayTimeStamp> element or omit the element altogether as this will be populated by
Gateway.
V1.1
4
23/09/2015
The service will generate the error responses found in both the Charities SpecDoc and the
Non-Form Validation Rules.
As the condition that returns error code 7020 cannot be recreated in LTS, this message can be
triggered when a submission using message class HMRC-CHAR-CLM is received containing an
Agent ID with the first four characters of the Claim Number set to 7020.
error code
Location
Condition
error message
Error returned in
Unmatched Agent/Nominee Reference
7020
/R68/AgtOrNom/RefNo
For single charity claims submitted by an Agent/Nominee, the HMRC Charities Agent
Reference associated with the enrolment is not the same as the Agent Reference in the
body of the submission.
Agent/Nominee details do not match those of the enrolled Agent/Nominee.
LTS and Live
 Independent Software Vendor Site (ISV) also known as Gateway Reflector
Service
In the 'Live' environment submissions are made to the Government Gateway, using the
Government Gateway Submission Protocol: 3.1 and the ISV service replicates this for test
submissions although only the ‘Header’ is validated.
Messages are transported across the network using the Hypertext Transport Protocol (HTTP)
so applications must be capable of generating HTTP 1.1 POST requests and receiving and
interpreting HTTP 1.1 response messages.
The URL for submissions to the ISV service is: https://secure.dev.gateway.gov.uk/submission
The URL for the Poll messages to the ISV service is: https://secure.dev.gateway.gov.uk/poll
Please ensure you use the correct Namespace (see LTS section above) <Class> and
<GatewayTest> in the XML you are submitting. You can find this information in the Charities
Online Service Non-Form Validation Rules
You must use the following test credentials when submitting to the ISV service. These should
be included as follows:
<SenderDetails>
<IDAuthentication>
<SenderID>323412300001</SenderID>
<Authentication>
<Method>clear</Method>
<Role>principal</Role>
<Value>testing1</Value>
</Authentication>
</IDAuthentication>
</SenderDetails >
.
.
.
<Keys>
V1.1
5
23/09/2015
<Key Type="CHARID">AB12345</Key>
</Keys>
In order to submit a claim to HMRC, your application must have a ‘conversation’ with Gateway and
this is described as below:
(1) You send the submission to Gateway using the submission_request message.
The URL for submissions to the ISV service is: https://secure.dev.gateway.gov.uk/submission
The URL for submissions to the Live service is: https://secure.gateway.gov.uk/submission
(2) Gateway ensures that the submission is well formed XML and checks that the credentials are
valid. If there is a problem with the credentials then a 1046 error is returned ‘Failure. The
supplied user credentials failed validation for the requested service’.
If the credentials are correct then Gateway issues a submission_acknowledgement message
containing a unique CorrelationID. This is confirmation that your submission was received and
accepted by Gateway. In the Live service, Gateway then automatically forwards the ‘body’ of
the submission to HMRC to be validated.
(3) You then use the CorrelationID to enquire to the Gateway about the status of the submission
using a submission_poll message.
The URL for the Poll messages to the ISV service is: https://secure.dev.gateway.gov.uk/poll
The URL for the Poll messages to the Live service is: https://secure. gateway.gov.uk/poll
(4) You should continue to issue submission_poll messages to Gateway until Gateway is able to
generate either a submission_response or submission_error message. You may have to send
this message a number of times before you receive a reply if the file is large or if the system is
busy.
(5) If the return is successfully validated you will receive an XML submission_response message –
it is important that you view and understand the information in this message.
(6) If the submission is rejected a submission_error message will be generated, advising of the
reason for the rejection
(7) If a submission_response or submission_error message is not received after a reasonable
length of time, you should consider temporarily ending the conversation and re-starting at a
later time using the same CorrelationID
(8) Once a submission_response or submission_error message has been returned, a
delete_request message should be issued to confirm that the Gateway “conversation” can be
closed. Issuing a delete_request does NOT prevent the original submission from being sent to
the HMRC system, it only deletes the submission_response or submission_error message
from Gateway.
V1.1
6
23/09/2015
There are examples of the different Gateway messages in the Charities technical specifications:
valid xml samples
 Live Service
To make a live claim, charities must sign up and enrol for the online service –
https://www.gov.uk/claim-tax-back-on-donations-using-charities-online
The charity will receive their gateway credentials for their HMRC reference which consist of a
Username and password. These are used to populate the following elements in a submission to
the live Charities online service:
<SenderDetails>
<IDAuthentication>
<SenderID>Username</SenderID>
<Authentication>
<Method>clear</Method>
<Role>principal</Role>
<Value>Password</Value>
</Authentication>
</IDAuthentication>
</SenderDetails>
.
.
.
<Keys>
<Key Type="CHARID">Charity’s HMRC Reference</Key>
</Keys>
For an individual charity submission, the HMRC charities reference <HMRCref> in the R68 claim is
also termed the Charity ID and is used for the <Keys> elements in the GovTalkDetails and
IRheader. The same reference is therefore used in the following places:
/GovTalkMessage/GovtalkDetails/Keys/Key/@Type
/IRheader/Keys/Key/@Type
/GovTalkMessage/Body/IRenvelope/R68/Claim/HMRCref
Live submissions should also contain your 4 digit 'Vendor ID', product name and product version in
the <ChannelRouting> as shown below:
<ChannelRouting>
<Channel>
<URI>Your Vendor ID</URI>
<Product>Your Product Name</Product>
<Version>Your Product Version</Version>
</Channel>
</ChannelRouting>
V1.1
7
23/09/2015
Recognition
If you would like the output from your software to be recognised and for your company details to
be published on the GOV.UK website https://www.gov.uk/government/publications/charitiesonline-commercial-software-suppliers/charities-online-commercial-software-suppliers you should
follow the instructions in the document Recognition process for the charities online service: 1.6
V1.1
8
23/09/2015
Donor information

GAD title - /R68/Claim/Repayment/GAD/Donor/Ttl
This is an optional element and can be between 1 and 4 characters in length (see page 29 of the
Charities SpecDoc). Only upper and lower alpha, backslash and hyphen characters are allowed.
Common problems include sending this element empty, including a space character or a full stop.

GAD postcode - /R68/Claim/Repayment/GAD/Donor/Postcode
This must be completed if the donor is a UK resident and contain a valid postcode (see page 47 of
the Charities SpecDoc).
BFPO postcodes need to be in the full “traditional” postcode format – there is a table available on
the GOV.UK website that has the full list of conversions between the numbers and the full
postcode – see here: https://www.gov.uk/government/publications/british-forces-post-officelocations
From 6th April 2015, if the donor is a Non-UK resident then the <House> element should contain as
much of the address as will fit into the 40 character limit and the <Overseas> element should be
included and set to ‘yes’.

GAD Total
This is a mandatory monetary element and must always be to 2 decimal places i.e. 3.50, 15.00. If
the value is less than £10, then only one zero is required before the decimal point i.e. 0.02, 9.99.
Other Guidance

Converting a password into MD5
1. The password string must first be made lowercase.
2. The lowercase password must then be MD5 hashed; the output of this operation must be an
array of bytes.
3. The byte array must then be base64 encoded, for ‘testing1’ this will give the result:
a3MweCsv60kkAgzEpXeCqQ==

Compression
Compression of the claim data is supported and we recommend that compression is used for files
over 1MB. The <CompressedPart> element must contain a data-stream which has been
compressed using zip or gzip and base 64 encoded. There is an example of an uncompressed claim
together with the zip and gzip versions in the Charities Valid Samples. LTS will validate files
containing compressed data.
V1.1
9
23/09/2015

Known Issues
Error 7026 – Incorrect error message returned
The validation states that:
error code: 7026
transactional message
(en)
Description: Exactly one of [OFF-NAME] or [OFF-ORG-NAME] must be
submitted.
You must provide the name of the Authorised Official or the
Corporate Trustee or both
The validation is correct but the transactional message should be:
“You must provide the name of the Authorised Official or the Corporate Trustee”
Support and contact information
If you have any feedback about this document, or any further questions please don’t hesitate to
contact the Software Developers Support Team
Telephone: 03000 518308
Email: Software Developer Support Team
Opening Hours: Monday to Friday 09:00 - 17:00 (Closed Bank Holidays)
Number
Reference
1
RIM Artefacts
Charities RIM artefacts version 2.0 – these artefacts are for claims made on or after
06/04/2015
Charities RIM artefacts version 1.0 - these artefacts are for claims made before
06/04/2015
Charities Online Service Non-Form Validation Rules
The validation rules for the Charities service that aren’t included in the RIM artefacts
HMRC IRmark
All the information needed to calculate the IRmark, which must be sent with every
Charities submission.
Local Test Service and LTS update manager
Download and install this tool to test your software against HMRC rules in your own
environment.
Government Gateway document submission protocol.
All applications submitting XML must comply with this protocol to communicate with
Government Gateway.
2
3
4
5
V1.1
10
23/09/2015
6
7
Charities technical specifications: valid xml samples
This contains examples of :
 different Gateway messages sent and received as part of the ‘conversation’ when
submitting a file
 valid samples for LTS
 compressed data sample
Recognition process for the charities online service: 1.6
Follow the instructions in the document to gain recognition
Change History
V1.0 to V1.1
 updated LTS guidance
V1.1
11
23/09/2015