Skip to main content

Flat-file payment upload file

The Flat-file payment upload file is sent to process a batch of payments. The system responds with a Flat-file payment response report.

File format

Fixed Width Card Payments Bank Account Payments Account Tokens Supported

The Flat-file format is a fixed-width text file. The file consists of five record types.

All files are plain text using UTF-8 character encoding. All records are separated by the CR LF end-of-line marker. Each record in the file is 250 characters long.

To upload a payment file in this format you must:

  • Send the parameter format with FLAT_FILE or FLAT_FILE_TOKENS.
  • Use only one supplier business code per batch header.
  • In the Account Number field, use only all card PANs or bank account numbers for FLAT_FILE or all account tokens for FLAT_FILE_TOKENS file.

The payment file has the following general structure:

Data types are listed as:

  • N - numeric 0-9 only.
  • A - letters from the English alphabet, including spaces.
  • AN - letters or numbers (alphanumeric), spaces, underscores _ and hyphens -.
  • S - spaces only

Unless otherwise noted, N numeric fields are right-justified and padded with leading zeros. A letters and AN alphanumeric fields are left-justified and padded with trailing spaces. Amounts are always expressed in cents, e.g. $125.94 is expressed as 0000012594 (assuming the field has a length of 10).

File control header

The file header must be the first record in the file.

No Field Name Position Length Data Type Description
1 Record Type 1 1 N 1 to indicate file control header.
2 Client Community Code 2 10 AN Your community code.
3 File Creation Date 12 8 N Date the file was created in YYYYMMDD format.
4 File Creation Time 20 4 N Time the file was created in HHMM
5 Client Name 24 30 AN Your community name.
6 Unique File Identifier 54 20 AN A unique identifier for the file. QuickStream will only process a file with a unique identifier once. This is returned in the payment file report. E.g. YYYYMMDD01 for the first file on a date.
7 Filler 74 177 S Spaces

Batch control header

This record is used to group together data for a particular supplier business.

No Field Name Position Length Data Type Description
1 Record Type 1 1 N 3 to indicate batch control header.
2 Client Company Name 2 30 AN Supplier business name.
3 Client Company Code 32 10 AN Supplier business code to process transactions in this batch.
4 Batch Type 42 2 A CC indicates only card payments are in this batch. DD indicates only bank account payments are in this batch.
5 Batch Description 44 18 S Not used - set to spaces.
6 Unique Batch Code 62 15 AN A unique identifier for this batch. QuickStream will process a batch with a unique batch code once. E.g. YYYYMMDD01_01 for the first batch in this file.
7 Refund Flag 77 1 A R indicates all transactions in this batch are refunds. A single space indicates all transactions in this batch are payments.
8 Currency 78 3 A AUD indicates the transactions in this batch are in Australian Dollars. NZD is also supported.
9 Filler 81 170 S Spaces

Transaction detail

Each batch contains one or more transactions. Transactions may be card or bank account, payments or refunds. Card and bank account transactions use the same record format, but the usage of the fields differ:

Card transaction detail
No Field Name Position Length Data Type Description
1 Record Type 1 1 N 5 to indicate a transaction.
2 Filler 2 2 S Spaces
3 Expiry Date 4 8 N The card expiry date in MMYY format.
4 Account Number 12 17 AN Card Number for FLAT_FILE format. Do not include dashes, underscores or spaces between card number digits. Account Token for FLAT_FILE_TOKENS format. Left justified with trailing spaces.
5 Amount 29 10 N The transaction amount in cents, right justified with zero padding. For example, $125.94 is expressed as 0000012594. For a refund, you can only refund an amount up to the value of the original transaction specified by Capture Transaction Number.
6 Customer Number 39 15 AN Your customer's number.
7 Account Name 54 22 AN The cardholder's name.
8 Transaction Number 76 15 AN A unique identifier for this transaction. This value cannot be the same as another transaction in this file or any previous file you have sent.
9 Capture Transaction Number 91 15 AN For a refund, use the receipt number of the transaction you wish to refund. For a payment, leave blank.
10 Authorisation Identifier 106 6 AN If capturing a previous pre-auth transaction, this is the 6 character authorisation code from that pre-auth transaction. Otherwise, leave blank.
11 Electronic Commerce Indicator 112 3 A CCT - Call centre transaction
REC - Recurring transaction
MTO - Mail or telephone order
IVR - Interactive Voice Recording telephone transaction.
12 Filler 115 136 S Spaces

