Tax Withheld Calculator - Software developers homepage · Tax Withheld Calculator ... 3.4.6 Calculate Offset Amount ... WFT Weekly Family Threshold – used in calculation o f Medicare

SPECIFICATION SOFTWARE PRODUCERS

10 APRIL 2012 UNCLASSIFIED FORMAT AUDIENCE DATE CLASSIFICATION

Tax Withheld Calculator

(Proof of Concept)

Message Implementation Guide

Version: [2.0] Document status: Final

This document and its attachments are Unclassified

TAX WITHHELD CALCULATOR (PROOF OF CONCEPT) Message Implementation Guide

Version [2.0] Unclassified PAGE 2 OF 54

VERSION CONTROL

Version Release date Description of changes

0.1 14/10/2011 Initial draft

0.2 05/12/2011 Incorporated feedback from initial draft review

0.3 05/12/2011 Release for SDGC, 07/11/2011

0.4 02/02/2012 1. Changed “Foreign Resident?” to “Australian Resident?” in Choose scale process flow to better align with element names and current tax withheld calculators.

2. Updated decision point names for clarity

3. Corrected the calculation specification for Tax Withheld ([TWC19])

4. Added Format & Validation Rules (incl. messages)

5. Added Appendix with SBDM information

0.5 22/3/2012 1. SBDM Implementation for Request and response Messages.

2. Process flows updates to address known issues with calculation of Net Withholding Amount and rounding when using Tax Scale 4.

3. Formal inclusion of diagnostic output

4. Inclusion of “Date of applicability” information in reference data tables and calculation process.

1.0 10/4/2012 Final

1. Removed References to “Ready Reckoner”

2. Corrected incorrect element ID in Section 4.1.1.4 (changed [TWC16] to [TWC21]).

1.1 04/05/2012 1. Clarification for Tax Scale 4 processing.

2. Remove references to Leave Loading: update Choose Scale process to remove Scale 7, delete element TWC10, related rule and message.

3. update message version to twc.calculate.01.01

4. Correct minor typos and format issues, clarify application of Flood Levy, add notes on diagrams.

1.2 10/05/2012 Remove references to Scale 7 from sections 3.2.2, 3.4.5 and 3.4.6

2.0 07/06/2012 Update links for reference documents, copyright statement and version.



Copyright © Commonwealth of Australia 2012 You are free to copy, adapt, modify, transmit and distribute this material as you wish (but not in any way that suggests the ATO or the Commonwealth endorses you or any of your services or products).



Table of contents 1 Introduction......................................................................................................................... 5

1.1 Overview.................................................................................................................... 5 1.2 Purpose...................................................................................................................... 5 1.3 Audience and Scope .................................................................................................. 5 1.4 References................................................................................................................. 5 1.5 Limitations / Known Issues ......................................................................................... 6 1.6 ACRONYMS / TERMS ............................................................................................... 6

2 General Instructions ........................................................................................................... 8 2.1 Data Validation........................................................................................................... 8 2.2 SBR Framework......................................................................................................... 8

2.2.1 Business Documents.............................................................................................. 8 2.3 Response Messages.................................................................................................. 8

2.3.1 Messages Described in the MIG............................................................................. 8 2.3.2 Messages not Described in the MIG....................................................................... 8

2.4 Rule Expression ......................................................................................................... 9 2.4.1 Structured English .................................................................................................. 9 2.4.2 Format Rules........................................................................................................ 10

3 Business Overview ........................................................................................................... 11 3.1 Process Overview .................................................................................................... 11 3.2 Reference Data Tables ............................................................................................ 11

3.2.1 Tax Scale Tables.................................................................................................. 11 3.2.2 Medicare Levy Parameters................................................................................... 12

3.3 Notes on Process Descriptions ................................................................................ 13 3.4 Calculate Net Withholding Amount Process ............................................................. 13

3.4.1 Choose Tax Scale ................................................................................................ 14 3.4.2 Calculate Tax Scale 4 Withholding ....................................................................... 16 3.4.3 Period Conversion................................................................................................ 17

3.4.3.1 Convert Period Earnings to Weekly Earnings ............................................... 17 3.4.3.2 Convert Weekly Amount to Period Amount................................................... 18

3.4.4 Calculate Unadjusted Weekly Withholding ........................................................... 20 3.4.5 Calculate Medicare Adjustment Amount............................................................... 20

3.4.5.1 Calculate Weekly Family Threshold.............................................................. 22 3.4.5.2 Calculate Shading Out Point......................................................................... 23 3.4.5.3 Calculate Weekly Levy Adjustment............................................................... 23

3.4.6 Calculate Offset Amount....................................................................................... 25 4 TWC Interaction Model ..................................................................................................... 27

4.1 Summary.................................................................................................................. 27 4.1.1 TWC Request - Message ..................................................................................... 27

4.1.1.1 Schema references....................................................................................... 27 4.1.1.2 Standard Business Document Header Content............................................. 27 4.1.1.3 Schema references....................................................................................... 27 4.1.1.4 Standard Business Document Body Content ................................................ 27

4.1.2 TWC Response - Message................................................................................... 35 4.1.2.1 Schema Reference....................................................................................... 35 4.1.2.2 Standard Business Document Header Content............................................. 35 4.1.2.3 Standard Business Document Body Content ................................................ 35

Appendix A – The Message Content Table Explained ............................................................. 38 Appendix B – Response Messages ......................................................................................... 39 Appendix C – SBDH Request Elements .................................................................................. 42 Appendix D – SBDH Request Validation Rules........................................................................ 45 Appendix E – SBDH Response Elements................................................................................ 51



1 INTRODUCTION

1.1 OVERVIEW

The Tax Withholding Calculator (TWC) allows a user to calculate the amount of tax withholding for a payee. This document describes the calculations, transformations, validations and error messages performed by Schematron component of the Tax Withholding Calculator Proof of Concept Project. The project will deliver a self-contained calculation engine which is consumable by external developers. The future direction of this work is to implement the TWC as a web service. The deliverables for the proof of concept are: • Message Implementation Guide • Schematron • Schemas (xsd), and • Tax Tables (xml)

1.2 PURPOSE

The purpose of this document is to support software developers in the implementation of the TWC.

1.3 AUDIENCE AND SCOPE

This document contains the necessary information required to support the implementation of the Schematron TWC.

1.4 REFERENCES

Ref Document Document description Document Link

1 NAT 1004 NAT1004 - Statement of formulas for calculating amounts to be withheld

Please refer to http://softwaredevelopers.ato.gov.au/taxtables

2 NAT 2335 NAT2335 - Statement of formulas for calculation HELP component


3 NAT 3305 NAT3305 - Statement of formulas for calculation SFSS component


4 NAT 3539 NAT3539 - Calculating HELP in conjunction with SFSS


5 NAT 0929 NAT0929 - Medicare Levy Variation Declaration (Form & Instructions)


6 SBR Web Technical interface data that is The SBR Web Service



Service Implementation Guide (WIG)

common to all business processes and messages that use the SBR channel: • Standard message header

structure

Implementation Guide document and Web Service Description Language (WSDL) files can be downloaded at https://www.sbr.gov.au/content/myhome/softwaredevelopers/downloads/commoncomponents (requires login)

1.5 LIMITATIONS / KNOWN ISSUES

Ref Description

1 This document describes a Proof of Concept system. Specifications and implementation are likely to change. This system is not suitable for production use.

2 The current TWC has been provided in “standalone” form. The future direction for this work is to implement the TWC as a web service utilising the common framework used for SBR web services. Elements of the SBR framework (e.g. SBDM) have been incorporated in the standalone version of the TWC in preparation for this.

3 Where possible, existing SBR definitional taxonomy elements have been used in the schema. Where no suitable SBR element exists, element names have been named using the SBR element naming conventions.

4 The process flow does not include a decision point for the temporary 2011-12 Flood Levy. References to published tax scale documentation are made to Flood Levy inclusive tax scales.

Note that Flood Levy is not applicable for the 2012-13 tax year.

5 Validation Rules will not check when unnecessary data for a calculation has been provided.

For example, the payee is a foreign resident and has indicated that the tax free threshold is to be claimed. In this case, the “Tax Free Threshold” data is not applicable (or required) for the calculation. The system will ignore the inclusion of this data.

6 The TWC does not provide inputs to indicate that there are 53 or 27 pay periods in a given year. This adjustment should be done manually by the user.

7 In the TWC, the message description for CMN.ATO.GEN.100006 uses the term “XML” instead of “XBRL”.

1.6 ACRONYMS / TERMS

Acronym / Term Description

a Tax scale table coefficient

AdditionalChildRate Medicare Levy Parameter - Additional child

ATO Australian Taxation Office

