south african revenue service · 3. data type: specifies the type for example, numeric or alpha...

SARS_IT3 Extract 2003 Specification Supplementary Document v2 0 0 19/01/2012 of 23

PUBLIC RELEA S E

Document Classification:

Official Publication

© South African Revenue Service 2012

Archive

d


Revision History Date Version Description Author/s 19/01/201 1.0.0 New document SARS 05/04/2012 2.0.0 Changes highlighted in green SARS

Archive

d


Table of Contents

1. DEFINITIONS AND ACRONYMS ................................................................................................................4

2. INTRODUCTION ..........................................................................................................................................5

3. GENERAL RULES FOR IMPORT FILE STRUCTURES .............................................................................6

4. FILE LAYOUT ..............................................................................................................................................7

4.1 IT3 EXTRACT DETAILS HEADER RECORD .................................................................................................7 4.2 IT3 EXTRACT PERSONAL/REGISTERED DETAILS DATA RECORD ................................................................8 4.3 IT3(B) EXTRACT INCOME DETAILS DATA RECORD .................................................................................. 13 4.4 IT3(C) FINANCIAL INSTRUMENTS/UNITS SOLD DATA RECORD ................................................................. 16 4.5 IT3(E) EXTRACT INCOME DETAILS DATA RECORD .................................................................................. 18 4.6 IT3 EXTRACT PARTNER DETAILS DATA RECORD ................................................................................... 20 4.7 IT3 EXTRACT DETAILS TRAILER RECORD .............................................................................................. 23

Archive

d


1. DEFINITIONS AND ACRONYMS

The following definitions and acronyms have been defined to provide assistance in identifying the meaning of SARS’s terminology. Term Description Alpha (A) Alphabet A until Z

Upper Case and Lower Case Dash (-) Space ( ) Comma (,) Apostrophe (‘) Characters such as ê, ë.

Alphanumeric (AN)

Alphabet A until Z Upper Case and Lower Case Characters Dash (-) Space ( ) Comma (,) Apostrophe (‘) Characters such as ê, ë. Numbers 0 to 9 Forward slash (/) Ampersand (&), Full Stop (.) Underscore (_) Brackets () Dash (-) All special characters allowed are as per the Unicode UTF-8 standard. The definition of this standard can be found on: http://www.utf8-chartable.de

CCYYMM Century-Year-Month CCYYMMDD Century-Year-Month-Day Conditional Fields Fields that must be completed subject to defined conditions, e.g. mandatory if related

fields have been completed EXTRS Extracts IT Income Tax Mandatory Fields Fields that must be completed as a rule as opposed to being optional Numeric (N) Numbers from 0 to 9 No Number Occurrence Indicates the number of occurences of a field that must appear in the record Optional Fields Fields that can be completed based on applicability and availability. These fields are not

mandatory. Spec Specification Arch

ived

http://www.utf8-chartable.de/�


2. INTRODUCTION

In order to assist taxpayers in complying with the submission of IT3 data, this document provides supplementary information to be used in conjunction with the current specification called IT3 EXTRACTS– INTERFACE REQUIREMENTS SPECIFICATION, Document Number: IBIR-033 Document Revision Number: 1.200, dated 2003-05-22.

Archive

d


3. GENERAL RULES FOR IMPORT FILE STRUCTURES

a. Fields are indicated as mandatory, optional or conditional as specified in this document.

b. Data fields must not start with a space.

c. SARS will reject an entire file if any field in the header record (“H” type record) fails any validation or if any section identifier field fails any validation.

d. The first 8 characters of the file name must be “IT3EXTRS”.

e. Monetary fields must not contain a decimal point or comma.

f. The fields in the file body are each subjected to the following types of validations: 1. Length: the required length of the field; 2. Occurrence: the number of times that a field must occur; 3. Data type: specifies the type for example, numeric or alpha numeric; 4. Required: validates whether the field is required to be completed. Can be mandatory,

conditional or optional. If the field is conditional, a condition rule is supplied; 5. Padding: if the field content does not occupy the maximum allowed field length, the

field must be padded as specified per field; 6. Alignment: if the field content does not occupy the maximum allowed field length, the

