Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 1 of 14
Revenue Online Services
Schema Notes
Diesel Rebate Scheme
Fuel Card Transactions
Last Updated 26/02/2013
Status DRAFT
Document Version 1.2
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 2 of 14
1 CONTENTS
1 Contents ......................................................................................................................................................................... 2 0 Document Information .................................................................................................................................................... 3
0.1 Synopsis ................................................................................................................................................................. 3 0.2 Change History ...................................................................................................................................................... 3 0.3 Abbreviations used in this Document ..................................................................................................................... 3 0.4 Additional Information ............................................................................................................................................ 3
1 Schema Overview .......................................................................................................................................................... 4 1.1 Supported Functions .............................................................................................................................................. 4 1.2 Schemas ................................................................................................................................................................ 4 1.3 Business Process Overview ................................................................................................................................... 5
1.3.1 Diesel Rebate Scheme Processes ................................................................................................................. 5 2 Schema Details .............................................................................................................................................................. 6
2.1 Periodic Fuel Card Transactions Data ................................................................................................................... 6 3 Fuel Card Transactions - Types ..................................................................................................................................... 8
3.1 Declarant Type ....................................................................................................................................................... 8 3.2 Period Type ............................................................................................................................................................ 8 3.3 Card Type .............................................................................................................................................................. 9
3.3.1 Error Type .................................................................................................................................................... 10 4 Appendix A –Simple / Enumerated Types ................................................................................................................... 11
4.1 Simple Types ....................................................................................................................................................... 11 4.2 Enumerated Types ............................................................................................................................................... 11
5 Appendix B – Error Messages ..................................................................................................................................... 13 6 Appendix C – Sample Messages ................................................................................................................................. 14
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 3 of 14
0 DOCUMENT INFORMATION
0.1 Synopsis
This document outlines the schema to be used for the preparation of Fuel Card Transaction data for submission to Revenue as part of the Diesel Rebate Scheme.
The schema and accompanying documentation are in a draft format and may be subject to future changes.
0.2 Change History
Table 1: Change History
Version
Number
Section Affected Change Description Date
0.1 Initial Revision 15/08/2013
1.1 5 Appendix B Updated with Error Messages 20/02/2013
1.2 Section1.2,
Section 3.1, Section 4.1, Appendix A
Section 3.3.1, Appendix A
Add revenue-types-v1.xsd schema
Update ros:taxtype to rev:RegistrationType
Add Error Codes
26/02/2014
0.3 Abbreviations used in this Document
Abbreviation Description
DRS Diesel Rebate Scheme
XML eXtensible Mark-up Language
0.4 Additional Information
N/A
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 4 of 14
1 SCHEMA OVERVIEW
The schema is intended for use by Fuel Card Providers submitting requested data to Revenue as part of the Diesel Rebate Scheme.
This document contains the element definitions, field & cross-field dependency rules for the Fuel Card Transactions schema.
At present the schema is limited to the preparation of period level transaction details. i.e. summed totals covering a period per card.
The element descriptions within the document include the following:
Name
Type
Required (in the request)
Description.
o Required data format.
o Restricted data values where appropriate.
o Maximum and minimum values where applicable.
o Dependent elements – other elements that are optional but required in certain circumstances if other elements are not provided.
The element rules must be fulfilled for Revenue to accept and process the submission.
1.1 Supported Functions
The following functions are supported using the schema. These map to DRS processes as outlined in Section 1.3 below.
Submit Periodic Fuel Card Transaction data
1.2 Schemas
There is one primary schema containing definitions for DRS Fuel Card Transaction requests and responses. There are also a number of supporting schemas that have custom types defined. Table 2 below outlines details of these schemas.
Table 2 Diesel Rebate Claim Schemas
Name File Namespace
Prefix
New or
Modified Reference
DRS Fuel Card Transactions Request
schema.xsd N/A New Section 2
ROS Types rostypes/schema.xsd ros: Existing Appendix A
Revenue Types common/revenue-types-v1 rev: Existing Appendix A
The new and modified schemas will be made available on the ROS website as part of the Diesel Rebate Scheme (DRS) software release.
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 5 of 14
1.3 Business Process Overview
1.3.1 Diesel Rebate Scheme Processes
1.3.1.1 Submit Periodic Fuel Card Transaction data
As part of the Diesel Rebate Scheme approved Fuel Card Providers will be required to electronically submit Fuel Card usage data to Revenue on a periodic basis. The data will subsequently be used to support Diesel Rebate claims received from Road Transport operators.
A list of fuel cards for which Revenue is seeking data and applicable dates will be made available to each provider to retrieve electronically via the Revenue Online System (ROS) on the periodic basis. The onus will be on the card provider to retrieve the request from Revenue and to supply the associated response within the given time frames. The response must be submitted electronically via ROS.
In order to submit Fuel Card Transaction data providers will be required to create a file that adheres to the rules contained within the schema and any further business rules defined by Revenue. A fuel card transactions submission will be tied to a DRS claim period (quarterly). Revenue may seek data for more than one period at a time.
If the submission is unsuccessful, i.e. the submission fails validation, a list of Errors will be returned. See Appendix B for more details on error messages. Please note that if validation fails for any of the submitted data then the entire submission will fail and the transfer will not be processed.
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 6 of 14
2 SCHEMA DETAILS
2.1 Periodic Fuel Card Transactions Data
Figure 1 Periodic Fuel Card Transactions Data
A ‘FuelCardTransactions’ request contains all of the information required to submit periodic fuel card data to Revenue. The attributes/elements of a Diesel Rebate Claim Request are listed below.
Table 3 Fuel Card Transactions attributes
Name Type Minimum
Value/Length
Maximum
Value
Required
(Y/N) Description / Validation
formversion Numeric 1 1 Y Version of the form
Form version must be 1
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 7 of 14
Name Type Minimum
Value/Length
Maximum
Value
Required
(Y/N) Description / Validation
product Text Characters 1 20 Y The name of the software or software company used to generate the return.
isAmendment ros:boolean 1 1 Y Flag to identify whether this is an amendment of an original submission.
Reserved for future use
sequenceNumber
Numeric N/A N/A Y Used to identify the sequence number of this particular file where the details have been split over multiple files.
Reserved for future use
lowVolumeThreshold
Numeric N/A N/A Y Details the value in litres, which defines a ‘low volume’ purchase.
Currently fixed at 120
Table 4 Fuel Card Transactions elements
Name Type Required
(Y/N/C) Description / Validation
Declarant
Declarant
Y The person/entity who is submitting the claim. Information is required on the tax reference number, tax type and fuel card provider name of the person/entity who is submitting the form.
See Section 3.1 below for details.
Period Period Y The period for which the data covers. DRS claims are submitted to Revenue on a quarterly basis. As such Fuel Card Transactional data will also be sought covering quarterly periods. The period defined in the form must match the period that Revenue has requested data for.
See Section 3.2 below for details.
Card Card Y A ‘Card’ element is used to provide details on a particular Fuel Card. A ‘Card’ element should be included for each and every Fuel Card number that Revenue have requested data for.
See Section 3.3 below for details.
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 8 of 14
3 FUEL CARD TRANSACTIONS - TYPES
3.1 Declarant Type
Figure 2 Declarant Type
The Declarant Type contains details on the declarant who is filing the claim. It includes details of the Tax type and tax number of the person making the claim. The tax number must be a valid tax number for the declared tax type.
Table 5 Declarant Elements
Name Type Required
(Y/N)
Description / Validation
TaxType rev:RegistrationType Y Tax Type, e.g. DRS.
See Appendix A
TaxReferenceNumber ros:registration Y The tax registration number. Must match one of the following regular expressions.
[0-9]{7,8}[A-Wa-w][A-ITWXZa-itwxz ]
[0-9]{5}[A-Wa-w]
[7-9][A-Wa-w][0-9]{5}[A-Za-z]
[0-9]{5,8}
[0-9]{1,2}[A-Za-z][0-9]{5}[A-Za-z]
ProviderName ros:string70 Y The trading name of the Fuel Card Provider
3.2 Period Type
Figure 3 Period Type
The Period Type contains details of the period for which the Fuel Card Transactions cover. DRS periods are quarterly and contain a start date and end date to identify the period. The periods for which Fuel Card data may be requested to file for are:
Quarter 1: Jan 1st – March 31
st
Quarter 2: April 1st – June 30
th
Quarter 3: July 1st – Sept 30
th
Quarter 4: Oct 1st – Dec 31
st
Table 6 Period Elements
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 9 of 14
Name Type Required
(Y/N/C) Description / Validation
StartDate ros:date Y The start date of the filing period.
Must be in the format DD/MM/YYYY
EndDate ros:date Y The end date of the filing period.
Must be in the format DD/MM/YYYY
3.3 Card Type
Figure 4 Card Type Elements
The Card type contains details on a per Fuel Card basis. At least one Card must be included in a Fuel Card Transactions submission. However, a ‘Card’ section should be included for each and every Fuel Card that Revenue have sought information for. A submission may be wholly rejected where data is missing for any card that has been requested.
Each card should be detailed once. Constraints will ensure that all ‘Cards’ included in a submission are unique based on card number.
Where a card is known to the Fuel Card Provider but no transactions have been recorded within the period this should be detailed in the submission with zero values for volume, number of transactions etc. E.g. Volume: 0, NumTransactions: 0, NumLowVolTransactions: 0
Where a requested card is not known to the Fuel Card Provider an ‘Error’ element should be included in place of the volume data.
Table 7 Card Type Elements
Name Type Required
(Y/N) Description / Validation
Number ros:positive19_16 Y Number of the Fuel Card as appears on the card itself. This must match one of the Fuel Card numbers sought by Revenue.
Min length 16 - Max length 19
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 10 of 14
Name Type Required
(Y/N) Description / Validation
Each number must be unique
Name ros:string30 Y Name/Description on the Fuel Card. E.g. Driver Name or Vehicle Registration as it appears on the Card
Max Length: 30
Volume ros:positiveDec10 Y Total volume of auto-diesel dispensed during the period on this Fuel Card (litres). Where there has been no auto-diesel dispensed for a known fuel card this should be set to 0.
This is a decimal field
Minimum Value = 0, Maximum Value = 9999999999.99
NumTransactions ros:positive5 Y Total number of transaction within the period involving the purchase of auto-diesel.
This is a numeric field
Minimum Value = 0, Maximum Value = 99999
NumLowVolTransactions ros:positive5 Y Total number of transaction within the period involving the purchase of auto-diesel where the volume was less than @lowVolumeThreshold in litres
This is a numeric field
@lowVolumeThreshold is currently set to 120.
Minimum Value = 0, Maximum Value = 99999
Error Error Conditional An Error may be included where the provider does not recognize the requested Fuel Card Number.
3.3.1 Error Type
Figure 5 Error Type
The Error Type provides Fuel Card Providers with a means to declare that a given Fuel Card number is not known. Please note, this should not be used in cases where a known fuel card number has not had any transactions within the period.
Table 8 Error Attribute
Name Type Minimum
Value/Length
Maximum
Value
Required
(Y/N) Description / Validation
Code Numeric 1 99999 Y Error Code as defined by Revenue. See Appendix A for more detail
Table 9 Error Element
Name Type Required
(Y/N) Description / Validation
Error String Y A textual description of the error.
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 11 of 14
4 APPENDIX A –SIMPLE / ENUMERATED TYPES
4.1 Simple Types
There are a number of simple types used in the schema to represent string, integer and decimal values. See the table below for details on the simple types.
Table 9 Simple Element Type Descriptions
Element Restriction
ros:boolean ROS Enumerated Type. See Appendix A
ros:date Date in format DD/MM/YYYY
rev:RegistrationType
Revenue Enumerated Type. See Appendix A
ros:registration
A Tax Reference Number.
String in the format of one of the following
[0-9]{7,8}[A-Wa-w][A-ITWXZa-itwxz ]?
[0-9]{5}[A-Wa-w]
[7-9][A-Wa-w][0-9]{5}[A-Za-z]
[0-9]{5,8}
[0-9]{1,2}[A-Za-z][0-9]{5}[A-Za-z]
positive19_16
String in the format [0-9]
Minimum length is 16
Maximum length is 19
PositiveDec10 Decimal between 0 and 9999999999.99
4.2 Enumerated Types
Table 10 boolean Input
True
False
Table 11 RegistrationType Input
CUST
PREM
VAT
IT
PSWT
SPIA
DIRT
IUT
PAYE
LAET
SSIA
CT
ACT
DWT
CGT
ELEV
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 12 of 14
RTSO
EVAT
TAXC
EUST
CandE
VRT
STMP
ATT
CAT
LPT
IL
PSL
IEGEVR
TAIN
EORI
RCT
BET
EXCISE
INTR
RPT
TRT
VIES
NEW_VAT
DRS
CDS
4.3 Error Codes
Table 12 Error Codes Input
1001 UNKNOWN CARD
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 13 of 14
5 APPENDIX B – ERROR MESSAGES
The Fuel Card Transactions submission service may respond with business errors based on simple-field or cross-field validation of input or with technical errors due to inconsistent data.
Where the input fails to pass standard schema validation the file will be rejected and schema violation errors will be returned to the user.
If the input is deemed to be valid against the schema a series of business rules will be run against the data. Any violated errors will be reported back to the user.
The following information may be included in a business validation error messages
Field Path: A validation message may include the path from the root of the request to the field that triggered the validation rule i.e. FuelCardTransactions.period.startDate
Index: If a validation error occurs within a collection of elements, an index will be used in the field path to help identify the field that failed. i.e. FuelCardTransactions.card[1].number indicates the first card element in the request has failed validation due to an issue with the number.
Value: The actual value that failed validation may be included in the validation message. i.e. FuelCardTransactions.card[1].number, Card details have already been supplied for (9999999999999999)
The list of business errors that may be returned include:
No permission to file for this client
No permission to file for this registration
Not Registered for this Tax
No matching Fuel Card Data request on record.
The declared period does not match up with any current requests according to Revenue records.
Data for the following requested fuel cards must be included: {0}
FuelCardTransactions.card[1]: The following fuel card was not included in the request according to Revenue records and must be removed: {0}
FuelCardTransactions.card[1]: Duplicate card details supplied for {0}
FuelCardTransactions.card[1]: The number of low volume transactions {0} cannot be greater than total transactions {1}. {2}
Revenue Online Services Diesel Rebate Scheme – Fuel Card
Transactions
Schema Notes
Page 14 of 14
6 APPENDIX C – SAMPLE MESSAGES
DRS 1234567T Test Fuel Card Providers Ltd 01/04/2014 30/06/2014 1234567891234567 Test Card 1 15511 25 0 1234567891234123 Test Card 2 10900 20 2 1234567891234245 Test Card 3 17333.50 30 4 1234567891234333 UNKNOWN CARD