b Tax scale table coefficient

MedicareLevy Medicare Levy Parameter - Medicare levy

MedicareLevyFamilyThreshold Medicare Levy Parameter - Medicare levy family threshold

MIG Message Information Guide

SBR Standard Business Reporting



SBDH Standard Business Document Header. The SBDH is a subsection of the SBDM.

SBDM Standard Business Document Message

Shade in threshold Medicare Levy Parameter - Weekly earnings shade-in threshold

SOP Shading out point – used in calculation of Medicare Levy

SOPDivisor Medicare Levy Parameter - Shading out point divisor

SOPMultiplier Medicare Levy Parameter - Shading out point multiplier

TWC Tax Withheld Calculator

WeeklyEarningsThreshold Medicare Levy Parameter - Weekly earnings threshold

WeeklyFamilyThresholdDivisor Medicare Levy Parameter - Weekly family threshold divisor

WeeklyLevyAdjustFactor Medicare Levy Parameter - Weekly levy adjustment factor

WFT Weekly Family Threshold – used in calculation of Medicare Levy

WLA Weekly Levy Adjustment – used in calculation of Medicare Levy

x Weekly earnings (adjusted)

y Tax withheld



2 GENERAL INSTRUCTIONS This section provides instructions that are relevant across messages specified within this MIG.

2.1 DATA VALIDATION

The TWC performs data type and/or business rule validation on request messages. These validations are detailed in Sections 2.4.2 and 4.1.1.4.

2.2 SBR FRAMEWORK

The TWC incorporates elements of the SBR framework. TWC interfaces are specified using XML schemas and NOT via eXtensible Business Reporting Language (XBRL). Some of the information provided in the SBR web service implementation guide (WIG) is applicable to the TWC. Specifically, sections 3.3.2, 3.3.3 & 3.3.4 of the WIG provide information on the SBDM. The physical message structure for the SBDH can be found in the SBR web service description language files (WSDLs).

2.2.1 Business Documents

Only one business document in the SBDH per message will be accepted.

2.3 RESPONSE MESSAGES

2.3.1 Messages Described in the MIG

All messages returned by the TWC will be described in Appendix B.

2.3.2 Messages not Described in the MIG

The MIG document only details messages raised by the TWC and not messages raised by external components such as XSLT processors.



2.4 RULE EXPRESSION

2.4.1 Structured English

ATO validation rules are expressed in a structured English form, specific terms are referenced in the following table:

Structured English term

Intended interpretation

Examples

- (as in <a> - <b>)

Minus. <a> - <b> Means value of ‘a’ minus the value of ‘b’

<> Not equal to IF <a> <> <b> Means if the value of ‘a’ is not equal to the value of ‘b’

AND Logical AND

NOT Reverses the value of a boolean i.e. turns TRUE to FALSE and vice versa.

NULL Fact is not there, or has been specified to be null with xsi:nil indicator or is a null non-textual value.

IF <a> = NULL Means if a (non-textual) value for <a> is blank or if <a> does not exist.

NULLORBLANK Fact is not there, is null with xsI:nil = true or is a null string. (Applied to Text, Code, Description and Identifier facts).

IF <a> = NULLORBLANK Means if a (textual) value for <a> is blank or if <a> does not exist.

OR Logical OR

SET Definition of an explicit set of values where if one value meets the criteria for comparison, a true response is given.

IF <a> <> SET("a","b","c") Means if <a> does not equal a or b or c. IF <a> = SET(“a”,”b”,”c”) Means if <a> is equal to a or b or c. Note: No Spaces exist between the SET and values are in brackets and are comma separated IF <a> = SET(0-3) Means if <a> is equal to 0 or 1 or 2 or 3



2.4.2 Format Rules

There are format rules that will be applied to elements provided in request documents. Note that not all rules described below are required for the TWC. The format rules, including the message code, are provided in the table below. Description of the message coding is provided in Appendix B.

Data type Rules Rule Imp. Msg Code

xs:boolean Data supplied is not in a valid xs:boolean format http://www.w3.org/TR/xmlschema-2/#boolean

DVR.ATO.TWC.001 CMN.TWC.GEN.F00001

xs:dateTime Data supplied is not in a valid xs:dateTime format http://www.w3.org/TR/xmlschema-2/#dateTime


xs:integer Data supplied is not in a valid xs:integer format http://www.w3.org/TR/xmlschema-2/#integer


xs:string Data supplied is not in the xs:string format http://www.w3.org/TR/xmlschema-2/#string


xs:date Data supplied is not in a valid xs:date format http://www.w3.org/TR/xmlschema-2/#date


xs:decimal Data supplied is not in a valid xs:decimal format See http://www.w3.org/TR/xmlschema-2/#decimal




3 BUSINESS OVERVIEW

3.1 PROCESS OVERVIEW

The Tax Withholding Calculator is modelled as a service, accepting a predefined request and returning a response. Figure 1 shows the high level flow of the TWC.

Figure 1 - Process Overview

3.2 REFERENCE DATA TABLES

The Tax Withheld Calculator requires a number of dynamic parameters based on user input. There are two types of parameters: Tax Scale tables and Medicare Adjustment Levy parameters. These are discussed in detail in the next sections.

3.2.1 Tax Scale Tables

To calculate the base withholding amount, the TWC requires two coefficients which are obtained from one of four sets of tax scale tables. Each of the four sets contain a number of individual tax scale tables, with the choice of tax scale table being governed by the input parameters. The four sets of tables are published in the following documents:

• NAT1004 – Statement of formulas for calculating amounts to be withheld • NAT2335 – Statement of formulas for calculation HELP component • NAT3305 - Statement of formulas for calculation SFSS component • NAT3539 – Calculating HELP in conjunction with SFSS

An example of a Tax Scale table is shown in Table 1, below.

Where tax-free threshold NOT claimed in Tax file nu mber declaration

Scale 1

Weekly earnings (x) less than $ a b

259 0.1650 0.1650

394 0.2284 16.4596

… … …

3144 & over 0.4650 376.9654

Table 1 - Example Tax Scale Table It must be noted that Tax Scale 4 table in the published documentation follows a slightly different format to the other tax scale tables. In this case the formula y = ax is used, where the



coefficient a is set to the Tax Rate defined in the Tax Scale 4 table – see the example in Table 2, below.

Where tax file number not provided by payee Scale 4

Earnings Tax Rate

Resident

$1 & over 0.4650

Foreign

$1 & over 0.4500

Table 2 - Tax Scale 4 (as per published documentat ion) For implementation purposes, this table is split into two tax scale tables, one for Australian residents and one for Foreign Residents, as shown in Table 3. This ensures that all tax scale tables follow the same format.

Where tax file number not provided by payee

Where tax file number not provided by payee

Scale 4 Resident Scale 4 Foreign

Earnings a b Earnings a b

$1 & over 0.4650 0 $1 & over 0.4500 0

Table 3 - Tax Scale 4 - structured as two tables All Tax Scale tables have been converted to XML and packaged with the Schematron as part of this project.

3.2.2 Medicare Levy Parameters

The Medicare Levy Adjustment calculation uses dynamic parameters based on the tax scale being used in the withholding amount calculation.

Medicare Levy Parameters

Parameter Scale 2 Scale 6

Weekly earnings threshold 359 606

Weekly earnings shade-in threshold 422 713

Medicare levy family threshold 31514 31514

Weekly family threshold divisor 52 52

Additional child 2919 2919

Shading out point multiplier 0.1000 0.0500

Shading out point divisor 0.0850 0.0425

Weekly levy adjustment factor 359.1700 606.0400

Medicare levy 0.0150 0.0075

Table 4 – Example Medicare Levy Parameters This table has also been converted into XML format and packaged with the Schematron as part of this project.



3.3 NOTES ON PROCESS DESCRIPTIONS

The following section and subsections provide detailed descriptions of the process used to calculate the net withholding amount for a payee. Each section or subsection includes a process diagram and a table of input and output parameters. The process diagrams use the following symbols: � Arrows indicate the process flow. � Rectangles indicate processes or calculations. Calculations are described inside the

rectangle. Processes are described in more detail in another subsection. � Diamonds indicate decisions. Arrows leaving a diamond are labelled “Yes” or “No”. The

appropriate arrow should be followed depending on the outcome of the decision. � Trapezoids indicate data elements. The data elements may be inputs, outputs or

intermediary values. Intermediary values are usually the output of a subsidiary process or calculation and the input of another subsidiary process or calculation.

The input tables describe the Request/Response message elements or intermediary values that are used in a process. The output tables describe the elements or intermediary values that are produced by a process. In the tables, Request/Response message elements are enclosed in square brackets (“[“, “]”) and intermediary values are enclosed in angle brackets (“<”, “>”).

