QuickSuper. Client Fund Upload File Specification.

Transcription

1 QuickSuper Client Fund Upload File Specification

2 Document History Date Description 24 May 2015 Initial version. Page 2

3 Table of Contents 1 Introduction Client Fund Upload File Format File Format Additional Notes Field Population Summary Client Fund Upload Receipt File Client Fund Receipt Detail Error Codes Example Receipt Files Page 3

4 1 Introduction QuickSuper allows client funds to be registered in the following ways: Individually, using the QuickSuper screens. In bulk, using the Client Fund Upload File This document describes the format of the Client Fund Upload File. It explains how new client funds can be added in bulk and also how the existing client funds can be updated. Authorised users in your company can upload client funds files via the QuickSuper web interface. QuickSuper will then generate a receipt file in response indicating the results of the file processed. 2 Client Fund Upload File Format The Client Fund Upload File has a CSV (comma separated values) format. This format allows the file to be viewed and edited in Microsoft Excel or similar products. A sample file of the existing funds can be downloaded by selecting Upload Funds in the menu and clicking the Export button. 2.1 File Format The file structure is as follows: Record File Header Description One record at the start of the file. It contains the file headings. This record must be followed immediately by a Client Fund Detail record. Client Fund Detail A record to represent a single client fund. There may be many such records per file. The following table describes the fields. All fields are to be separated by a comma (,) value. Double quotes may be used around the fields. For example, either of the following would work in the header record: Action, Fund ID, etc. Action, Fund ID, etc. If the field values themselves contain commas, double quotes must be used. The first row of your file must contain the values in the Column Heading column below. Note: the single quotes should be excluded when you populate the file. Your client fund data should start on the second row of the file and continue for as many rows as you require. Page 4

5 Col. Column Heading Value and Format Notes A Action Mandatory. ADD or UPDATE B Fund ID Mandatory. C Fund Name Conditional. Any other value will cause the file to be rejected. The only allowed characters within the ID are alphanumeric i.e. A to Z (upper case) and 0 to 9. Hyphens, underscores, lower case letters, spaces and other characters are not allowed within the ID. Max length = 11 (excluding QuickSuper Client ID) SuperStream Standards require that this field is limited to specific characters. See Organisation Name Accepted Characters section below. Max length = 60 D Status Mandatory. Active or Inactive E Redirect To Conditional. F ABN Conditional. Any other value will cause the record to be rejected. Fund ID of target master fund (i.e. USI) that you wish to redirect to. 11 digits, no spaces. ADD can be used to: - Add a new SMSF - Add a new Redirection UPDATE can be used to: - Update an existing client fund, including marking a client fund as inactive. The Fund ID may be a value of your choosing that you will then use in a contribution file. When adding an SMSF you can provide the ABN or another identifier from your payroll system as the Fund ID. The value you include in this file may be with or without your QuickSuper Client ID at the start. If you do not include your QuickSuper Client ID, this will be automatically prepended by QuickSuper when the file is uploaded. Name of the fund. This field is mandatory is most cases but is ignored when marking a fund as inactive. If you provide a character that is not allowed, the record will be rejected. Indicates whether the fund is active or not. When updating a fund as inactive, all fields except Action, Fund ID and Status are ignored. This is mandatory when adding or updating redirections. It must be blank when maintaining SMSFs and is ignored when updating a fund as inactive. This is mandatory when adding or updating SMSFs. It is ignored when maintaining redirections or Refer to the ABN section below for more details on this field. Page 5

6 Col. Column Heading Value and Format Notes G BSB Conditional. H Account Number Conditional. 6 digits, no spaces or hyphens e.g Consecutive digits (i.e. no spaces or other characters in between). Max length = 9 I Account Name Conditional. The Australian Banking system requires that this field is limited to specific characters. See Account Name Accepted Characters section below. Max length = 32 J ESA Alias Optional. Alphanumeric value. Max length = 16 K Conditional. If supplied, the value must be in a valid address format (e.g. abc@xyz.com.au ). Note: we cannot check if it is a valid address. Max length = 60 L Address Line 1 Optional (see notes). Free text value. Max length = 35 This is mandatory when adding or updating SMSFs. It is ignored when maintaining redirections or If you provide a numeric value shorter than 6 digits we will prepend zeroes to the front of the value until it is 6 digits. This is mandatory when adding or updating SMSFs. It is ignored when maintaining redirections or This is mandatory when adding or updating SMSFs. It is ignored when maintaining redirections or This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or Refer to the ESA Alias section below for more details on this field. This is mandatory when adding or updating SMSFs. It is ignored when maintaining redirections or This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. Please refer to the below section on Postal Address Validation for more details on this column. Page 6

