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.

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 Name/Identifier 2 30 AN For AU payments, this should be your supplier business name. For NZ payments, this is required to be your full account number including 3 digit suffix without spaces (NZ Format 2-4-7-3). For example 0312341234567001.
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.
PT indicates only PayTo transactions 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. Only required for FLAT_FILE format. Ignored for FLAT_FILE_TOKENS 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.
PayTo transaction detail
No Field Name Position Length Data Type Description
1 Record Type 1 1 N 5 to indicate a transaction.
2 Filler 2 10 S Spaces
3 Agreement Token 12 17 AN PayTo Agreement Token for FLAT_FILE_TOKENS. Left justified with trailing spaces.
4 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 the exact amount of the original transaction specified by the Capture Transaction Number.
5 Customer Number 35 15 AN Your customer's number.
6 Filler 54 22 S Spaces
7 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.
8 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.
9 Filler 106 9 S Spaces
10 End-to-end ID 115 35 AN Optional. A unique identifier to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.
11 Remittance Information 1 150 140 AN Optional. Information supplied to enable the matching/reconciliation of a transaction with the items that the payment is intended to settle, such as commercial invoices in an accounts receivable system, in an unstructured form.
12 Remittance Information 2 290 140 AN As above.

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 characters.
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.

Westpac Privacy Statement

Privacy Statement (for individuals whose personal information may be collected - in this clause referred to as "you"). All personal information we collect about you is collected, used and disclosed by us in accordance with our Privacy Statement which is available at Privacy Statement or by calling us through your relationship manager or Westpac representative. Our Privacy Statement also provides information about how you can access and correct your personal information and make a complaint. You do not have to provide us with any personal information but, if you don't, we may not be able to process an application or a request for a product or service.