3.4 CALCULATE NET WITHHOLDING AMOUNT PROCESS

Figure 2 shows the steps required to calculate the Net Withholding Amount from a payee’s earnings, shown in Figure 1. The following subsections in this document explain each of these steps. For each individual step, a breakdown of it input/outputs is included.

ChooseTaxScale

Period Conversion(Period Earnings to Weekly Earnings)

CalculateWeekly

WithholdingNo

Calculate Adjustments(Medicare)

Calculate Offsets

Period Withholding Amount

Period Conversion(Weekly Withholding

Amount to Period Withholding)

No

Offset Amount

Unadjusted Weekly

Withholding

Medicare Adjustment Amount

Weekly Withholding Amount

Weekly Witholding = (Unadjusted Weekly

Withholding) –(Medicare Adjustment Amount)

Net Withholding Amount

Net Withholding mount = Period Withholding

Amount – Offset Amount

Offset Amount <= Period Withholding

Amount?

Yes

Net Withholding Amount = 0

No

TaxScale 4 Applied?

CalculateTax Scale 4 Withholding

Yes

Figure 2 - Calculate Net Withholding Amount



Inputs / Outputs

Inputs Diagram reference(s) Description

Validated TWC Request message

The TWC Request message is described in Section 4.1.1. The following subsections describe the usage of elements in the TWC Request message.

Outputs Diagram reference(s) Description

[TWC19] Net Withholding Amount

Net Withholding Amount

3.4.1 Choose Tax Scale

As detailed in Section 3.2, the Tax Withheld Calculator requires a number of dynamic parameters based on user input. The first step in the calculation process is to identify which tax scale table is to be used in subsequent decisions and calculations. Figure 3 details the process for selecting the tax scale table.



TFN provided?Australian Resident?

Claim Tax Free Threshold?

Tax Scale 4 Australian (NAT1004)

Tax Scale 4 Foreign (NAT1004)

Medicare Exemption = Full ?

Medicare Exemption = Half ?

Medicare Exemption = None ?

Yes

Yes

Yes

No

No

No

Yes

No

No

No

Yes

Yes

Yes

Tax Scale 3 (NAT3539)

HELP?

SFSS?

SFSS?

Yes

No




No

No

Yes

Yes


HELP?

SFSS?

SFSS?

Yes

No



No

No

Yes

Yes


HELP?

SFSS?

SFSS?

Yes

No



No

No

Yes

Yes


HELP?

SFSS?

SFSS?

Yes

No




No

No

Yes

Yes


HELP?

SFSS?

SFSS?

Yes

No




No

No

Yes

Yes

TFN Exemption?

No

Yes

Australian Resident?



Medicare Levy Variation Income Check satisfied?


No

Yes

No

Yes

No

Yes


Figure 3 - Choose Tax Scale

Inputs / Outputs

The following elements are required as Inputs/Outputs for the Choose Tax Scale Process. Inputs Diagram reference(s) Description

[TWC1] TFN Provided? Has the payee provided a Tax File Number (TFN)?

[TWC2] TFN Exemption? If the payee has not provided a TFN, is the payee exempt from needing a TFN?




[TWC3] Australian Resident? Is the payee an Australian Resident?

[TWC4] Claim Tax Free Threshold?

Has the payee claimed the Tax Free Threshold?

Medicare Exemption = Full? Medicare Exemption = Half?

[TWC6]

Medicare Exemption = None?

Payee claiming exemption or variation from the Medicare levy?

[TWC13] HELP? Does the payee have an accumulated Higher Education Loan Programme (HELP) debt?

[TWC14] SFSS? Does the payee have an accumulated Financial Supplement debt?

[TWC15] Medicare Levy Variation Income Check satisfied?

Medicare levy variation income check


<tax scale table> This is used in a number of decision points and calculations throughout the calculation.

3.4.2 Calculate Tax Scale 4 Withholding

The Calculate Tax Scale 4 Withholding process provides the withholding amount when Tax scale for 4 is required.

Figure 4 - Calculate Tax Scale 4 Witholding

Inputs / Outputs

Input Values Diagram reference(s) Description

[TWC12] Apply Formula y=ax Period earnings.

<tax scale table data> Apply Formula y=ax For Tax Scale 4, this is simply the percentage rate (<a>)

<a> Apply Formula y=ax Dynamic lookup from <tax scale table data> based on <tax scale table> and <weekly earnings> amount.

Output Values Diagram reference(s) Description

[TWC16] Withholding Amount The amount of tax applicable for the period.

For Tax Scale 4, Tax Applicable = Net Withholding amount



3.4.3 Period Conversion

During the calculation process, there are a number of times where an amount needs to be converted between the fortnightly/monthly/quarterly amounts and weekly amounts. The following two figures describe the conversion process to a weekly amount, and back to the original fortnightly/monthly/quarterly amount.

3.4.3.1 Convert Period Earnings to Weekly Earnings

Period = Weekly?

Period Earnings

Period = Fortnightly?

Period = Monthly?

Period = Quarterly?

(PeriodEarnings / 2)

No

No

No

Yes

Yes

Weekly Earnings (x)

PeriodEarnings ends with 33c?

PeriodEarnings = PeriodEarnings +

$0.01

(PeriodEarnings * 3) / 13

No

Yes

(PeriodEarnings / 13)

Yes

Yes

UnadjustedWeeklyEarn

ings

Unadjusted WeeklyEarnings ignoring cents +

$0.99

Figure 5 - Convert Period Earnings to Weekly Earni ngs

Inputs / Outputs

The following elements are required as Inputs/Outputs for the Convert Period Earnings to Weekly Process.




Period = Weekly?


Period = Monthly?

[TWC11]

Period = Quarterly?

Payee payments period

[TWC12] Period Earnings Gross earnings (for given period)


<weekly earnings>

Weekly Earnings (x) Period earnings converted to weekly equivalent.

3.4.3.2 Convert Weekly Amount to Period Amount

This process is used multiple times to convert various weekly amounts

1) Weekly Withholding to Period Withholding 2) Unadjusted Weekly Withholding to Period Withholding Amount (required in response

output) 3) Medicare Adjustment Amount to Period Medicare Adjustment (required in response

output)

Figure 6 - Convert Weekly Amount to Period Amount



Inputs / Outputs

The following elements are required as Inputs/Outputs for the Convert Convert Weekly Amount to Period Amount Process. This process is required to be run three times during the calculation with different input value pairs. 1. Conversion of Weekly Withholding amount from weekly to the original period for use in

further calculations: Type Input Value Diagram reference(s) Description

Period = Weekly?


Period = Monthly?

Input [TWC11]

Period = Quarterly?


Input <Weekly Withholding Amount>

Weekly Amount Weekly Withholding Amount

Output <Period Withholding Amount>

Period Amount

2. Conversion of Unadjusted Weekly Withholding amount back to the original period. This is

only required for the calculator output: Type Input Value Diagram reference(s) Description

Period = Weekly?


Period = Monthly?

Input [TWC11]

Period = Quarterly?


Input <Unadjusted Weekly Withholding>

Weekly Amount

Output [TWC16] Period Amount The amount of tax applicable for the period.

3. Conversion of Medicare Adjustment amount back to the original period. This is only required

for the calculator output: Type Input Value Diagram reference(s) Description

Period = Weekly?


Period = Monthly?

Input [TWC11]

Period = Quarterly?


Input <Medicare Adjustment Amount>

Weekly Amount

Output [TWC18] Period Amount Medicare levy adjustment amount for the period



3.4.4 Calculate Unadjusted Weekly Withholding

The Calculate Weekly Withholding process provides the base withholding amount prior to any adjustments or offsets are applied.

Figure 7 - Calculate Unadjusted Weekly Witholding

Inputs / Outputs

Input Values Diagram reference(s) Description

<weekly earnings> Apply Formula y=ax-b Weekly earnings after conversion from period earnings

<tax scale table data> Apply Formula y=ax-b Tax Scale table selected by Choose Tax Scale process

<a> Apply Formula y=ax-b Dynamic lookup from <tax scale table data> based on <tax scale table> and <weekly earnings> amount

<b> Apply Formula y=ax-b Dynamic lookup from <tax scale table data> based on <tax scale table> and <weekly earnings> amount

Output Values Diagram reference(s) Description

<Unadjusted Weekly Withholding>

Unadjusted Weekly Withholding

Applying y = ax - b

After selecting the tax scale that is to be used, the following formula is applied to calculate weekly tax withheld:

y = ax - b Where

y = weekly tax withheld (prior to adjustments/offsets) x = weekly earnings a = coefficient a from the appropriate tax scale table b = coefficient b from the appropriate tax scale table

