Revenue Online Servicesrospublictestnextversion.ros.ie/schemas/drs/fuel... · quarterly periods. The period defined in the form must match the period that Revenue has requested data

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


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


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


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.


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.


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


Transactions

Schema Notes

Page 7 of 14

Name Type Minimum

Value/Length

Maximum

Value

Required


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.


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.



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


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


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


Transactions

Schema Notes

Page 10 of 14

Name Type Required


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


Code Numeric 1 99999 Y Error Code as defined by Revenue. See Appendix A for more detail

Table 9 Error Element

Name Type Required


Error String Y A textual description of the error.


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


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


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}


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

Documents

Revenue Online Servicesrospublictestnextversion.ros.ie/schemas/drs/fuel... · quarterly periods. The period defined in the form must match the period that Revenue has requested data