7 Col. Column Heading Value and Format Notes M Address Line 2 Optional (see notes). Free text value. Max length = 35 This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. Please refer to the below section on Postal Address Validation for more details on this column. N Suburb Optional (see notes). Free text value. Max length = 35 This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. Please refer to the below section on Postal Address Validation for more details on this column. O State Optional (see notes). NSW, VIC, QLD, TAS, SA, WA, ACT or NT This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. Please refer to the below section on Postal Address Validation for more details on this column. P Postcode Optional (see notes). Numeric value. Length = 4 This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. Please refer to the below section on Postal Address Validation for more details on this column. Q Contact Name Optional. Free text value. Max length = 25 R Phone Optional. Well-formed phone number. Max length = 15 This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. Please refer to the below section on Phone Number Validation for more details on this column. Page 7

8 Col. Column Heading Value and Format Notes S Fax Optional. Well-formed phone number. Max length = 15 This is optional when adding or updating SMSFs. It is ignored when maintaining redirections or It is not required for use by QuickSuper. You may populate this if you wish for your own future reference. Please refer to the below section on Phone Number Validation for more details on this column. Page 8

9 2.2 Additional Notes Organisation Name Accepted Characters The SuperStream legislated message implementation guides include the restriction of characters that can be included in an Organisation Name. This restriction is applied to the Fund Name field. A list of all characters that can be accepted for organisation names is included below. Character Description Character Description A to Z and a to z Alphabetic characters (upper and lower case) Pipe 0 to 9 Numeric characters - Hyphen or dash Space _ Underscore. Period or decimal point = Equals sign, Comma \ Back slash? Question mark / Forward slash! Exclamation At sign ( Left Parenthesis # Hash or pound ) Right Parenthesis $ Dollar sign { Left brace % Percent sign } Right brace * Asterisk : Colon & Ampersand ; Semicolon " Double quote ' Apostrophe ABN An Australian Business Number (ABN) is required for all SMSFs that a QuickSuper client wishes to make contributions to via QuickSuper. The supplied value is validated to ensure it is in the correct format (i.e. 11 digit number and meets check digit algorithm). The value is then checked against the ABN Lookup service ( to ensure that the ABN is registered, active and a complying SMSF. QuickSuper will reject any request with an invalid or inactive ABN or where the ABN is not for a complying SMSF. When adding or updating a redirection, this field is ignored as the ABN of the target fund is used. Page 9

10 2.2.3 Account Name Accepted Characters The Australian Banking system only allows specific characters to be included in an account name. A list of all characters that can be accepted for account names is included below. Character Description Character Description A to Z and a to z Alphabetic characters (upper and lower case) ^ Circumflex 0 to 9 Numeric characters - Hyphen or dash Space _ Underscore. Period or decimal point = Equals sign, Comma ' Apostrophe? Question mark / Forward slash! Exclamation At sign ( Left parenthesis # Hash or pound ) Right parenthesis $ Dollar sign [ Left square bracket % Percent sign ] Right square bracket * Asterisk : Colon & Ampersand ; Semicolon + Plus sign ESA Alias To be able to receive SuperStream compliant contribution messages, every SMSF needs to subscribe to a service provider who is able to receive messages on their behalf. The service provider will provide the SMSF with an electronic service address (ESA). This will be in the form of a simple alias that refers to the service provider or their product name. Your employee should be able to provide you with the details of their selected ESA. The field is currently optional in the file specification to allow SMSFs and employer to transition to the SuperStream standards. However, this field is expected to become mandatory in the future when adding or updating SMSFs (note: no specific timing has been scheduled for this as yet). In the interim, if you do not provide an ESA then QuickSuper will continue to send remittance details via . If the delivery to the ESA is not successful (e.g. the SMSF is not registered with the specified ESA), QuickSuper will deliver an alternative remittance to the address registered for the client fund. Page 10

11 2.2.5 Redirections Under the SuperStream standards, public or corporate super funds are identified using their Unique Superannuation Identifier (USI). In QuickSuper, the Fund ID for these funds is the USI. If your payroll system cannot provide the required USI in a contribution file then you will need to use redirections as a workaround. Redirections allow your payroll system to provide an alternative identifier and QuickSuper will then redirect contributions to the appropriate master fund Postal Address Validation The postal address columns are optional as they are not used in processing. You may populate if you wish for your own future reference. Given that the columns are optional, they may be left blank. However, if any of the postal address columns are populated then the following minimum columns must be provided: Address Line 1 Suburb State Postcode That is, it is not valid to include Address Line 1 without at least populating the other required columns to form a valid address. Address Line 2 is always optional Phone Number Validation The Phone and Fax columns are optional as they are not used in processing. You may populate if you wish for your own future reference. Given that the columns are optional, they may be left blank. However, if populated then the value must be a well-formed phone number. The validation will allow the number to commence with a plus (to include the international prefix) and may include hyphen, parentheses and space characters as allowed characters. Landline numbers must include the area code to pass validation e.g would be accepted (02) , and other similar combinations would be accepted would be rejected as it does not include the area code. Page 11

12 2.3 Field Population Summary The following summarises the main scenarios and the field combinations that are appropriate to each scenario. Col. Column Heading Add/update SMSF Add/update Redirection Mark as inactive A Action ADD / UPDATE ADD / UPDATE UPDATE B Fund ID Mandatory Mandatory Mandatory C Fund Name Mandatory Mandatory Ignore D Status Active Active Inactive E Redirect To Blank Mandatory Ignore F ABN Mandatory Ignore Ignore G BSB Mandatory Ignore Ignore H Account Number Mandatory Ignore Ignore I Account Name Mandatory Ignore Ignore J ESA Alias Optional (note: this is expected to become mandatory in the future). Ignore Ignore K Mandatory Ignore Ignore L Address Line 1 Optional Ignore Ignore M Address Line 2 Optional Ignore Ignore N Suburb Optional Ignore Ignore O State Optional Ignore Ignore P Postcode Optional Ignore Ignore Q Contact Name Optional Ignore Ignore R Phone Optional Ignore Ignore S Fax Optional Ignore Ignore Page 12

13 3 Client Fund Upload Receipt File After processing an upload file, QuickSuper will generate a receipt file in CSV format indicating the processing status of each line in the original file. The file can be downloaded from the QuickSuper web interface. The line number and any errors found on that line will be included in the file. Errors may be determined at: File Level, where the whole file is rejected. An example of this might be if the file has incorrect header line. Line Level, where a single line is rejected independent of the processing of other lines. An example of this might be if a line is missing a mandatory parameter. This line would be rejected but other lines in the file may be accepted. Any lines without errors will be processed but lines containing errors will not be processed further by QuickSuper. You must correct the errors and upload a corrected file for the rejected lines for processing to continue. You should ensure that the receipt file is checked for errors each time and respond accordingly. The receipt file structure is as follows: Record File Header Description One record at the start of the file. It contains the file headings. This record must be followed immediately by a Client Fund Receipt Detail record. Client Fund Receipt Detail A record to represent a receipt for a line in the original client fund upload file. There may be multiple records for a given line if there are multiple errors on that line. Page 13

14 3.1 Client Fund Receipt Detail Col. Column Heading Value and Format Notes A Line Number Numeric Indicates the line on which the error has been determined. B Fund ID Alphanumeric Includes the Fund ID that was included in the original file for your reference. C Status Alphanumeric Processing status of the line. This will be one of the following: Added if the original line has been successfully added. Updated if the original line has been successfully updated. No action if an update was requested but the details were not changed. Error if there is an error with the line, further details are included in the following columns. D Error Code Numeric Error code if the line has an Error status. See list of codes in the following section. E Error Description Alphanumeric Error description if the line has an Error status. Describes the error in more detail. 3.2 Error Codes The following describes the various error codes reported during the processing of the Client Funds upload file. The examples represent the text that may be included in the Error Description field. The errors are separated into: File Level Errors (codes from 1 to 10). These errors are reported against the first line to indicate why the entire file is being rejected. Line Level Errors (codes from 11 to 99). These are errors which are reported on the line on which the error occurred. A line level error will result in the current line being rejected from processing without affecting processing of the rest of the file. Error Code Description File Level Errors (1-10) 1 Invalid Header Record This error indicates that the first line of the file is not formatted correctly. The line must have all the file headings in the correct order. Example: File missing required header field Fund ID. Page 14

15 Error Code Description 2 Internal QuickSuper Error This indicates that the file could not be successfully processed for an unspecified reason. You will not receive this error in normal processing. If this error occurs, please contact QuickSuper Support and we will advise of the next action. Example: Internal QuickSuper error occurred. Please contact support Reserved for future use Line Level Errors (11-99) 11 Invalid Action This error indicates that the value specified in the Action field is not valid. The value must be ADD or UPDATE. Action is a mandatory field that you have not provided. Action XYZ is not one of the accepted values. 12 Invalid Fund ID This error indicates that the value specified in the Fund ID field is missing or is not valid (e.g. contains invalid characters). If the specified Action is ADD, the error could indicate: The Fund ID provided already exists as a client fund in QuickSuper If the specified Action is UPDATE, the error could indicate: The Fund ID provided does not exist in QuickSuper and could not be updated Fund ID is a mandatory field that you have not provided. Fund ID ABC%$@ has invalid characters. Fund ID ABCD has already been referred to in this file. Fund ID ABCD could not be added as it already exists. Fund ID ABCD could not be updated as it does not exist. 13 Invalid Fund Name This error indicates that the value specified in the Fund Name field is missing or not valid (e.g. contains invalid characters). Fund Name is mandatory when adding or updating an SMSF. Fund Name ABC[] has invalid characters. Page 15

16 Error Code Description 14 Invalid Status This error indicates that the value specified in the Status field is not valid. This field must be Active or Inactive when the specified Action is UPDATE. The field must always be Active when the specified action is ADD. Example: Status Yes not one of expected values. Status Inactive is not valid when the Action is ADD. 15 Invalid Redirect To This error indicates that the value you have provided in the Redirect To field is not that of a valid master fund. This could be the case where you are trying to add a new redirection or update an existing redirection. Redirect To is not a valid target to redirect contributions to. 16 Invalid ABN. This error indicates that the specified ABN is not in a correct format or is not that of an active complying super fund. This could also indicate the case where we expect that ABN to be that of an SMSF but it is not. ABN is mandatory when adding or updating an SMSF. ABN 1234ABCD has invalid characters. ABN is not an active, complying SMSF. 17 Invalid BSB This error indicates that the BSB is invalid. BSB is mandatory when adding or updating an SMSF. BSB exceeds 6 character limit. BSB AABBCC has invalid characters. 18 Invalid Account Number This error indicates that the account number provided is invalid. Account Number is mandatory when adding or updating an SMSF. Account Number ABCD has invalid characters. 19 Invalid Account Name This error indicates that the account name provided is invalid. Account Name is mandatory when adding or updating an SMSF. Account Name AAA AAA exceeds 32 character limit. Account Name ABCD{} has invalid characters. Page 16

17 Error Code Description 20 Invalid ESA Alias This error indicates that the ESA Alias is not valid. When this value is provided, we expect it to be one of the registered ESAs. In some cases, QuickSuper is able to verify that the ABN provided is registered with the provided ESA to receive messages. ESA Alias ABCD is not a valid electronic service address. ABN ' ' does not match an SMSF registered with the ESA you have selected. Please check that the ESA is correct and that your employee has registered with that service provider. 21 Invalid Address The address must not be longer than 60 characters. Additionally, the value must be in a valid address format. Address is mandatory when adding or updating an SMSF. Address AAA AAA exceeds 60 character limit. Address XYZ is not a valid address. 22 Invalid Address Line 1 The address line 1 must not be longer than 35 characters. Additionally, it must be provided if any other address columns are populated. Address Line 1 is required if any other address columns are populated. Address Line 1 AAA AAA exceeds 35 character limit. 23 Invalid Address Line 2 The address line 2 must not be longer than 35 characters. Address Line 2 AAA AAA exceeds 35 character limit. 24 Invalid Suburb The suburb must not be longer than 35 characters. Additionally, it must be provided if any other address columns are populated. Suburb is required if any other address columns are populated. Suburb AAA AAA exceeds 35 character limit. 25 Invalid State The state must be one of the expected values. Additionally, it must be provided if any other address columns are populated. State is required if any other address columns are populated. State XYZ is not one of the expected values. Page 17

18 Error Code Description 26 Invalid Postcode The postcode must be a 4 digit number. Additionally, it must be provided if any other address columns are populated. Postcode is required if any other address columns are populated. Postcode XYZ is not a valid value. 27 Invalid Contact Name The contact name must not be longer than 25 characters. Contact Name AAA AAA exceeds 25 character limit. 28 Invalid Phone The phone must not be longer than 15 characters and must be a well-formed phone number. Phone exceeds 15 character limit. Phone XYZ is not a valid value. 29 Invalid Fax The fax must not be longer than 15 characters and must be a well-formed phone number. Fax exceeds 15 character limit. Fax XYZ is not a valid value Reserved for future use Page 18

19 3.3 Example Receipt Files Processed file The following receipt file indicates that some of the records have been processed as requested. However, line 5 contains two errors which are reported on subsequent lines. Line Number,Fund ID,Status,Error Code,Error Description 2, ,Added,, 3, ,Updated,, 4, ,No action,, 5, ,Error,16,ABN 1234ABCD has invalid characters. 5, ,Error,18,Account Number ABCD has invalid characters Rejected file The following receipt file indicates that the entire file has been rejected by reporting an error against the first line in the file. Line Number,Fund ID,Status,Error Code,Error Description 1,,Error,1,File missing required header field Fund ID. Page 19