As an example, if the tax scale 1 was used (see Table 1, Section 3.2.1) and weekly earnings was $300, the equation would look like:

y = (0.2284) * (300) – (16.4569)

3.4.5 Calculate Medicare Levy Adjustment Amount

The Medicare levy adjustment process consists of a number of steps as detailed in the following sections. The adjustment calculation uses dynamic parameters based upon the tax scale table being used in the overall calculation. The parameters are defined in the Medicare levy parameters table. All dynamic variables have been highlighted in the following flow charts using bold italics.



Calculate WFT

Calculate SOP

Calculate WLA

Medicare Adjustment Amount

x >= [WeeklyEarningsThre

shold] ?Yes

No

Has Spouse?Number of

Dependents > 0?No

Yes

Medicare Adjustment Amount = 0

No

Claim reduced levy?

Yes

Yes Scale 2 or 6?

Yes

Yes

No


Figure 8 - Calculate Medicare Levy Adjustment Amou nt

Inputs / Outputs

Input Diagram reference(s) Description

[TWC7] Claim Reduced Levy? Payee claiming reduced amount of levy

[TWC8] Has Spouse? Does the payee have a spouse?

[TWC9] Number of Dependents >0 ? Number of dependent children claimed?

[TWC15] Medicare Levy Variation Income Check satisfied?

Medicare levy variation income check

<Weekly Earnings Threshold>

x >= [WeeklyEarningsThreshold] ?

Dynamic lookup from Medicare levy parameters table

<Weekly earnings> x >= [WeeklyEarningsThreshold] ?

From Weekly Amount to Period Amount

<tax scale table> Scale 2 or 6? Required for dynamic lookup of Medicare Levy




x >= [WeeklyEarningsThreshold]?

Parameters

Output Diagram reference(s) Description

[TWC18] Medicare Adjustment Amount Medicare Adjustment Amount

3.4.5.1 Calculate Weekly Family Threshold

The Calculate Weekly Family Threshold (WFT) is the first of three sub-calculations within the Medicare Adjustment calculation. The WFT value is required in the Weekly Levy Adjustment (WLA) calculation.

Figure 9 - Calculate Weekly Famity Threshold (WFT)

Inputs / Outputs


[TWC9] Number of dependents > 0? Number of dependent children claimed

<AdditionalChildRate> ((AdditionalChildRate * Number of Dependents) + MedicareLevyFamilyThreshold) / WeeklyFamilyThresholdDivisor

Dynamic lookup from Medicare table

<MedicareLevyFamily Threshold>

((AdditionalChildRate * Number of Dependents) + MedicareLevyFamilyThreshold) / WeeklyFamilyThresholdDivisor


<WeeklyFamily ThresholdDivisor>

((AdditionalChildRate * Number of Dependents) + MedicareLevyFamilyThreshold) / WeeklyFamilyThresholdDivisor


<tax scale table> ((AdditionalChildRate * Number of Dependents) + MedicareLevyFamilyThreshold) /

Required for dynamic lookup of Medicare Levy Parameters




WeeklyFamilyThresholdDivisor


<WFT> WFT Weekly Family Threshold

3.4.5.2 Calculate Shading Out Point

The Calculate Shading Out Point (SOP) is the second of three sub-calculations within the Medicare Adjustment calculation. The SOP value is required in the Weekly Levy Adjustment (WLA) calculation.

Figure 10 - Calculate Shading Out Point (SOP)

Inputs / Outputs


<WFT> (WFT * SOPMultiplier) / SOPdivisor From WFT calculation

<SOP Multiplier> (WFT * SOPMultiplier) / SOPdivisor Dynamic lookup from Medicare levy parameters table

<SOP divisor> (WFT * SOPMultiplier) / SOPdivisor Dynamic lookup from Medicare levy parameters table

<tax scale table> (WFT * SOPMultiplier) / SOPdivisor Required for dynamic lookup of Medicare Levy Parameters


<SOP> SOP Shading Out Point

3.4.5.3 Calculate Weekly Levy Adjustment

The Calculate Weekly Levy Adjustment (WLA) is the final of three sub-calculations within the Medicare Adjustment calculation. Note that the WLA value is represented as Medicare Adjustment Amount in Figure 8.



Figure 11 - Calculate Weekly Levy Adjustment (WLA) Inputs / Outputs


<weekly earnings> x

x < [shade in threshold] ? <shade in threshold>

[shade in threshold] <= x < WFT ?


<WeeklyLevy Adjustment Factor>

(x – WeeklyLevyAdjustFactor) * ShadeOutMultiplier


<Shade Out Multiplier> (x – WeeklyLevyAdjustFactor) * ShadeOutMultiplier


<MedicareLevy> (WFT * MedicareLevy) – ((x – WFT) * SOPdivisor)



(WFT * MedicareLevy) – ((x – WFT) * SOPdivisor)

<WFT>

WFT <= x < SOP ?

Weekly Family Threshold

WFT <= x < SOP ? <SOP>

x >= SOP ?

Shading Out Point

<SOP Divisor> (WFT * MedicareLevy) – ((x – WFT) * SOPdivisor)


x < [shade in threshold] ?


(x – WeeklyLevyAdjustFactor) * ShadeOutMultiplier

WFT * MedicareLevy) – ((x – WFT) * SOPdivisor)

<Medicare parameter table>

(WFT * MedicareLevy) – ((x – WFT) *

Required for dynamic lookup of Medicare Levy Parameters




SOPdivisor)

Output Diagram reference(s) Description

<WLA> Weekly Levy Adjustment Weekly Levy Adjustment

3.4.6 Calculate Offset Amount

The last step of the calculation process is to calculate and apply tax offsets. This calculation is applied on the input data without conversion to/from the specified period. The process takes into consideration the period by varying the percentage rate for each.

Period = Weekly?


Period = Monthly?

Period = Quarterly?

No

No

No

Yes

Tax offsets * 1.9%

Tax offsets * 3.8%

Tax offsets * 8.3%

Tax offsets * 25%

Yes

Yes

Yes

Yes

No

Yes

Tax offsets > $0 ?

Offset = 0

Round to nearest dollar

Offset Amount

NoScale 2, 5 or 6

used?

Figure 12 - Calculate Offset Amount

Inputs / Outputs

Element Diagram reference(s) Description

[TWC11] Period = Weekly?


Period = Monthly?




Element Diagram reference(s) Description

Period = Quarterly?

[TWC5] Tax Offsets * 1.9%

Tax Offsets * 3.8%

Tax Offsets * 8.3%

Tax Offsets * 25%

Amount the payee claimed for Tax offsets

<tax scale table> Scale 2, 5 or 6 used?

Outputs Diagram reference(s) Description <Offset amount> Offset Amount



4 TWC INTERACTION MODEL

4.1 SUMMARY

The following sections define the input and outputs of the TWC. Where possible, existing SBR definitional taxonomy elements have been used in the schema. Where no suitable SBR element exists, element names have been named using the SBR element naming conventions.

4.1.1 TWC Request - Message

4.1.1.1 Schema references

Schema sbdm.02.00.data.xsd (contained within SBR WSDL)

4.1.1.2 Standard Business Document Header Content

Please see Appendix C & D for details of specific SBDH data element values and validation rules in the request message.

4.1.1.3 Schema references

Schema TaxWithholdingCalculationRequest.xsd

4.1.1.4 Standard Business Document Body Content

The following describes the facts required to be supplied within the SBDB element BusinessDocument.instance.text

XML Seq No.

ID Fact Cardinality

Element Datatype

Instructions / Rules Rule Imp. Msg Code

1 [TWC1] Has the payee provided a Tax File Number (TFN)

1..1 Identifiers.TaxFileNumberExistent.Indicator

xs:boolean 1. IF [TWC1] = NULL

RETURN VALIDATION MESSAGE

ENDIF

1. Schematron ID = VR.ATO.TWC.001

1. CMN.ATO.TWC.001



XML Seq No.

ID Fact Cardinality

Element Datatype


2 [TWC2] If the payee has not provided a TFN, is the payee exempt from needing a TFN

1..1 IdentificationExemptionDetails.TFNExemption.Indicator

xs:boolean 1. IF [TWC1] = FALSE AND [TWC2] = NULL


ENDIF


1. CMN.ATO.TWC.002

3 [TWC3] Is the payee an Australian Resident

1..1 Residency.TaxPurposesPersonStatus.Indicator

xs:boolean 1. IF [TWC3] = NULL


ENDIF


1. CMN.ATO.TWC.003

4 [TWC4] Has the payee claimed the Tax Free Threshold

1..1 TaxOffsetClaim.TaxFreeThreshold.Indicator

xs:boolean 1. IF ([TWC1] = TRUE OR ([TWC1] = FALSE AND [TWC2] = TRUE))