field must be right or left aligned as specified per field; 7. Clarifying business rules: applies a logic validation on the value of the field.

Archive

d


4. FILE LAYOUT

The tables below lists all the validations as specified in the IT3 Extracts – Interface Requirement Specificationper section and provides clarifying rules and comments.

4.1 IT 3 E xtrac t Details Header R ec ord

Field No

IT3 Extracts – Interface Requirements Specification Breakdown of Rules in Specification

Clarifying Business Rules Comments Name Description Length Occurrence

Additional validation

Spec Remarks

Data Type Required Padding Alignment

1 SEC-ID File section identifier

1 1 “H“ A M None None 1. Type "H" records must be followed by type "P" records

2 INFO-TYPE Information type

8 1 “IT3EXTRS” 1,2 A M None None 1. Must = "IT3EXTRS"

3 INFO-SUBTYPE

Information subtype

8 1 Blanks 1,2,9 A O Blank Left 1. Must be 8 blank characters

4 TEST-DATA Test data indicator

1 1 “Y” or “N” 7 A M None None 1. Must = "Y", if the file is sent to the test environment 2. Must = "N", if the file is sent to the production environment

1. Field must contain either a "Y" or an "N". If the field contains any other value the field will be rejected.

5 FILE-SERIESCTL

File series control field

1 1 “S” A M None None

6 EXT-SYS External system identification

8 1 ISP0901 1,2,6 AN M Blank Left 1. UPPER(EXT-SYS) must = UPPER(folder name)

1. Folder name is also referred to as directory name

7 VER-NO Interface version number

8 1 “1” 1,3,4 N M Blank Right

8 OWN-FILE-ID

Unique file identifier

14 1 Alpha-numeric

1,3,8 AN M Blank Right 1. Must be at least a length of one character

9 GEN-TIME Date and time of file creation

14 1 CCYYMM DDhhmmss

5 D M None None 1. Valid if before today (current date and time)

Archive

d


4.2 IT 3 E xtrac t P ers onal/R egis tered Details Data R ec ord

Field No




Spec Remarks



1 1 “P“ A M None None 1. Type "P" records must only be followed by type "E", "I", "N" or "U" records

2 IT3-PERS-ID IT3 unique client number

25 1 Unique (1), (2), (3)

AN M Blank Left 1. This number must be unique within the file

3 IT-REF-NO Income tax reference number

10 1 Numeric (4) N C None None 1. If TP-CATEGORY = "01" either IT-REF-NO, TP-ID, TP-OTHER-ID or TP-DOB must be completed 2. If TP-CATEGORY = "02" either IT-REF-NO or CO-REG-NO must be completed 3. If TP-CATEGORY = "03" either the IT-REF-NO or TRUST-DEED-NO must be completed 4. Must start with "0", "1", "2", "3" or "9" 5. Must pass the IT Ref No modulus test

4 PERIOD-START

The date starting the period that is reported by this IT3 extract

8 1 CCYYMMDD (5), (6) D M None None 1. Must be smaller than today's date 2. Must be greater than 19010101 3. Must be smaller than PERIOD-END field 4. Must be greater than or equal to the first day and smaller than or equal to the last day of the current tax filing season year

Archive

d


Field No




Spec Remarks


5 PERIOD-END The date ending the period

8 1 CCYYMMDD (5), (7) D M None None 1. Must be smaller than today's date 2. Must be greater than 19010101 3. Must be greater than or equal to the first day and smaller than or equal to the last day of the current tax filing season year

6 TP-CATEGORY

Taxpayer category

2 1 Numeric (8) N M None None 1. Must contain one of the values in Table A4 in Appendix A, therefore must = "01", "02" or "03"

1. If the organisation is a Sports Club, Recreational Club, NPO or PBO use category "02"

7 TP-ID Taxpayer South African ID number

13 1 Numeric (1), (2), (9)

N C None None 1. If TP-CATEGORY = "01" either IT-REF-NO, TP-ID, TP-OTHER-ID or TP-DOB must be completed 2. Must not equal a company/CC registration number or trust deed number 3. Must pass SA ID No Modulus Test

1. Workaround: 1203310000087. Also to be used for estates, where attorney details are not available

8 TP-OTHER-ID Taxpayer other ID number

