Document Control

Revenue Online Services
Web Services
Form 11 Specification / File name: spec.doc
Status: Issued
Version: 1.2
Date: 01/09/08

Page 18 of 21

Revenue Online Services
Web Services
Form 11 Specification / File name: spec.doc
Status: Issued
Version: 1.2

DOCUMENT CONTROL

Document Holder

Change History

Version / Date / Change
1.0 / 01/09/08 / Document Created from Version 8

CONTENTS

1. Introduction 3

2. Calling the Service 4

2.1. Namespaces, Schemas and Locations 4

2.2. Operation Header 4

2.3. Digital Signature 5

3. Interpreting the Response 6

3.1. Form11/Calculate 6

3.2. Form11/File 6

3.3. SummaryCalculation 6

3.4. Errors 6

A. SummaryCalculation (v6) (2005) 8

B. Error Codes for Form 11 (v9) (2008) 10

B.1 ErrorList for Personal Details 10

B.2. ErrorList for Self Employed Income 11

B.3. ErrorList for Irish Rental Income 12

B.4. ErrorList for PAYE Panel 13

B.5. ErrorList for Foreign Income 14

B.6. ErrorList for Irish Other Income 15

B.7. Error List for Exempt Income 16

B.8. Error List for Charges and Deductions 17

B.10. Error List for Personal Tax Credits 18

B.11. Error List for Restrictions of Reliefs 19

B.12. Error List for Capital Gains 20

B.13. Error List for Cross Panel Validation 21

Date: 01/09/08

Page 18 of 21

Revenue Online Services
Web Services
Form 11 Specification / File name: spec.doc
Status: Issued
Version: 1.2

1.  Introduction

This document is a specification for the ROS web service for the Form 11. It covers all the necessary arrangements for calling this web service that are specific to the Form 11. It should be read in conjunction with the Overview Specification, which discusses the general approach to calling a ROS web service.

The ROS web service for the Form 11 provides two basic services:

·  Anonymous validation and calculation of a Form 11

·  Submission of the Form 11 to Revenue

Both of these services are covered in this document.

This document is currently written for the 2008 tax year. It will be updated to reflect other tax years when appropriate.

2.  Calling the Service

The ROS web service for the Form 11 is described through the WSDL file and the Schema for the Form 11. This schema is also referenced within the WSDL file. These files will be found at

·  http://www.ros.ie/schemas/ros.wsdl

·  http://www.ros.ie/schemas/form11/v9/schema.xsd

The WSDL file is discussed in greater detail in the Overview Specification, including

·  Where the web service is located

·  What protocol must be used

2.1. Namespaces, Schemas and Locations

The Form 11 web service uses the two namespaces enumerated in the Overview Specification. It also uses an additional namespace specifically for the Form 11. This extra namespace is used to define all the elements for describing the Form 11 and its calculation.

Description / Namespace / Location
The Form 11 elements / http://www.ros.ie/Ê
schemas/form11/v9/ / http://www.ros.ie/Ê
schemas/form11/v9/schema.xsd
Basic types for ROS schemas and web services / http://www.ros.ie/Ê
schemas/rostypes/ / http://www.ros.ie/Ê
schemas/rostypes/schema.xsd
Web service messages, operations, bindings, etc. / http://www.ros.ie/Ê
schemas/service/ / http://www.ros.ie/Ê
schemas/ros.wsdl

2.2. Operation Header

As discussed in the Overview Specification, it is necessary to provide an Operation header in the SOAP request to identify which web service you wish to call. For the Form 11 web service, there are two options depending on which to achieve.

·  Form11/Calculate

·  Form11/File

Form11/Calculate
This operation can be used to indicate that the Form 11 should be validated and the liability calculated, but not submitted. When this service is being used, neither the name nor the PPSN need be completed. The result from this will be an Acknowledgement, as defined in the schema. Either an ErrorList or a SummaryCalculation will be returned in the acknowledgement, depending on whether or not the validation was successful. The NoticeNumber will never be present.
Form11/File
This operation can be used to indicate that the Form 11 should be validated and submitted to Revenue. If this is successful, the Form 11 will be processed by Revenue. The return value will be an Acknowledgement with a NoticeNumber and a SummaryCalculation. If the validation of the Form 11 is unsuccessful, the Form 11 will not be processed any further by Revenue. The return value in this case will be an Acknowledgement with only an ErrorList present.

2.3. Digital Signature

The Form 11 Service may or may not require a digital signature depending on which operation is being accessed, according to the following table.

Operation / Signature required
Form11/Calculate / No
Form11/File / Yes

3.  Interpreting the Response

The response from this web service will be an Acknowledgement element. This element extends the AcknowledgementType described in the Overview Specification.

In addition to the elements and attributes declared as part of the AcknowledgementType type, there may also be a SummaryCalculation element. This element will only be returned if the validation was successful. It contains details of the calculation and total liability as calculated by Revenue for the submitted Form 11.

3.1. Form11/Calculate