AND [TWC3] = TRUE AND [TWC4] = NULL


ENDIF


1. CMN.ATO.TWC.004

5 [TWC5] Amount the payee claimed for Tax offsets $

1..1 IncomeTax.TaxOffsetsAndRebatesTotal.Amount

xs:decimal 1. IF [TWC5] <> NULL AND [TWC5] < 0


ENDIF


1. CMN.ATO.TWC.005



XML Seq No.

ID Fact Cardinality

Element Datatype


6 [TWC6] Payee claiming exemption or variation from the Medicare levy

1..1 IncomeTax.MedicareLevy.Exemption.Code

xs:enumeration

N(No)

H(Half)

F(Full)

1. IF ([TWC1] = TRUE OR ([TWC1] = FALSE AND [TWC2] = TRUE))

AND [TWC3] = TRUE AND [TWC4] = TRUE AND [TWC6] = NULLORBLANK


ENDIF

2. IF [TWC6] <> NULLORBLANK AND [TWC6] <> SET("F","H","N")


ENDIF



1. CMN.ATO.TWC.006

2. CMN.ATO.TWC.007

7 [TWC7] Payee claiming reduced amount of levy

1..1 IncomeTax.MedicareLevy.Exemption.Indicator


AND [TWC3] = TRUE AND [TWC4] = TRUE AND [TWC6] = SET("H","N") AND [TWC7] = NULL


ENDIF


1. CMN.ATO.TWC.008



XML Seq No.

ID Fact Cardinality

Element Datatype


8 [TWC8] Does the payee have a spouse

1..1 TaxOffsetClaim.DependantSpouse.Indicator


AND [TWC3] = TRUE

AND [TWC4] = TRUE

AND [TWC6] = SET("H","N")

AND [TWC7] = TRUE

AND [TWC15] = TRUE

AND [TWC8] = NULL


ENDIF


1. CMN.ATO.TWC.009

9 [TWC9] Number of dependent children claimed

1..1 IncomeTax.MedicareLevy.DependentChildrenAndStudents.Count

xs:int 1. IF ([TWC1] = TRUE OR ([TWC1] = FALSE AND [TWC2] = TRUE))

AND [TWC3] = TRUE AND [TWC4] = TRUE AND [TWC6] = SET("H","N") AND [TWC7] = TRUE AND [TWC15] = TRUE AND [TWC9] = NULL


ENDIF

2. IF [TWC9] <> NULL AND [TWC9] < 0


ENDIF



1. CMN.ATO.TWC.010

2. CMN.ATO.TWC.011



XML Seq No.

ID Fact Cardinality

Element Datatype


11 [TWC11] Payee payments period

1..1 Income.PaymentPeriod.Code xs:enumeration

W(Weekly)

F(Fortnightly)

M(Monthly)

Q(Quarterly)

1. IF [TWC11] = NULLORBLANK


ENDIF

2. IF [TWC11] <> NULLORBLANK AND [TWC11] <> SET("W","F","M","Q")


ENDIF



1. CMN.ATO.TWC.013

2. CMN.ATO.TWC.014

12 [TWC12] Gross earnings (for given period)

1..1 Income.Gross.Amount xs:decimal 1. IF [TWC12] = NULL


ENDIF

2. IF [TWC12] <> NULL AND [TWC12] <=0


ENDIF



1. CMN.ATO.TWC.015

2. CMN.ATO.TWC.016



XML Seq No.

ID Fact Cardinality

Element Datatype


13 [TWC13] Does the payee have an accumulated Higher Education Loan Programme (HELP) debt

1..1 StudentLoan.HigherEducationLoanProgramme.Indicator


AND [TWC3] = FALSE AND [TWC13] = NULL


ENDIF


AND [TWC3] = TRUE AND [TWC4] = FALSE AND [TWC13] = NULL


ENDIF


AND [TWC3] = TRUE AND [TWC4] = TRUE AND [TWC15] = FALSE AND [TWC13] = NULL


ENDIF




1. CMN.ATO.TWC.017

2. CMN.ATO.TWC.018

3. CMN.ATO.TWC.019



XML Seq No.

ID Fact Cardinality

Element Datatype


14 [TWC14] Does the payee have an accumulated Financial Supplement debt

1..1 StudentLoan.StudentFinancialSupplementScheme.Indicator


AND [TWC3] = FALSE AND [TWC14] = NULL


ENDIF


AND [TWC3] = TRUE AND [TWC4] = FALSE AND [TWC14] = NULL


ENDIF


AND [TWC3] = TRUE AND [TWC4] = TRUE AND [TWC15] = FALSE AND [TWC14] = NULL


ENDIF




1. CMN.ATO.TWC.020

2. CMN.ATO.TWC.021

3. CMN.ATO.TWC.022



XML Seq No.

ID Fact Cardinality

Element Datatype


15 [TWC15] Combined weekly income of payee and payee’s spouse,

or the payee’s income as a sole parent, less than the relevant amount in table A?

(Medicare levy variation income check)

1..1 IncomeTax.MedicareLevy.CombineOrSoleParentIncome.Indicator


AND [TWC3] = TRUE AND [TWC4] = TRUE AND [TWC15] = NULL


ENDIF


1. CMN.ATO.TWC.023

16 [TWC21] Indicator to enable diagnostic output.

0..1 DiagnositcOutput.Indicator xs:boolean



4.1.2 TWC Response - Message

4.1.2.1 Schema Reference

Schema TaxWithholdingCalculationResponse.xsd

4.1.2.2 Standard Business Document Header Content

Please see Appendix E for details of specific SBDH data element values the response message.

4.1.2.3 Standard Business Document Body Content

The following describes the facts within the XML response document populated in the SBDB element BusinessDocument.instance.text

XML Seq No.

ID Fact Cardinality

Element Datatype


1 [TWC12] Gross weekly/fortnightly/monthly/quarterly earnings

1..1 Income.Gross.Amount xs:decimal n/a n/a n/a

2 [TWC16] Tax Applicable

1..1 IncomeTax.PayAsYouGoWithholding.Tax.Amount

xs:decimal n/a n/a n/a

3 [TWC17] Tax offsets 1..1 IncomeTax.PayAsYouGoWithholding.TaxOffset.Amount


4 [TWC18] Less Medicare Levy Adjustment

1..1 IncomeTax.PayAsYouGoWithholding.MedicareLevyAdjustment.Amount




XML Seq No.

ID Fact Cardinality

Element Datatype


5 [TWC19] Tax Withheld

1..1 IncomeTax.PayAsYouGoWithholding.TaxWithheld.Amount

xs:decimal n/a n/a

6 [TWC20] Net Pay

1..1 Income.Net.Amount

xs:decimal [TWC20] = [TWC12] – [TWC19]

n/a n/a

The following table describes the additional facts within the XML response when the DiagnositcOutput.Indicator ([TWC21]) = True in the request message.

XML Seq No.

ID

Fact Cardin-

ality Element Datatype

Description Rule Imp. Msg Code

7 System Diagnostic 1..1 System.Diagnostic n/a n/a n/a

7.1 Tax Schedule 1..1 TaxSchedule xs:string The schedule that the tax scale is sourced

n/a n/a

7.2 Tax Scale Value 1..1 TaxScaleValue xs:string The tax scale used in the calculation n/a n/a

7.3 Weekly Earnings 1..1 WeeklyEarnings xs:decimal The equivalent weekly earnings amount

n/a n/a

7.4 Tax Scale To Be Applied 1..1 TaxScaleToBeApplied n/a Displays the various details of the tax scale table used in the calculations.

n/a n/a

7.4.1 WeeklyEarningCoefficients 1..1 WeeklyEarningCoefficients n/a n/a n/a

7.4.1.1 Weekly Earnings Threshold 1..1 WeeklyEarningsThreshold xs:decimal n/a n/a

7.4.1.2 Coefficient A 1..1 CoefficientA xs:decimal n/a n/a

7.4.1.2 Coefficient B 1..1 CoefficientB xs:decimal n/a n/a

7.5 Unadjusted Weekly Withholding 1..1 UnadjustedWeeklyWithholding The unadjusted weekly withholding amount

n/a n/a



XML Seq No.

ID

Fact Cardin-

ality Element Datatype

Description Rule Imp. Msg Code

7.6 Medicare Levy Parameter 1..1 MedicareLevyParameter n/a Displays the Medicare levy parameters table that is used for the calculations.

n/a n/a

7.6.1 Tax 1..1 Tax n/a n/a n/a

7.6.1.1 WeeklyEarningsThreshold 1..1 WeeklyEarningsThreshold xs:decimal n/a n/a

7.6.1.2 WeeklyEarningsShadeInThreshold

1..1 WeeklyEarningsShadeInThreshold