10 1 Alpha-numeric

(1), (2), (9)

AN C Blank Left 1. If TP-CATEGORY = "01" either IT-REF-NO, TP-ID, TP-OTHER-ID or TP-DOB must be completed 2. Must not equal a company/CC registration number or trust deed number 3. Must contain at least one character

1. Workaround: 1203310000. To be used as workaround for passport numbers as well.

Archive

d


Field No




Spec Remarks


9 CO-REG-NO Company/CC registration number

15 1 Alpha-numeric

(1), (2),(10)

AN C Blank Left 1. If TP-CATEGORY = "02" either IT-REF-NO or CO-REG-NO must be completed 2. Must not equal an SA ID No, other ID No or trust deed number 3. Must contain forward slashes 4. Must contain at least one character

1. Workaround: If foreign company, Sports Club or Recreational Club, Co Reg No to be supplied is 2012/000000/00

10 TRUST-DEED-NO

Trust deed number

10 1 Alpha-numeric

(1), (2), (11)

AN C Blank Left 1. If TP-CATEGORY = "03" either the IT-REF-NO or TRUST-DEED-NO must be completed 2. Must not equal an SA ID No, other ID No or company/CC registration number 3. Must be greater than or equal to 1

11 TP-NAME Taxpayer name

120 1 Alpha-numeric

(1), (2), (12)

AN M Blank Left 1. If TP-CATEGORY = "01", this field must contain the name and surname of the individual 2. If TP-CATEGORY = "2" or "3", this field must contain the registered name

12 TP-INITS Taxpayer initials

5 1 Alpha-numeric

(1), (2), (13)

AN C Blank Left 1. If TP-CATEGORY = "01", this field is mandatory

13 TP-FIRSTNAMES

Taxpayer first names

90 1 Alpha-numeric

(1), (2), (13)

AN C Blank Left 1. If TP-CATEGORY = "01", this field is mandatory

Archive

d


Field No




Spec Remarks


14 TP-DOB Taxpayer date of birth

8 1 CCYYMMDD (19), (5) N C None None 1. If TP-CATEGORY = "01" either IT-REF-NO, TP-ID, TP-OTHER-ID or TP-DOB must be completed 2. Must be smaller than or equal to today's date 3. Must be greater than 19010101 4. If TP-ID field contains a value, the value of this field must be equal to the first 6 digits of the value contained in the TP-ID field

1. Workaround: 20120331. Also to be used for estates, where attorney details are not available

15 TP-TRADENAME

Taxpayer trading name

120 1 Alpha-numeric

(1), (2), (16)

AN O Blank Left

16 TP-POSTADDR

Taxpayer postal address lines

35 4 Alpha-numeric

(1), (2), (15)

AN O Blank Left 1. Note that this field requires 4 occurences

17 TP-POSTCODE

Taxpayer postal code

10 1 Alpha-numeric

(1), (2),(15)

AN O Blank Left

18 TP-PHY-ADDR Taxpayer physical address lines

35 4 Alpha-numeric

(1), (2),(15)


19 TP-PHY-CODE Taxpayer physical postal code

10 1 Alphanumeric (1), (2),(15)

AN O Blank Left Archive

d


Field No




Spec Remarks


20 TP-SA-RES Taxpayer South African residence indicator

1 1 “Y”, “N” (17) A M None None

21 PARTNERSHIP Partnership indicator

1 1 “Y”, “N” (18) A O None None 1. "Y" is a valid value if the record set includes at least 2 "N" records

Archive

d


4.3 IT 3(b) E xtrac t Inc ome Details Data R ec ord

Field No




Spec Remarks



1 1 “I“ A M None None 1. Type "I" records must only be followed by type "E", "I", "N", "P", "T" or "U" records

2 IT3-PERS-ID

IT3 unique client Number

25 1 Unique (1), (2), (3)

AN M Blank Left 1. Must be equal to the IT3-PERS-ID value supplied in the preceeding "P" record.

3 INCOME-NATURE

The source code indicating the nature of income paid to taxpayer

4 1 Numeric (4), (5), (7)

N M None None 1. Must contain one of the values in Table A1 in Appendix A.