Note:

  • The Electronic Commerce Indicator of REC for Recurring transaction (i.e. Mastercard or Visa Recurring) should be set if a transaction is a recurring transaction for which you hold an agreement with the cardholder. In addition, for Visa Recurring, the first transaction has to be authorised with a valid card expiry date. If the transaction is a one-off transaction, you must set the Sale Type to one of the other values (i.e. CCT, MTO or IVR). Under no circumstances may you flag a one-off transaction as Recurring.
  • Refunds are a potential avenue for fraud. Check your merchant agreement for information about performing refunds. You must provide the receipt number of the transaction you wish to refund in Capture Transaction Number.
Bank account transaction detail
No Field Name Position Length Data Type Description
1 Record Type 1 1 N 5 to indicate a transaction.
2 Filler 2 2 S Spaces
3 BSB 4 8 N BSB for FLAT_FILE format, right justified with zero padding. E.g. 032-002 is expressed as 00032002. Leave blank for FLAT_FILE_TOKENS format.
4 Account Number 12 17 AN Account Number for FLAT_FILE format. Account Token for FLAT_FILE_TOKENS format. Left justified with trailing spaces.
5 Amount 29 10 N The transaction amount in cents, right justified with zero padding. For example, $125.94 is expressed as 0000012594. For a refund, you can only refund an amount up to the value of the original transaction specified by Capture Transaction Number.
6 Customer Number 39 15 AN Your customer's number.
7 Account Name 54 22 AN The acount holder's name.
8 Transaction Number 76 15 AN A unique identifier for this transaction. This value cannot be the same as another transaction in this file or any previous file you have sent.
9 Capture Transaction Number 91 15 AN For a refund, use the receipt number of the transaction you wish to refund. For a payment, leave blank.
10 Authorisation Identifier 106 6 S Not used for bank account transactions - leave blank.
11 Electronic Commerce Indicator 112 3 S Not used for bank account transactions - leave blank.
12 Filler 115 136 S Spaces

Note:

  • Refunds are a potential avenue for fraud. Check your merchant agreement for information about performing refunds. You must provide the receipt number of the transaction you wish to refund in Capture Transaction Number.

Batch control trailer

Each batch must have a trailer record following the last transaction in the batch.

No Field Name Position Length Data Type Description
1 Record Type 1 1 N 7 to indicate batch control trailer.
2 Batch Transaction Count 2 6 N Number of transactions in the batch.
3 Batch Transaction Total Amount 8 10 N Sum of all transaction amounts in the batch.
4 Client Company Code 18 10 AN Must be the same as the Client Company Code in the batch control header.
5 Unique Batch Code 28 15 AN Must be the same as the Unique Batch Code in the batch control header.
6 Filler 43 208 S Spaces

File control trailer

The file trailer record must be the last record in the file.

No Field Name Position Length Data Type Description
1 Record Type 1 1 N 9 to indicate file control trailer.
2 File Batch Count 2 2 N The number of batches present in this file.
3 File Transaction Count 4 8 N Total number of transactions in the file.
4 File Transaction Amount 12 12 N Sum of all transaction amounts in the file.
5 Client Community Code 24 10 AN Must be the same as the Client Community Code in the file control header.
6 Client Name 34 30 AN Must be the same as the Client Name in the file control header.
7 Unique File Identifier 64 20 AN Must be the same as the Unique File Identifier in the file control header.
8 Filler 84 167 S Spaces