xs:decimal n/a n/a

7.6.1.3 MedicareLevyFamilyThreshold 1..1 MedicareLevyFamilyThreshold xs:decimal n/a n/a

7.6.1.4 WeeklyFamilyThresholdDivisor 1..1 WeeklyFamilyThresholdDivisor xs:decimal n/a n/a

7.6.1.5 AdditionalChild 1..1 AdditionalChild xs:decimal n/a n/a

7.6.1.6 ShadingOutPointMultiplier 1..1 ShadingOutPointMultiplier xs:decimal n/a n/a

7.6.1.7 ShadingOutPointDivisor 1..1 ShadingOutPointDivisor xs:decimal n/a n/a

7.6.1.8 WeeklyLevyAdjustmentFactor 1..1 WeeklyLevyAdjustmentFactor xs:decimal n/a n/a

7.6.1.9 MedicareLevy 1..1 MedicareLevy xs:decimal n/a n/a

7.7 MedicareAdjustmentAmount 1..1 MedicareAdjustmentAmount xs:decimal The Medicare adjustment amount to be applied to the withholding.

n/a n/a

7.8 TaxOffsetPercentage 1..1 TaxOffsetPercentage xs:decimal The percentage rate used to calculate the tax offset amount

n/a n/a



APPENDIX A – THE MESSAGE CONTENT TABLE EXPLAINED This section defines the table structure that defines the data elements contained within the XML instance document – referred to as the message content table.

The message content table uses the following rows and columns:

Message Type (row at top of table) : This is the name of the schema which has been defined early in the MIG document.

Sequence Number: This is a sequential number used to indicate the expected order of the data elements within the request document.

XML Seq No.

Fact

Cardinality

0..1 Element Datatype


1 Requestor Reference

1..1 ReferenceIdentifier

xs:string

1. 1. 1.

Fact : This is the logical name of the element to be submitted.

Cardinality : Specifies the minimum and maximum number of element instances to be submitted.

XML: Element : The name of the XML element to be submitted

XML: Datatype : The basic XML schema datatype of the element

Instructions / Rules : This column describes all the instructions / rules applicable to the data element. Each rule needs to be given a sequential number which links the rule to its implementation and message code. Rules would include information such as optionality, presentation criteria and the use of XML attributes such as IsVisible.

Rule Implementation : Rule reference identifier.

Message Code : All messages returned via the TWC channel will contain a code to uniquely identify the condition that has occurred.



APPENDIX B – RESPONSE MESSAGES The following table contains response messages returned by the TWC: Message Code Severity Short Description CMN.TWC.GEN.OK Information The calculation has been processed successfully CMN.TWC.GEN.F00001 Error Field not supplied in valid xs:boolean format CMN.TWC.GEN.F00002 Error Field not supplied in valid xs:dateTime format CMN.TWC.GEN.F00003 Error Field not supplied in valid xs:integer format CMN.TWC.GEN.F00004 Error Field not supplied in valid xs:string format CMN.TWC.GEN.F00005 Error Field not supplied in valid xs:date format CMN.TWC.GEN.F00006 Error Field not supplied in valid xs:decimal format CMN.ATO.GEN.100001 Error SBDH: Mandatory Field is required CMN.ATO.GEN.100002 Error SBDH:Valid Message.Type.Text is required CMN.ATO.GEN.100003 Error SBDH: BusinessDocument required for each

BusinessDocumentInstance CMN.ATO.GEN.100004 Error SBDH: Valid URI is required CMN.ATO.GEN.100005 Error SBDH: Attachments are not accepted CMN.ATO.GEN.100006 Error Must be the same as the Schema Ref element in the XML

payload CMN.ATO.GEN.100007 Error SBDH: Valid Message.Timestamp.GenerationSource.Code is

required CMN.ATO.GEN.100000 Error SBDH: Field not supplied in correct format CMN.ATO.GEN.100008 Error SBDH: Valid IdentificationDetails.IdentifierDesignation.Text is

required CMN.ATO.GEN.100009 Error SBDH: Valid IdentificationDetails.Identifier.Name.Text is

required CMN.ATO.GEN.100010 Error SBDH: Invalid BusinessDocument.Sequence.Number provided CMN.ATO.GEN.100011 Error SBDH: Field not supplied in valid xs:anyType format CMN.ATO.GEN.100012 Error SBDH: Field not supplied in valid xs:dateTime format CMN.ATO.GEN.100013 Error SBDH: Field not supplied in valid xs:integer format CMN.ATO.GEN.100014 Error SBDH: Field not supplied in valid xs:string format

The following table contains the specific response messages returned by the TWC: Message Code Severity Short Description Long Description CMN.ATO.TWC.001 Error TFN Provided

indicator is required Indicate whether the payee has provided a Tax File Number (TFN).

CMN.ATO.TWC.002 Error TFN Exemption indicator is required

Indicate whether the payee is exempt from needing a Tax File Number (TFN). This is required when the payee has not provided a TFN.

CMN.ATO.TWC.003 Error Australian Resident indicator is required

Indicate whether the payee is an Australian Resident.

CMN.ATO.TWC.004 Error Claim Tax Free Threshold indicator is required

Indicate whether the Tax Free Threshold is being claimed. This is required when the payee has provided a Tax File Number (TFN) or has a TFN exemption and is an Australian resident.

CMN.ATO.TWC.005 Error Tax Offset must be $0 or greater

CMN.ATO.TWC.006 Error Medicare Exemption/Variation code is required

Indicate the type of Medicare Exemption/Variation the payee is claiming. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident and is



Message Code Severity Short Description Long Description claiming the Tax Free Threshold.

CMN.ATO.TWC.007 Error Medicare Exemption/Variation code must be F, H or N

Medicare Exemption/Variation code must be F(full), H(half) or N(none).

CMN.ATO.TWC.008 Error Claim Reduced Levy indicator is required

Indicate whether the payee is Claiming a Reduced Amount of Levy. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident, is claiming the Tax Free Threshold and is claiming no or half Medicare Levy Exemption/Variation.

CMN.ATO.TWC.009 Error Has Spouse indicator is required

Indicate whether the payee has a Spouse. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident, is claiming the Tax Free Threshold, is claiming reduced amount of Levy and is claiming no or half Medicare Levy Exemption/Variation.

CMN.ATO.TWC.010 Error Number of Dependent Children required

Number of Dependent Children is required. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident, is claiming the Tax Free Threshold, is claiming reduced amount of Levy, is claiming no or half Medicare Levy Exemption/Variation and has combined weekly income of payee and payee’s spouse, or the payee’s income as a sole parent, less than the relevant amount in table A (Medicare levy variation declaration).

CMN.ATO.TWC.011 Error Number of Dependent Children must be 0 or greater

CMN.ATO.TWC.013 Error Payment period code is required

CMN.ATO.TWC.014 Error Payment period code must be W, F, M or Q

Payment period must be W(weekly), F(fortnightly), M(monthly) or Q(quarterly)

CMN.ATO.TWC.015 Error Gross Earnings amount is required

CMN.ATO.TWC.016 Error Gross Earnings amount must be greater than $0

CMN.ATO.TWC.017 Error HELP indicator required

Indicate whether the payee has an accumulated Higher Education Load Programme (HELP) debt. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption and is not an Australian resident.

CMN.ATO.TWC.018 Error HELP indicator required

Indicate whether the payee has an accumulated Higher Education Load Programme (HELP) debt. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident and is not claiming the Tax Free Threshold.

CMN.ATO.TWC.019 Error HELP indicator Indicate whether the payee has an



Message Code Severity Short Description Long Description required accumulated Higher Education Load

Programme (HELP) debt. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident, is claiming the Tax Free Threshold and does not have a combined weekly income of payee and payee’s spouse, or the payee’s income as a sole parent, less than the relevant amount in table A (Medicare levy variation declaration).

CMN.ATO.TWC.020 Error SFSS indicator required

Indicate whether the payee has an accumulated Financial Supplement (SFSS) debt. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption and is not an Australian resident.


Indicate whether the payee has an accumulated Financial Supplement (SFSS) debt. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident and is not claiming the Tax Free Threshold.


Indicate whether the payee has an accumulated Financial Supplement (SFSS) debt. This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident, is claiming the Tax Free Threshold and does not have a combined weekly income of payee and payee’s spouse, or the payee’s income as a sole parent, less than the relevant amount in table A (Medicare levy variation declaration).

CMN.ATO.TWC.023 Error Medicare Levy Variation Income Check indicator required

Indicate whether the payee has combined income less than the relevant amount in table A? (Medicare levy variation income check). This is required when the payee has provided a Tax File Number (TFN) or TFN exemption, is an Australian resident and is claiming the Tax Free Threshold.