4 INCOME-PAID

Amount paid or accrued to taxpayer

15 1 Numeric (1), (5), (6), (7)

N M Blank Right 1. Must be greater than 0 and smaller than or equal to 999999999999999.

1. Field can only contain a positive amount 2. The two rightmost digits denote Cents. The rest denote the Rand amount.

5 ACCOUNT-NO

Investment account number (Investment income only)

20 1 Alpha-numeric

(1), (2), (8), (9)

AN C Blank Left 1. If INCOME-NATURE = "4201", then this field is mandatory 2. Must contain at least one character

1. Workaround: For Pension, Provident Funds and Investment Houses that uses code 4201, but do not have Account Numbers, use 99999999999999999999 as workaround

6 BRANCH-CODE

Branch code (Investment income only)

6 1 Numeric (17) N O Zero Right 1. If INCOME-NATURE = "4201", then this field is mandatory

1. Workaround: For Pension, Provident Funds and Investment Houses that uses code 4201, but do not have Account Numbers, use 666666 as workaround Arch

ived


Field No




Spec Remarks


7 ACCOUNT-TYPE

Investment account type (Investment income only)

2 1 Numeric (1), (5), (8), (10)

N C Blank Right 1. If INCOME-NATURE = "4201", then this field is mandatory 1. Must contain one of the values in Table A3 in Appendix A.

8 START-DATE

Account opening date or start of the IT3(b) reporting period (Investment income only)

8 1 CCYYMMDD (8), (11), (12)

N C None None 1. If INCOME-NATURE = "4201", then this field is mandatory 2. Must be smaller than or equal to last day of current tax filing season year 3. Must be smaller than END-DATE

9 START-BAL

Opening balance on the START-DATE (Investment income only)

15 1 Numeric (1), (5), (6),

(8), (14)

N C Blank Right 1. If INCOME-NATURE = "4201", then this field is mandatory 2. Must be greater than or equal to 0 and smaller than or equal to 999999999999999

1. Field can only contain a positive amount 2. The two rightmost digits denote Cents. The rest denote the Rand amount. If the value does not have cents the 2 most right values must be 00

10 START-BALSIGN

The sign of the STARTBAL field (Investment income only)

1 1 “C”, “D” (8), (16) A C None None 1. If INCOME-NATURE = "4201", then this field is mandatory 2. Must = "C" or "D", where "C" indicates a positive amount and "D" indicates a negative amount

1. This field indicates whether the START-BAL is a positive or negative value.

11 END-DATE Account closing date or end of the IT3(b) reporting period (Investment income only)

8 1 CCYYMMDD (8), (11), (13)

N C None None 1. If INCOME-NATURE = "4201", then this field is mandatory 2. Must be greater than or equal to the first day and smaller than or equal to the last day of the current tax filing season year

Archive

d


Field No




Spec Remarks


12 END-BAL Investment balance on the END-DATE (Investment income only)

15 1 Numeric (1), (5), (6),

(8), (15)

N C Blank Right 1. If INCOME-NATURE = "4201", then this field is mandatory 2. Must be greater than or equal to 0 and smaller than or equal to 999999999999999

1. Field can only contain a positive amount 2. The two rightmost digits denote Cents. The rest denote the Rand amount. If the value does not have cents the 2 most right values must be 00 3. Balance before closing of accounts for reconciling purposes must be provided

13 END-BAL-SIGN

The sign of the END-BAL field (Investment income only)

1 1 “C”, “D” (8), (16) A C None None 1. If INCOME-NATURE = "4201", then this field is mandatory 2. Must = "C" or "D", where "C" indicates a positive amount and "D" indicates a negative amount

1. This field indicates whether the END-BAL is a positive or negative value.

14 FOREIGN-TAXPAID

Tax paid on the foreign dividends or interest

15 1 Numeric (1), (5), (6), (18)

N C Blank Right 1. If INCOME-NATURE = "4216" or "4218", then this field is mandatory 2. Must be greater than or equal to 0 and smaller than or equal to 999999999999999

1. The two rightmost digits denote Cents. The rest denote the Rand amount. If the value does not have cents the 2 most right values must be 00

Arch

ived