If the operation is Form11/Calculate, then a successful validation of the form will return a SummaryCalculation while an unsuccessful one will return an ErrorList containing the errors. See below for an explanation of the SummaryCalculation element and a list of the possible errors.

A NoticeNumber will never be returned.

3.2. Form11/File

If the operation is Form11/File, then a successful validation of the form will return a NoticeNumber and a SummaryCalculation while an unsuccessful one will return an ErrorList containing the errors. See below for an explanation of the SummaryCalculation element and a list of the possible errors.

3.3. SummaryCalculation

When validation is successful, a SummaryCalculation will be returned. This element breaks down the liability calculation performed by Revenue. This calculation changes from year to year, so the SummaryCalculation element must be interpreted in the context of which version was submitted. Please see the appropriate Appendix below.

3.4. Errors

There are two different checks done for any form submitted via Webservice. Firstly, the XML file is validated against the schema. Any errors at this stage will result in an error message like the following:

Error validating XML: cvc-complex-type.4: Attribute 'ppsnself' must appear on element 'ns3:Details'.

If the XML validation passes ok, the data within the form is checked. This will include checks on the values for each element and for discrepancies between values in different elements. Attributes of elements are also checked.

Any errors in these checks will produce error text with the name of the element that contained the error and the Panel the error occurred in, like the following:

PPSN (Personal Details) is a required field.

The values for the errors must be interpreted in the context of which version Form 11 was submitted. Please see the appendices for possible values.

Date: 01/09/08

Page 18 of 21

Revenue Online Services
Web Services
Form 11 Specification / File name: spec.doc
Status: Issued
Version: 1.2

A. SummaryCalculation (v6) (2005)

The SummaryCalculation element consists of attributes and a series of elements, which break down the calculation. The attributes of the SummaryCalculation element are:

ppsnself / The PPSN that was on the submitted Form 11
name / The name that was on the submitted Form 11
date / The date of the calculation
currency / The currency in which the Form 11 was submitted
periodstart / The period start date that was on the submitted Form 11
periodend / The period end date that was on the submitted Form 11
totalliability / The total liability as calculated for this Form 11
selfasmttaxpayable / The total amount of tax due by the customer
selfasmttaxrepayable / The total amount of tax owed by the customer

The following elements break down the calculation further

Income / The sources of income
Captial / Capital allowances and losses carried forward
NetPosition / The net position of income less losses/allowances
IrishEffectiveRate / The Irish Effective Rate
AllowancesReliefsDeductions / Allowances, reliefs, and deductions
TaxableIncome / Taxable income (net position less allowances, reliefs, and deductions) broken down into tax rates.
CreditsReliefs / Credits and reliefs set against tax on income
NetTaxLiability / Running total of tax liability (all of the above included)
AddTaxOn / Addition of other taxes
NetTaxLiability / Running total of tax liability (all of the above included)
DeductTaxOn / Deductions from tax
NetTaxLiability / Running total of tax liability (all of the above included)
PRSIHealth / PRSI, health levy, tax relief at source
Other / Any other credits and reliefs

The total liability figure given in the attribute of the SummaryCalculation can be obtained by applying the following calculations to the values available in the break down elements.

NetPosition/total

- AllowancesReliefsDeductions/total

= TaxableIncome/amount

This is then broken across the tax bands to obtain TaxableIncome/totalincometax.

TaxableIncome/totalincometax

- CreditsReliefs/total (= NetTaxLiability/total (first))

+ AddTaxOn/total (= NetTaxLiability/total (second))

- DeductTaxOn/total (= NetTaxLiability/total (third))

+ PRSIHealth/total

- Other/total

= Total liability

B. Error Codes for Form 11 (v9) (2008)

B.1 ErrorList for Personal Details

Field Name> must be after Date of Birth
Field Name> cannot be less than 01/01/1900 or greater than the day of upload
Field Name> cannot be before 1900
Field Name> cannot be after today
Joint Assessment must be chosen when Non Resident is selected
Spouse PPSN (Personal Details) cannot be the same as PPS number for self
Amount Income In State (Personal Details) cannot be less than value supplied in Income Taxable in the State
Spouse Date Of Death (Personal Details) date of death cannot be before self date of birth
A non-resident cannot claim married persons tax credit where all of the income of both spouses is not chargeable to tax in Ireland. Please change marital status to single
Marital Status must be Married to select a basis of assessment
A basis of assessment must be selected
Error: Married But Living Apart (Personal Details) only applicable to marital status of Married but living apart
Error: Married But Living Apart (Personal Details) If ticked previous marital status must be Married
Error: Prev Stat (Personal Details) Not allowed with the marital status selected. Please review Help for valid combinations
Error: Prev Stat (Personal Details) Your present marital status is Single, you cannot have had a previous status

B.2. ErrorList for Self Employed Income

Cannot have Partner Reference (Trade {1-3}) here if previously submitted accounts information has value
Cannot have Perv Sub Acc Return (Trade {1-3}) here if partnership tax reference has value
Field Name> is required if Accounts Information filled
Error: Specify one of either Self or Spouse for this trade.
Error: Specify <Field Name> for one of either Self or Spouse.
Error: Prev Sub Acc Return (Trade {1-3}) Cannot be earlier than 01/01/1900
Error: Prev Sub Acc Return (Trade {1-3}) Cannot have a value less than 2001 or greater than 2006