APPENDIX C – SBDH REQUEST ELEMENTS Mandatory Transaction Target Field Type Schema

Occurs Local Service

Value

StandardBusinessDocumentMessage

StandardBusinessDocumentHeader StandardBusinessDocumentHeaderType 1-1 M M StandardBusinessDocumentBody StandardBusinessDocumentBodyType 0-1 M M StandardBusinessDocumentHeaderType

Message.Type.Text xs:string 1-1 M M Value must be set to "twc.calculate.01.01.request"

MessageTimeStamps MessageTimestampsType 1-1 O M

Sender PartyType - Sender 0-1 O O

Receiver PartyType - Receiver 0-1 O O

LodgementReceipt LodgementReceiptType 0-1 Not Required for Request

SoftwareInformation SoftwareInformationType 0-1 O M

BusinessDocuments BusinessDocumentsType 0-1 M M Required for request

MessageEvent MessageEventType 0-1 Not Required for Request

MessageTimestampsType

MessageTimestamp MessageTimestampType 1-N O M One or more Timestamps for Request

MessageTimestampType

Message.Timestamp.Generation.Datetime xs:dateTime 1-1 O M To be stored for usage logging

Message.Timestamp.GenerationSource.Code xs:string 1-1 O M To be stored for usage logging

PartyType - Sender

IdentificationDetails.Identifier.Designation.Text xs:string 1-1 O M

IdentificationDetails Identifier Name.Text xs:string 1-1 O M Value must be 'AgencyInternetDomainName'

PartyType - Receiver

IdentificationDetails.Identifier.Designation.Text xs:string 1-1 O M Value must be 'ato.gov.au'

IdentificationDetails Identifier Name.Text xs:string 1-1 O M Value must be 'AgencyInternetDomainName'

LodgementReceiptType

Lodgement.Receipt.Identifier xs:string 0-1 Not Required for Request

Lodgement.Receipt.Datetime xs:dateTime 1-1 Not Required for Request



Mandatory Transaction Target Field Type Schema Occurs Local Service

Value

SoftwareInformationType

OrganisationNameDetails.OrganisationalName.Text xs:string 1-1 O M To be stored for usage logging

SoftwareInformation.ProductName.Text xs:string 1-1 O M To be stored for usage logging

SoftwareInformation.ProductVersion.Text xs:string 1-1 O M To be stored for usage logging

BusinessDocumentsType

BusinessDocument BusinessDocumentType 1-N M M One BusinessDocument for Lodge

BusinessDocumentType

BusinessDocument.Sequence.Number xs:integer 1-1 M M Value must be 1

BusinessDocument.Creation.Datetime xs:dateTime 1-1 M M Set value to Current timestamp

BusinessDocument.ValidationUniformResourceIdentifier.Text xs:string 1-1 M M Set to URI of business document

BusinessDocument.BusinessGeneratedIdentifier.Text xs:string 0-1 M M Must be the same as the Schema Ref element in the payload (Absolute Reference)

BusinessDocument.GovernmentGeneratedIdentifier.Text xs:string 0-1 Not Required for Request

Attachments AttachmentsType 0-1 Out of Scope

AttachmentsType

Attachment AttachmentType 1-1 Out of Scope

AttachmentType

Message.Attachment.Sequence.Number xs:integer 1-1 Out of Scope

Message.Attachment.FileName.Text xs:string 0-1 Out of Scope

Message.Attachment.Description.Text xs:string 0-1 Out of Scope

MessageEventType

Message.Event.MaximumSeverity.Code xs:string 1-1 Not Required for Request

MessageEventItems MessageEventItemsType 1-1 Not Required for Request

MessageEventItemsType

MessageEventItem MessageEventItemType 1-N Not Required for Request

MessageEventItemType

Message.Event.Item.Error.Code xs:string 1-1 Not Required for Request

Message.Event.Item.Severity.Code xs:string 1-1 Not Required for Request




Value

ShortDescriptions MessageEventItemShortDescriptionsType 0-1 Not Required for Request DetailedDescriptions MessageEventItemDetailedDescriptionsType 0-1 Not Required for Request

Parameters MessageEventItemParametersType 0-1 Not Required for Request

Locations MessageEventItemLocationsType 0-1 Not Required for Request

MessageEventItemShortDescriptionsType

Message.Event.Item.Short.Description xs:anyType 0-N Not Required for Request

MessageEventItemDetailedDescriptionsType

Message.Event.Item.Detailed.Description xs:anyType 0-N Not Required for Request

MessageEventItemParametersType

Message.Event.Item.Parameter xs:string 1-N Not Required for Request

MessageEventItemLocationsType

Location MessageEventItemLocationType 1-N Not Required for Request

MessageEventItemLocationType

BusinessDocument.Sequence.Number xs:integer 1-1 Not Required for Request

Message.Event.Item.Location.Path.Text xs:string 0-1 Not Required for Request

StandardBusinessDocumentBodyType

BusinessDocumentInstances BusinessDocumentInstancesType 1-1 M M

AttachmentInstances AttachmentInstancesType 0-1 Out of Scope

BusinessDocumentInstancesType

BusinessDocumentInstance BusinessDocumentInstanceType 1-N M M Maximum of 1 instance

BusinessDocumentInstanceType

BusinessDocument.Sequence.Number xs:integer 1-1 M M Value must be 1

BusinessDocument.Instance.Text xs:string 1-1 M M TWC Request

AttachmentInstancesType

AttachmentInstance AttachmentInstanceType 1-N Out of Scope



Message.Attachment.Instance.BinaryObject xmime:base64Binary 1-1 Out of Scope

Message.Attachment.Instance.BinaryObject.contentType xs:string (Attribute) 1-1 Out of Scope



APPENDIX D – SBDH REQUEST VALIDATION RULES Transaction Source Field Type Validation Rule (Error

Condition) Validation Rule ID Error Message ID

StandardBusinessDocumentMessage StandardBusinessDocumentHeader StandardBusinessDocumentHeader

Type IF StandardBusinessDocumentHeader = NULL RETURN VALIDATION MESSAGE ENDIF

VR.ATO.GEN.100004 CMN.ATO.GEN.100001

StandardBusinessDocumentBody StandardBusinessDocumentBodyType

IF StandardBusinessDocumentBody = NULL RETURN VALIDATION MESSAGE ENDIF


StandardBusinessDocumentHeaderType Message.Type.Text Message.Type.TextType IF

StandardBusinessDocumentHeader <> NULL AND Message.Type.Text = NULLORBLANK RETURN VALIDATION MESSAGE ENDIF


Message.Type.Text Message.Type.TextType IF Message.Type.Text <> SET(DOMAIN(RequestMessageType)) RETURN VALIDATION MESSAGE ENDIF


MessageTimeStamps MessageTimestampsType Sender PartyType Receiver PartyType LodgementReceipt LodgementReceiptType



Transaction Source Field Type Validation Rule (Error Condition)

Validation Rule ID Error Message ID

SoftwareInformation SoftwareInformationType BusinessDocuments BusinessDocumentsType IF

StandardBusinessDocumentHeader <> NULL AND BusinessDocuments = NULL RETURN VALIDATION MESSAGE ENDIF


MessageEvent MessageEventType MessageTimestampsType MessageTimestamp MessageTimestampType MessageTimestampType Message.Timestamp.Generation.Datetime

Message.Timestamp.Generation.DatetimeType

Message.Timestamp.GenerationSource.Code

Message.Timestamp.GenerationSource.CodeType

Message.Timestamp.GenerationSource.Code

Message.Timestamp.GenerationSource.CodeType

PartyType - Sender IdentificationDetails.Identifier.Designation.Text

IdentificationDetails.IdentifierDesignation.TextType

IdentificationDetails Identifier Name.Text IdentificationDetails.IdentifierName.TextType


PartyType - Receiver IdentificationDetails.Identifier.Designation.Text


IdentificationDetails.Identifier.Designation.Text








LodgementReceiptType Lodgement.Receipt.Identifier Lodgement.Receipt.IdentifierType Lodgement.Receipt.Datetime Lodgement.Receipt.DatetimeType SoftwareInformationType OrganisationNameDetails.OrganisationalName.Text

OrganisationNameDetails.OrganisationalName.TextType

SoftwareInformation.ProductName.Text SoftwareInformation.ProductName.TextType

SoftwareInformation.ProductVersion.Text SoftwareInformation.ProductVersion.TextType

BusinessDocumentsType BusinessDocument BusinessDocumentType IF BusinessDocuments

<> NULL AND BusinessDocument = NULL RETURN VALIDATION MESSAGE ENDIF


BusinessDocument BusinessDocumentType If Count(BusinessDocument) <> Count(BusinessDocumentInstance) RETURN VALIDATION MESSAGE ENDIF