4.4 IT 3(c ) F inanc ial Ins truments /Units S old Data R ec ord

Field No




Spec Remarks



1 1 “U“ A M None None 1. Type "U" records must only be followed by type "E", "I", "N", "P", "T" or "U" records

2 IT3-PERS-ID

IT3 unique client Number

25 1 Unique (1), (2), (3)


3 INCOME-SOURCE-CODE

The source code indicating nature of the capital gain or loss

4 1 Numeric (4), (5), (8)


4 ASSET-DESC

Description of the financial instrument

30 1 Alphanumeric (1), (2) AN O Blank Left

5 UNITS Number of instruments/units sold

8 1 Numeric (1), (5), (7), (9)

N M Blank Right 1. Must be greater than 0 and smaller than or equal to 99999999 2. Must be rounded up to the next whole number, e.g. 100.25 will be rounded up to 101

6 COST Total value of units purchased based on weighted average

15 1 Numeric (1), (5), (6)

N M Blank Right 1. Must be greater than 0 and smaller than or equal to 999999999999999

1. The two rightmost digits denote Cents. The rest denote the Rand amount. The amounts must all be positive. If the value does not have cents the 2 most right values must be 00 Arch

ived


Field No




Spec Remarks


7 PROCEEDS The proceeds of the instruments/units sold

15 1 Numeric (1), (5), (6)


1. The two rightmost digits denote Cents. The rest denote the Rand amount. The amounts must all be positive. If the value does not have cents the 2 most right values must be 00

8 GAIN-LOSS The net gain or loss value of the units sold

15 1 Numeric (1), (5), (6)



9 BALANCE-OF-UNITS

The balance of the number of instruments/units as at the last day of February

8 1 Numeric (1), (5), (9)

N C Blank Right 1. If BALANCE-OF-UNITS-VALUE field contains a value, this field is mandatory 2. Must be greater than or equal to 0 and smaller than or equal to 9999999999 3. Must be rounded up to the next whole number, e.g. 100.25 will be rounded up to 101

10 BALANCE-OF-UNITS-VALUE

The weighted average value of the instruments/units as at the last day of February

15 1 Numeric (1), (5), (6)

N C Blank Right 1. If BALANCE-OF-UNITS field contains a value, this field is mandatory 2. Must be greater than or equal to 0 and smaller than or equal to 99999999999999999


Arch

ived


4.5 IT 3(e) E xtrac t Inc ome Details Data R ec ord

Field No




Spec Remarks



1 1 "E" A M None None 1. Type "U" records must only be followed by type "E", "I", "N", "P", "T" or "U" records

2 IT3-PERS-ID

IT3 unique client number related to the personal details record

25 1 Unique (1), (2), (3)


3 INCOME-NATURE

The source code indicating the nature of income paid to taxpayer

4 1 Numeric (4), (5), (7)


4 NET-PROCEEDS

Net proceeds paid to taxpayer

15 1 Numeric (1), (5), (6), (7),

(8)



5 GROSS-PROCEEDS

Gross proceeds paid to taxpayer

15 1 Numeric (1), (5), (6), (7)



6 ACCRUAL-DATE

Accrual/Payment date of proceeds to taxpayer

8 1 CCYYMMDD (11) N M None None 1. Must be greater than or equal to the first day and smaller than or equal to the last day of the current tax filing season year

Archive

d


Field No




Spec Remarks


7 UNITS Number of instruments/units sold

8 1 Numeric (1), (5), (10)

N M Blank Right 1. Must be greater than or equal to 0 and smaller than or equal to 99999999

1. If the value does not have cents the 2 most right values must be 00

8 SUB-PERIOD

The sub-period within the reporting period for which this income details record is valid

2 1 Numeric (1), (5), (9)

N M None None 1. Must = "01" or "02"

9 REF-NO Reference number applicable to this income

20 1 Alphanumeric (1), (2), (12)

AN O Blank Left

Archive

d


4.6 IT 3 E xtrac t P artner Details Data R ec ord

Field No




Spec Remarks



1 1 "N" A C None None 1. If PARTNERSHIP field in preceeding "P" record = "Y", this field is mandatory 2. Type "N" records must only be followed by type "E", "I", "N", "P", "T" or "U" records