Sample file

The sample file below contains:

  • 2 batches, 1 for a card payment and 1 for a bank account payment.
  • 2 transactions. 1 transaction in each batch.
  • The community code is CLIENTCODE.
  • The supplier code is SUPPLRCODE.
1CLIENTCODE200911040800Client Name                   2009110401                                                                                                                                                                                           
3Customer Name                 SUPPLRCODECCCredit Card Batch 2009110401_01   AUD                                                                                                                                                                          
5  000011134111111111111111 0000002508CUST000001     John Citizen          127462329                                                                                                                                                                      
70000010000002508SUPPLRCODE2009110401_01                                                                                                                                                                                                                  
3Customer Name                 SUPPLRCODEDDDirect Debit Batch2009110401_02   AUD                                                                                                                                                                          
5  00032000000007           0000003712CUST000002     Jane Citizen          127462330                                                                                                                                                                      
70000010000003712SUPPLRCODE2009110401_02                                                                                                                                                                                                                  
90200000002000000006220CLIENTCODEClient Name                   2009110401                                                                                                                                                                                 

Soft descriptors for aggregators

To use these fields a merchant facility must be set up in Westpac systems to use soft-descriptors. Providing soft-descriptors for transactions to merchant facilities which are not set up to use them will have no effect.

Read more about Soft descriptors for Aggregators.

Use these fields in the Transaction Detail Record - Fields 12 to 18 this format.

Field Required Description
Merchant Name Required for Aggregator merchants only. Maximum 22 characters.
Must be in the format AggregatorName*SubMerchantName.
For example:
  • AggregatorName is Jane's Transactions, abbreviated to JAT.
  • SubMerchantName name is Jill's Bikes.
  • The value of this field may be JAT*JillsBikes.
AggregatorName can be either in full or abbreviated and must be 3 characters.
Westpac may suggest a three character aggregator name during your implementation.
Merchant Street Address Required for Aggregator merchants only. Maximum 48 characters.
The street address of the sub-merchant's trading address.
It is a scheme requirement to populate the street address as part of the payment. Westpac does not hold the street address information for sub-merchants and it will not appear on the cardholder's or merchant's statement.
Must contain the street address lines only:
  • Include the city or suburb in Merchant Location.
  • Include the state in Merchant State.
  • Include the country in Merchant Country.
  • Include the post code in Merchant Post Code.
Merchant Location Required for Aggregator merchants only. Maximum 13 characters.
The city or suburb of the sub-merchant's trading address.
Merchant State Required for Aggregator merchants only. Maximum 3 characters.
The state of the sub-merchant's trading address. One of:
  • NSW
  • ACT
  • VIC
  • QLD
  • NT
  • SA
  • WA
  • TAS
Merchant Country Required for Aggregator merchants only. Maximum 2 characters.
Must be set to AU.
The sub-merchant must be registered in Australia and have a presence and process payments within Australia.
Merchant Postcode Required for Aggregator merchants only. Maximum 4 characters.
The postal code of the sub-merchant's trading address.
Sub-merchant ID Required for Aggregator merchants only. Maximum 15 chracters.
A unique identifier for your sub-merchant. The aggregator allocates the sub-merchant identifier. Westpac does not allocate this value.

Do not include any further columns.

Disclaimer

The information contained in this publication is provided for learning purposes only and is subject to change. Revisions may be issued from time to time that encompass changes or additions to this module.

This is a guide only and it is not comprehensive. It does not impinge on or overrule any formal arrangement you may enter into with the Bank. The Bank and its officers shall not have any liability for any losses of any kind incurred in connection with any action, inaction or decision taken in reliance on the information herein or for any inaccuracies, errors or omissions. In this publication references to the "Bank" are to Westpac Banking Corporation ABN 33 007 457 141 and to any of its operating Divisions, including BankSA and St.George.