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:

File control header (one only per file)
Batch control header (per supplier business)
Transaction detail (one or more in each batch)
Batch control trailer (one only per batch header)
File control trailer (one only per file)

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
Bank account transaction detail
PayTo transaction detail

Card transaction detail

If you send payment files containing full card account details, your system must meet Payment Card Industry Data Security Standard (PCI-DSS) requirements for storing card numbers. Read more about QuickStream PCI Compliance.

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

The functionality described in this section applies to aggregator merchants only. Other merchants cannot use the functionality described in this section.

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.

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 `AggregatorNameSubMerchantName`. For example: `AggregatorName` is `Jane's Transactions`, abbreviated to `JAT`. `SubMerchantName` name is `Jill's Bikes`. The value of this field may be `JATJillsBikes`. `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.