BusinessDocumentType BusinessDocument.Sequence.Number BusinessDocument.Sequence.Num

berType IF BusinessDocument <> NULL AND ThisField = NULL RETURN VALIDATION MESSAGE ENDIF






BusinessDocument.Sequence.Number BusinessDocument.Sequence.NumberType

BusinessDocument.Sequence.Number must be minimum inclusive with a value of 1


BusinessDocument.Creation.Datetime BusinessDocument.Creation.DatetimeType

IF BusinessDocument <> NULL AND ThisField = NULL RETURN VALIDATION MESSAGE ENDIF


BusinessDocument.ValidationUniformResourceIdentifier.Text

BusinessDocument.ValidationUniformResourceIdentifier.TextType

IF BusinessDocument <> NULL AND ThisField = NULL RETURN VALIDATION MESSAGE ENDIF



BusinessDocument.ValidationUniformResourceIdentifier.TextType

Must be the same as the Schema Ref element in the XBRL payload for the corresponding BusinessDocumentInstance (Absolute Reference)


BusinessDocument.BusinessGeneratedIdentifier.Text

BusinessDocument.BusinessGeneratedIdentifier.TextType

BusinessDocument.GovernmentGeneratedIdentifier.Text

BusinessDocument.GovernmentGeneratedIdentifier.TextType

Attachments AttachmentsType IF Attachments <> NULL RETURN VALIDATION MESSAGE ENDIF


AttachmentsType Attachment AttachmentType AttachmentType





Message.Attachment.Sequence.Number Message.Attachment.Sequence.NumberType

Message.Attachment.FileName.Text Message.Attachment.FileName.TextType

Message.Attachment.Description.Text Message.Attachment.Description.TextType

MessageEventType Message.Event.MaximumSeverity.Code Message.Event.Item.Severity.Code

Type

MessageEventItems MessageEventItemsType MessageEventItemsType MessageEventItem MessageEventItemType MessageEventItemType Message.Event.Item.Error.Code Message.Event.Item.Error.CodeTyp

e

Message.Event.Item.Severity.Code Message.Event.Item.Severity.CodeType

Message.Event.Item.Short.Description MessageEventItemShortDescriptionType

Message.Event.Item.Detailed.Description MessageEventItemDetailedDescriptionType

Parameters MessageEventItemParametersType Locations MessageEventItemLocationsType StandardBusinessDocumentBodyType BusinessDocumentInstances BusinessDocumentInstancesType IF ParentField <> NULL

AND BusinessDocumentInstances = NULL RETURN VALIDATION MESSAGE ENDIF


AttachmentInstances AttachmentInstancesType IF AttachmentInstances <> NULL RETURN VALIDATION MESSAGE ENDIF






BusinessDocumentInstancesType BusinessDocumentInstance BusinessDocumentInstanceType IF

BusinessDocumentInstances <> NULL AND BusinessDocumentInstance = NULL RETURN VALIDATION MESSAGE ENDIF


BusinessDocumentInstanceType BusinessDocument.Sequence.Number BusinessDocument.Sequence.Num

berType IF BusinessDocumentInstance <> NULL AND BusinessDocument.Sequence.Number = NULL RETURN VALIDATION MESSAGE ENDIF


BusinessDocument.Instance.Text BusinessDocument.Instance.TextType

IF BusinessDocumentInstance <> NULL AND BusinessDocument.Instance.Text = NULL RETURN VALIDATION MESSAGE ENDIF




APPENDIX E – SBDH RESPONSE ELEMENTS Mandatory Transaction Target Field Type Schema

Occurs Local Service

Value

StandardBusinessDocumentMessage

StandardBusinessDocumentHeader StandardBusinessDocumentHeaderType 1-1 M M StandardBusinessDocumentBody StandardBusinessDocumentBodyType 0-1 O O StandardBusinessDocumentHeaderType

Message.Type.Text xs:string 1-1 M M Value shall be set to "twc.calculate.01.01.response"

MessageTimeStamps MessageTimestampsType 1-1 O M

Sender PartyType - Sender 0-1 O M

Receiver PartyType - Receiver 0-1 O

LodgementReceipt LodgementReceiptType 0-1 O O

SoftwareInformation SoftwareInformationType 0-1 O

BusinessDocuments BusinessDocumentsType 0-1 M O

MessageEvent MessageEventType 0-1 M M

MessageTimestampsType

MessageTimestamp MessageTimestampType 1-N O M One or more Timestamps for Response (Inserted on response)

MessageTimestampType

Message.Timestamp.Generation.Datetime xs:dateTime 1-1 O M Set value to Current timestamp

Message.Timestamp.GenerationSource.Code xs:string 1-1 O M Value must be: 'GovernmentAgency'

PartyType - Sender

IdentificationDetails.Identifier.Designation.Text xs:string 1-1 O M Value shall be 'ato.gov.au'

IdentificationDetails Identifier Name.Text xs:string 1-1 O M Value shall be 'AgencyInternetDomainName'

PartyType - Receiver

IdentificationDetails.Identifier.Designation.Text xs:string 1-1 IdentificationDetails Identifier Name.Text xs:string 1-1




Value

LodgementReceiptType

Lodgement.Receipt.Identifier xs:string 0-1 O O

Lodgement.Receipt.Datetime xs:dateTime 1-1 O M

SoftwareInformationType

OrganisationNameDetails.OrganisationalName.Text xs:string 1-1 Not Required for Response

SoftwareInformation.ProductName.Text xs:string 1-1 Not Required for Response

SoftwareInformation.ProductVersion.Text xs:string 1-1 Not Required for Response

BusinessDocumentsType

BusinessDocument BusinessDocumentType 1-N M M One business document for a response

BusinessDocumentType

BusinessDocument.Sequence.Number xs:integer 1-1 M M Value shall be 1

BusinessDocument.Creation.Datetime xs:dateTime 1-1 M M Set value to Current timestamp


xs:string 1-1 M M Set to URI of business document

BusinessDocument.BusinessGeneratedIdentifier.Text xs:string 0-1 M M Set as per Request:BusinessDocument.BusinessGeneratedIdentifier.Text field

BusinessDocument.GovernmentGeneratedIdentifier.Text xs:string 0-1 O O

Attachments AttachmentsType 0-1 Out of Scope

AttachmentsType

Attachment AttachmentType 1-1 Out of Scope

AttachmentType


Message.Attachment.FileName.Text xs:string 0-1 Out of Scope

Message.Attachment.Description.Text xs:string 0-1 Out of Scope

MessageEventType

Message.Event.MaximumSeverity.Code xs:string 1-1 SWS to calculate maximum severity code by going through the SeverityCodes in




Value

MessageEventItems

MessageEventItems MessageEventItemsType 1-1

MessageEventItemsType

MessageEventItem MessageEventItemType 1-N Set via validation rules and also as per service AP360 (where additional errors are returned)

MessageEventItemType

Message.Event.Item.Error.Code xs:string 1-1

Message.Event.Item.Severity.Code xs:string 1-1 Must be one of: Error, Warning, Information

ShortDescriptions MessageEventItemShortDescriptionsType 0-1

DetailedDescriptions MessageEventItemDetailedDescriptionsType 0-1

Parameters MessageEventItemParametersType 0-1

Locations MessageEventItemLocationsType 0-1

MessageEventItemShortDescriptionsType

Message.Event.Item.Short.Description xs:anyType 0-N

MessageEventItemDetailedDescriptionsType

Message.Event.Item.Detailed.Description xs:anyType 0-N

MessageEventItemParametersType

Message.Event.Item.Parameter xs:string 1-N

MessageEventItemLocationsType

Location MessageEventItemLocationType 1-N

MessageEventItemLocationType

BusinessDocument.Sequence.Number

xs:integer 1-1 Set to 1 where no relevant business document is identified

Message.Event.Item.Location.Path.Text xs:string 0-1

StandardBusinessDocumentBodyType

BusinessDocumentInstances BusinessDocumentInstancesType 1-1 M M AttachmentInstances AttachmentInstancesType 0-1 Out of Scope

BusinessDocumentInstancesType

BusinessDocumentInstance BusinessDocumentInstanceType 1-N M M




Value

BusinessDocumentInstanceType

BusinessDocument.Sequence.Number xs:integer 1-1 M M Value shall be 1

BusinessDocument.Instance.Text xs:string 1-1 M M TWC Response


AttachmentInstance AttachmentInstanceType 1-N Out of Scope



Message.Attachment.Instance.BinaryObject xmime:base64Binary 1-1 Out of Scope

Message.Attachment.Instance.BinaryObject.contentType xs:string (Attribute) 1-1 Out of Scope