B.3. ErrorList for Irish Rental Income

Field Name> (Irish Rent Income) cannot have a value less than 0 or greater than 99,999,999
Field Name> (Irish Rent Income) cannot be less than the value given for Total Capital Allowances
Field Name> (Irish Rent Income) cannot be greater than the value given for Amount of income after expenses but before capital allowances and losses
Unused CA Restricted Self/Spouse (Irish Rent Income) Cannot be greater than Lesser of (31750 or Capital Allowances for 2008 minus (Net Rental Income minus Capital allowances forward from a prior year))
Total Capital Allow Self/Spouse (Irish Rent Income) Cannot be greater than Capital Allowances brought forward from a prior year + Capital Allowances for the year 2008
Error: Non Resident checkBox for self on the Personal Details panel must be ticked if value entered in Am Tax Withheld Self (Irish Rent Income)
Error: Non Resident checkBox for spouse on the Personal Details panel must be ticked if value entered in Am Tax Withheld Spouse (Irish Rent Income)
Error: Total Capital Allow Self/Spouse (Irish Rent Income) Cannot be greater than Lesser of (31750 or Capital Allowances for 2008 minus (Net Rental Income minus Capital allowances forward from a prior year))

B.4. ErrorList for PAYE Panel

Field Name> (Paye) cannot have a value less than 0
Field Name> (Paye) cannot have a value greater than 99,999,999
Field Name> (Paye) is over 100,000
Total Self (Paye) must be greater than or equal to the sum of M1, M4 and M6
Total Spouse (Paye) must be greater than or equal to the sum of U1, U4 and U6
Field Name> (Paye) cannot have a value greater then 50,000
Field Name> (Paye) cannot hava a value greater than 999,999
Field Name> (Paye) greater than 15,001
Field Name> (Paye) is over 25,400
Field Name> (Paye) is over 1,270
Where a value is returned for Expenses Self/Spouse (Paye), value required at one of the following:
-Irish Employment subject to PAYE
-Foreign Employment subject to PAYE
-Public Sector Employment
-Employment not subject to PAYE
Field Name> (Paye) should be less than the sum of Irish Employment subject to PAYE, Foreign Employment subject to PAYE, Pension Subject to PAYE, Public Sector Employment, Early Farm Retirement Pension and Annuity Pension
Sum of PAYE refunded 2008 and PAYE tax underpaid must be less than Total PAYE Deducted Self/Spouse (Paye)
Deferred Income Tax Pay Due Self/Spouse (Paye) cannot be greater than amount entered at Chargeable to IT on Shares disposed
Relevant Tax Share Options Self/Spouse (Paye) cannot exceed 41% of Total Chargeable amount

B.5. ErrorList for Foreign Income

Field Name> (Foreign) is a required field
Field Name> (Foreign) must be between 0 and 99,999,999
Must enter a figure for Eu Dep Interest Self (Foreign) if entering information into EU "other" Interest field
Am Of F Tax Ded Self/Spouse (Foreign) must be filled out when you have entered information into Income from foreign employments above
Inc From Foreign Empl Self/Spouse (Foreign) must be filled out when you have entered information into foreign tax deducted below
Ftrade Inc Tax Ded Amount Self/Spouse (Foreign) must be filled out when you have entered information into income from foreign trade/profession above
Ftrade Inc Tax Ded Self/Spouse (Foreign) must be filled out when you have entered information into amount of foreign tax deducted below
Am Of F Tax Ded Self/Spouse (Foreign) must be filled out when you have entered information into Income from Foreign trade/profession above
Income From F Rents Self/Spouse (Foreign) must be filled out when you have entered information into amount of foreign tax deducted below
Am Of F Tax Ded Self/Spouse (Foreign) must be filled out when you have entered information into profit on Foreign Rental property
Other Foreign Tax Self/Spouse (Foreign) must be filled out when you have entered information into income from all other foreign interest
All Other Income Tax Ded Self/Spouse (Foreign) must be filled out when you have entered information into amount of foreign tax deducted
Dep Foreign Tax Self/Spouse (Foreign) cannot be greater than the amount entered at (a)EU deposit interest
Foreign Tax Ded Self/Spouse (Foreign) cannot be greater than the amount entered at Gross amount Foreign Employments attributable to the performance outside the state of such employments on which Transborder Relief is not claimed
Foreign Tax Ded Self/Spouse (Foreign) cannot be greater than the amount entered at Foreign Rent
Exp From F Rents Income Self/Spouse (Foreign) cannot be greater than the amount entered at Foreign Rent
Net Profit F Rents Self/Spouse must equal Foreign Rents - Expenses on this income
Other Foreign Tax Self/Spouse (Foreign) cannot be greater than the amount entered at All other Foreign Income where tax deducted

B.6. ErrorList for Irish Other Income