2 IT3-PERS-ID IT3 unique client number related to the personal details record

25 1 Unique (1), (2), (3)


3 IT-REF-NO Partner Income Tax Reference Number

10 1 Numeric (4) N C None None 1. If PT-CATEGORY = "01" either IT-REF-NO, PT-ID or PT-OTHER-ID must be completed 2. If PT-CATEGORY = "02" either IT-REF-NO or PT-CO-REG-NO must be completed 3. If PT-CATEGORY = "03" either the IT-REF-NO or PT-TRUST-DEED-NO must be completed 4. Must start with "0", "1", "2", "3" or "9" 5. Must pass the IT Ref No modulus test

4 PT-CATEGORY

Partner category

2 1 Numeric (5) N M None None 1. Must contain one of the values in Table A4 in Appendix A, therefore must = "01", "02" or "03"

Archive

d


Field No




Spec Remarks


5 PT-ID Partner South African ID number

13 1 Numeric (1), (2), (6)

N C None None 1. If PT-CATEGORY = "01" either IT-REF-NO, PT-ID or PT-OTHER-ID must be completed 2. Must start with "0", "1", "2" or "3". 3. Must pass SA ID No Modulus Test 4. Must not equal a company/CC registration number or trust deed number

1. Workaround: 1203310000087, where ID Numbers of all partners are not available

6 PT-OTHER ID Partner other ID number

10 1 Alpha-numeric

(1), (2), (6)

AN C Blank Left 1. If PT-CATEGORY = "01" either IT-REF-NO, PT-ID or PT-OTHER-ID must be completed 2. Must not equal a company/CC registration number or trust deed number 3. Must contain at least one character

1. Workaround: 1203310000. To be used as workaround for passport numbers as well.

7 PT-CO-REG-NO

Company/CC registration number

15 1 Alpha-numeric

(1), (2), (7)

AN C Blank Left 1. If PT-CATEGORY = "02" either IT-REF-NO or PT-CO-REG-NO must be completed 2. Must not equal an SA ID No, other ID No or trust deed number 3. Must contain at least one character

8 PT-TRUST-DEED-NO

Trust deed number

10 1 Alpha-numeric

(1), (2), (8)

AN C Blank Left 1. If PT-CATEGORY = "03" either the IT-REF-NO or PT-TRUST-DEED-NO must be completed 2. Must not equal an SA ID No, other ID No or company/CC registration number 3. Must be greater than or equal to 1

Archive

d


Field No




Spec Remarks


9 PT-NAME Partner Name

120 1 Alpha-numeric

(1), (2), (9)

AN M Blank Left 1. If PT-CATEGORY = "01", this field must contain the name and surname of the individual 2. If PT-CATEGORY = "02" or "03", this field must contain the registered name

10 PT-INITS Partner initials

5 1 Alpha-numeric

(1), (2), (10)

AN C Blank Left 1. If PT-CATEGORY = "01", this field is mandatory

11 PT-FIRSTNAMES

Partner first names

90 1 Alpha-numeric

(1), (2), (10)

AN C Blank Left 1. If PT-CATEGORY = "01", this field is mandatory

12 PT-POST-ADDR

Partner postal address lines

35 4 Alpha-numeric

(1), (2), (11)


16 PT-POST-CODE

Partner postal code

10 1 Alpha-numeric

(1), (2), (11)

AN O Blank Left

17 PT-PHY-ADDR

Partner physical address

35 4 Alpha-numeric

(1), (2), (12)


18 PT-PHY-CODE

Partner physical postal code

10 1 Alpha-numeric

(1), (2), (11)

AN O Blank Left

19 PT-SA-RES Partner South African residence indicator

1 1 "Y", "N" (13) A M None None

Archive

d


4.7 IT 3 E xtrac t Details T railer R ec ord

Field No




Spec Remarks



1 1 "T" A M None None 1. Must be the last record in the file

2 REC-NO Number of data records in this file (excluding the header and trailer records)

8 1 Numeric (1), (2), (3)

N M Zero Right 1. Must equal the number of records in the file excluding "H" and "T" type records

Archive

d

south african revenue service · 3. data type: specifies the type for example, numeric or alpha...

Documents