Payment Files API

API Reference

Payment files API

Payment files contain transactions that you want QuickStream to process. Payment files contain capture and refund transactions in payment batches. Each payment batch contains transactions for either credit card or bank account transactions but not both. Use this resource to:

  1. Upload a payment file.
  2. Get the status and details of a payment file.
  3. List payment files uploaded in the last 365 days.
  4. Get the details of a payment batch.
  5. List the payment batches in the payment file.
  6. List individual transactions contained in each payment batch.

To use this feature:

  1. Generate a file in one of the Payment File Formats.
  2. Upload the file.
  3. Get the status of the file.
  4. If QUEUED, Queued for processing. Wait a minute and then get the status of the file again.
  5. If ERROR, correct the errors and upload the file again.
  6. If PROCESSING, QuickStream is checking the file for format errors and processing transactions in the file. Payment files with a very large number of transactions may take some time.
  7. If AWAITING_CLEARANCE, QuickStream is waiting on all transactions to clear with the other financial institution. Bank account payments may take up to 5 business days to clear.
  8. If COMPLETE, update your system with the status of individual Payment Batches and Transactions.

Upload payment file

To upload a payment file, you must:

  • Create a file in one of the Payment File Formats.
  • Encode your POST as multipart/form-data using curl or a standard library.
  • In the multipart request:
    • send a field named file containing a file with a unique filename, and
    • send a field named format with CSV, CSV_TOKENS, FLAT_FILE, FLAT_FILE_TOKENS, MTS or MTS_TOKENS matching the chosen Payment File Format.

Request

POST /payment-files

Use your Secret API key to access this resource.

Request headers

Header Description
Prevent-CSRF Set to true. Required. This header is required for multipart requests to prevent Cross-Site Request Forgery

Request body

Encode your POST as multipart/form-data. Provide the file contents in the multipart binary part. Provide the following in the multipart request part:

Field Format Description
file string File with a unique file name.
format string The format of the file. Provide CSV, CSV_TOKENS, FLAT_FILE, FLAT_FILE_TOKENS, MTS or MTS_TOKENS matching the chosen Payment File Format.
ignoreDuplicateCheck boolean Optional. If true, the duplicate check will not be performed. Defaults to false when not provided.

Response

If successful, this method returns the Payment File Model in the response body. The Location response header contains the URL to the payment file you uploaded. The status field describes the status of the payment file.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The file is stored. QuickStream will check the format of the file and then process transactions. You must check the status of the file.
400 BAD REQUEST Prevent-CSRF header is missing or is not set to true.
422 UNPROCESSABLE ENTITY The request contained invalid data or the server has detected a duplicate payment file. Refer to errors in the response body for more. View more

Duplicate checking

This API returns a 422 UNPROCESSABLE ENTITY when it detects a duplicate payment file. A payment file with the same name and hashed message contents indicates a duplicate.

QuickStream compares payment files over the last 365 days. Bypass duplicate checking by providing ignoreDuplicateCheck = true.

You may further prevent duplicate processing by setting a unique value for the Idempotency-Key header on POST requests.

Payment file formats

Payment files contain payments that you want QuickStream to process. You can process payments by sending a file in one of these formats:

Flat file

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 MMYYYY 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 22 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

CSV

CSV Legacy Format Card Payments Only Account Tokens Supported AUD or NZD Pre-Auth Not Supported

The CSV format is the simplest format. It specifies only the required fields. This format supports only card payments.

All files are plain text using UTF-8 character encoding. All records except the last are separated by the CR LF end-of-line marker. Fields containing double quotes and commas must be enclosed in double quotes. If double quotes enclose a field, then a double quote appearing inside a field must be escaped by preceding it with another double quote.

To upload a payment file in this format you must

  • Send the parameter format with CSV or CSV_TOKENS.
  • Use only one currency per file.
  • Use only one supplier business code per file.
  • In the Account Number field, use only all card PANs or bank account numbers for CSV or all account tokens for CSV_TOKENS files.

Header row:

Column Value
A Transaction Number
B Merchant ID
C Account Number
D Customer Number
E Transaction Amount
F Expiry Date
G Currency
H Customer Name
I Transaction Type
J Capture ID
K Invoice Number
L Merchant Name
M Merchant Street Address
N Merchant Location
O Merchant State
P Merchant Country
Q Merchant Postcode
R Sub-merchant ID

The header row is optional.

Detail rows:

Column Value Required Description
A Transaction Number Required A unique reference for a transaction.
B Merchant ID Required A reference to the supplier business you wish to process the payment for. Must be the same for every transaction in the file. Create a separate file for each different supplier business code.
C Account Number Required when Customer Number is not provided. The full card number, or an account token. Use only all card PANs for CSV or all account tokens for a CSV_TOKENS file. Provide blank for refunds as QuickStream will use the original account.
D Customer Number Required when Account Number is not provided. Your customer's number.
E Transaction Amount Required The transaction amount. If this is a refund, this the amount you wish to refund up to the original payment amount.
F Expiry Date Optional The expiry date of the card in MMYY format. E.g. January 2021 is 0121
G Currency Optional AUD or NZD. Defaults to AUD when not provided. Must be the same for every transaction in the file. Create a separate file for each currency.
H Customer Name Optional An optional customer name. This is for human readable purposes only.
I Transaction Type Optional Blank or R. Leave this field blank to indicate a payment. Use R to indicate a refund.
J Capture ID Required when Transaction Type is R. The receipt number provided for the original payment.
K Invoice Number Optional An optional reference for this transaction. Often this is an invoice number.
L Merchant Name Required for Aggregator merchants only. See Soft descriptors for Aggregators.
M Merchant Street Address Required for Aggregator merchants only. See Soft descriptors for Aggregators.
N Merchant Location Required for Aggregator merchants only. See Soft descriptors for Aggregators.
O Merchant State Required for Aggregator merchants only. See Soft descriptors for Aggregators.
P Merchant Country Required for Aggregator merchants only. See Soft descriptors for Aggregators.
Q Merchant Postcode Required for Aggregator merchants only. See Soft descriptors for Aggregators.
R Sub-merchant ID Required for Aggregator merchants only. See Soft descriptors for Aggregators.

Do not include any further columns.

Minimal file with card number format = CSV

"Transaction Number","Merchant ID","Account Number","Customer Number","Transaction Amount","Expiry Date"
"123456","SUPPLIERBUSINESSCODE","4242424242424242","CUSTOMERA","100.00","0121"

Minimal file with customer number and account token format = CSV_TOKENS

"Transaction Number","Merchant ID","Account Number","Customer Number","Transaction Amount","Expiry Date"
"123456","SUPPLIERBUSINESSCODE","CUST89455677","CUSTOMERA","100.00","0121"

Full file with card number and refund format = CSV

"Transaction Number","Merchant ID","Account Number","Customer Number","Transaction Amount","Expiry Date","Currency","Customer Name","Transaction Type","Capture ID","Invoice Number"
"123457","SUPPLIERBUSINESSCODE","4242424242424242","CUSTOMERA","200.00","0121","AUD","Customer A","","","INVOICE2"
"123458","SUPPLIERBUSINESSCODE","","CUSTOMERA","100.00","","AUD","Customer A","R","1222684604","INVOICE1"

Note:

  • Transactions using this format are flagged as Recurring transactions (i.e. Mastercard or Visa Recurring). Use this format when you hold a valid direct debit agreement from 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 use a different file format. Under no circumstances may you perform one-off transaction using this format.
  • 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 ID.

Westpac MTS orders

Fixed Width Legacy Format Card Payments Only Account Tokens Supported AUD Only Capture Pre-Auth Only

The Westpac MTS (Merchant Transmission Service) format is a legacy format. It may contain only credit card transactions. Use this format if your system already produces MTS files.

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 MTS or MTS_TOKENS.
  • Supports only transactions in AUD.
  • Use only one supplier business code per batch header.
  • In the card number field, use only all Card PANs for MTS or all account tokens for MTS_TOKENS files.

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) or spaces.
  • S - spaces only.

Unless otherwise noted, N numeric fields are right-justified and padded with leading zeros 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 00012594 (assuming the field has a length of 8).

File header

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

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N Must be 1 to indicate file header.
2 Record Sequence 2-7 6 N Not used - set to any numeric value, e.g. 000000.
3 Facility Link ID 8-11 4 N Not used - set to any numeric value, e.g. 000000.
4 Originating PC ID 12-14 3 AN Transmitting PC ID (default is P01)
5 Creation Date 15-22 8 N Date the file was created in YYYYMMDD format.
6 Creation Sequence 23-24 2 N Creation Sequence beings at 01 and increments by 1 for each file created on Creation Date.
7 Posting Status 25 1 A O = Original Status
8 Filler 26-80 55 S Spaces

Batch header

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

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N Must be 2 to indicate batch header.
2 Record Sequence 2-7 6 N Not used - set to any numeric value, e.g. 000000.
3 Merchant Identifier 8-15 8 AN Supplier business code to process transactions in this batch.
4 Batch Value Date 16-23 8 N Must be the same as the date in the file header.
5 Batch Sequence Number 24-25 2 N Batch sequence beings at 01 and increments by 1 for each batch in the file.
6 Posting Status 26 1 A O = Original Status
7 Filler 27-80 54 S Spaces

Sale/Refund transaction

Each batch contains one or more sale or refund transactions.

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N 3 for sale, 4 for refund.
2 Record Sequence 2-7 6 N Not used - set to any numeric value, e.g. 000000.
3 Merchant Identifier 8-15 8 AN Must be the same as the Merchant Identifier in the batch header.
4 Card Number or Account Token 16-34 19 N Card Number for MTS format. Do not include dashes or spaces between card number digits. Account Token for MTS_TOKENS format.
5 Transaction Date 35-42 8 N Must be the same as the Batch Value Date in the batch header.
6 Transaction Amount 43-50 8 N Transaction amount in cents, right justified with zero padding. For example, $125.94 is expressed as 00012594.
7 Sale Type 51 1 A M - Mail Order
T - Telephone order
R - Recurring transaction.
8 POS Terminal Indicator 52 1 S Not used - set a single space.
9 Authorisation Code 53-58 6 AN If capturing a previous pre-auth transaction, this is the 6 character authorisation code from that pre-auth transaction. Otherwise, leave blank.
10 Merchant Reference Number 59-64 6 AN Your first reference number for this transaction. Populate this field with your system's identifier for this transaciton to allow tracing.
11 Card Expiry Date 65-70 6 N The card expiry date in MMYYYY format.
12 Merchant Secondary Reference Number 71-78 8 AN Your second reference number for this transaction. Leave blank if not required.
13 Filler 79-80 2 S Spaces

Note:

  • The Merchant Reference Number and Merchant Secondary Reference Number are shown as concatenated in QuickStream. For example, if the Merchant Reference Number field is abc1 and the Merchant Secondary Reference Number is 234xyz, the Payment Reference Number field will show abc1234xyz.
  • The Sale Type of R 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. M or T). 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.

Batch trailer

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

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N Must be 5 to indicate batch trailer.
2 Record Sequence 2-7 6 N Not used - set to any numeric value, e.g. 000000.
3 Merchant Identifier 8-15 8 AN Must be the same as the merchant ID in the batch header.
4 Batch Transaction Count 16-21 6 N Number of transactions in the batch.
5 Batch Transaction Total Amount 22-31 10 N Sum of batch sales transaction amounts minus sum of batch refund transaction amounts.
6 Batch Amount Sign Indicator 32 1 A C for credit if the above total is positive. D for debit if the above total is negative.
7 Sales Count 33-37 5 N Number of sale transactions in this batch.
8 Sales Total Amount 38-47 10 N Total amount for all sale transactions in this batch.
9 Refunds Count 48-52 5 N Number of refund transactions in this batch.
10 Refunds Total Amount 53-62 10 N Total amount for all refund transactions in this batch.
11 Filler 63-80 18 S Spaces

File trailer

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

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N Must be 6 to indicate file trailer.
2 Record Sequence 2-7 6 N Not used - set to any numeric value, e.g. 000000.
3 Facility Link ID 8-11 4 N Same as file header.
4 Batch Count 12-15 4 N Number of batches present in the file.
5 Transaction Count 16-22 7 N Total number of transactions in the file.
6 Transaction Total Amount 23-33 11 N Sum of all sales transaction amounts minus sum of all refund transaction amounts.
7 File Amount Sign Indicator 34 1 A C for credit if the above total is positive. D for debit if the above total is negative.
8 Sales Count 35-40 6 N Number of sale transactions in this file.
9 Sales Total Amount 41-51 11 N Total amount for all sale transactions in this file.
10 Refunds Count 52-57 6 N Number of refund transactions in this file.
11 Refunds Total Amount 58-68 6 N Total amount for all refund transactions in this file.
12 Filler 69-80 12 S Spaces

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:

  • Columns L to R in the CSV format.
  • Transaction Detail Record - Fields 12 to 18 in the Flat File 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.

Get payment file

Get the status of a payment file.

Request

GET /payment-files/{paymentFileId}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentFileId string QuickStream's unique identifier for the payment file.

Request body

None.

Response

If successful, this method returns the Payment File Model in the response body. The status field describes the status of the payment file.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentFileId path parameter may be incorrect. View more.

List payment files

List the previous 365 days of payment files.

Request

GET /payment-files

Use your Secret API key to access this resource.

Path parameters

None.

Request body

None.

Response

This is a paginated resource. The list is sorted to show the most recent payment files first. The status field describes the status of the payment file.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of Payment File Model A paginated list of payment files.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.

List payment file errors

This resource is only valid when the payment file status is ERROR. Use this resource to list the errors in a payment file.

Request

GET /payment-files/{paymentFileId}/errors

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentFileId string QuickStream's unique identifier for the payment file.

Request body

None.

Response

This is a paginated resource. The list is ordered by line number.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of File Error Model A paginated list of errors.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentFileId path parameter may be incorrect. View more.

Get payment batch

This resource is only available when the payment file status is COMPLETE.

A payment file contains one or more payment batches.

A payment batch:

  • contains only card transactions or only bank account transactions, and
  • transactions in a payment batch are for a single supplier business and currency.

In most cases, you will have one or two payment batches per file.

Use this resource to get the details of a payment batch.

Request

GET /payment-batches/{paymentBatchId}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentBatchId string QuickStream's unique identifier for the payment batch.

Request body

None.

Response

If successful, this method returns the Payment Batch Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentBatchId path parameter may be incorrect or or the status is not COMPLETE. View more.

List payment batches

This resource is only available when the payment file status is AWAITING_CLEARANCE or COMPLETE.

Use this resource to list the payment batches in a payment file.

Request

GET /payment-files/{paymentFileId}/payment-batches

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentFileId string QuickStream's unique identifier for the payment file.

Request body

None.

Response

This is a paginated resource.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of Payment Batch Model A paginated list of payment batches.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentFileId path parameter may be incorrect or the status is not AWAITING_CLEARANCE or COMPLETE. View more.

List payment batch transactions

This resource is only available when the payment file status is COMPLETE.

Use this resource to list the transactions in a payment batch. You can filter the results for only Approved or Declined transactions. The transaction status allows you to determine if transactions were declined.

Request

GET /payment-batches/{paymentBatchId}/transactions?status={statusCode}

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentBatchId string QuickStream's unique identifier for the payment batch.

Request body

None.

Query parameters

Parameter Name Format Description
status string Optional. Filter the transactions by their status. Approved or Declined.

Response

The response is in the same format as returned for transaction search. The transaction status allows you to determine if transactions were declined.

Field Format Description
links Array of Links Links to related documents and resources.
data Array of Transaction Response Model A list of transactions.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
404 NOT FOUND The paymentBatchId path parameter may be incorrect or thestatus is not COMPLETE. View more.

Download flat file report

This resource is valid when the file status is COMPLETE. Use this resource if your software is compatible with the Flat File report.

Request

GET /payment-files/{paymentFileId}/flat-file

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentFileId string QuickStream's unique identifier for the payment file.

Headers

Header Name Description
Accept Must be text/plain or not provided.

Request body

None.

Response

If successful, this method returns a Flat File report.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded and the report will download.
202 ACCEPTED The report is generating. Try again in one minute.
404 NOT FOUND One of:
  • The paymentFileId path parameter may be incorrect,
  • the payment file has errors,
  • there are bank account payments in the payment file, or
  • the payment file has not finished processing.
Bank account payments are not supported in this format. This resource is valid when the file status is COMPLETE.
406 NOT ACCEPTABLE The Accept header must be text/plain or not provided.

Download CSV report

This resource is valid when the file status is COMPLETE. Use this resource if your software is compatible with the CSV report.

Request

GET /payment-files/{paymentFileId}/csv

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentFileId string QuickStream's unique identifier for the payment file.

Headers

Header Name Description
Accept Must be text/plain or not provided.

Request body

None.

Response

If successful, this method returns a CSV report.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded and the report will download.
202 ACCEPTED The report is generating. Try again in one minute.
404 NOT FOUND One of:
  • The paymentFileId path parameter may be incorrect,
  • the payment file has errors,
  • there are bank account payments in the payment file, or
  • the payment file has not finished processing.
Bank account payments are not supported in this format. This resource is valid when the file status is COMPLETE.
406 NOT ACCEPTABLE The Accept header must be text/plain or not provided.

Download Westpac MTS rejects report

This resource is valid when the file status is COMPLETE. Use this resource if your software is compatible with the Westpac MTS rejects report.

Request

GET /payment-files/{paymentFileId}/mts-rejects

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
paymentFileId string QuickStream's unique identifier for the payment file.

Headers

Header Name Description
Accept Must be text/plain or not provided.

Request body

None.

Response

If successful, this method returns a Westpac MTS rejects report.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded and the report will download.
202 ACCEPTED The report is generating. Try again in one minute.
404 NOT FOUND One of:
  • The paymentFileId path parameter may be incorrect,
  • the payment file has errors,
  • there are bank account payments in the payment file, or
  • the payment file has not finished processing.
Bank account payments are not supported in this format. This resource is valid when the file status is COMPLETE.
406 NOT ACCEPTABLE The Accept header must be text/plain or not provided.

Transaction report formats

Each payment file format has a corresponding transaction report format:

Flat file report

Fixed Width
Card Payments
Bank Account Payments
Account Tokens Supported

The flat file contains the list of all transactions that were approved and declined during processing. The Flat File format is a fixed-width text file. The file consists of five record types.

The 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).

Report control header

The file header is the first record in the file.

No Field Name Position Length Data Type Description
1 Record Type 1 1 N 1 to indicate file header.
2 Client Community Code 2 10 AN Your community code.
3 File Creation Date 12 8 N Date the file was created 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 The Unique File Identifier you provided in the payment file.
7 Filler 74 177 S Spaces.

Report batch header

One batch header record will be present for each payment batch.

No Field Name Position Length Data Type Description
1 Record Type 1 1 N 3 to indicate batch header.
2 Client Company Name 2 30 AN Supplier business name.
3 Client Company Code 32 10 AN Supplier business code that processed the 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 Spaces.
6 Unique Batch Code 62 15 AN The Unique Batch Identifier you provided in the payment file.
7 Refund Flag 77 1 A R for a refund batch. Otherwise a single space.
9 Filler 78 170 S Spaces.

Report transaction detail

Each record represents a transaction that was approved or declined during processing. Card and bank account transactions use the same record format, but the usage of the fields differ:

Report 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 MMYYYY format.
4 Account Number 12 17 AN Card number or Account Token. Left justified with trailing spaces.
5 Amount 29 10 N The transaction amount.
6 Customer Number 39 15 AN Customer number provided in the payment file.
7 Customer Name 54 22 AN Customer name provided in the payment file.
8 Transaction Number 76 15 AN The transaction number provided in the payment file.
9 Originating System Code 91 2 S Spaces.
10 Receipt Number 93 21 N A unique reference for a transaction. Left justified with trailing spaces.
11 Filler 114 16 S Spaces.
12 Summary Code 130 1 N Success indicator for the Response Codes.
13 Response Code 131 3 AN The response code from the transaction processing.
14 Response Description 134 60 AN Description for the Response Codes.
15 Card Scheme 194 2 A The card scheme. VI (Visa), MC (Mastercard), AX (American Express), DC (Diners Club), JC (Japan Credit Bureau), or UP (Union Pay). Spaces for unknown or invalid cards.
16 Soft Decline Flag 196 1 N 1 if the transaction was a soft-decline. Otherwise a single space.
17 Automatic Retry Flag 197 1 N 1 if the transaction will be automatically retried. Otherwise a single space.
18 Filler 198 53 S Spaces.

Report 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 AN The BSB or spaces for Account Token payments
4 Account Number 12 17 AN Bank account number or Account Token. Left justified with trailing spaces.
5 Amount 29 10 N The transaction amount.
6 Customer Number 39 15 AN Customer number provided in the payment file.
7 Customer Name 54 22 AN Customer name provided in the payment file.
8 Transaction Number 76 15 AN The transaction number provided in the payment file.
9 Originating System Code 91 2 S Spaces.
10 Receipt Number 93 21 N A unique reference for a transaction. Left justified with trailing spaces.
11 Filler 114 16 S Spaces.
12 Summary Code 130 1 N Success indicator for the Response Codes.
13 Response Code 131 3 AN The response code from the transaction processing.
14 Response Description 134 60 AN Description for Response Codes.
15 Filler 194 2 S Spaces.
16 Soft Decline Flag 196 1 N 1 if the transaction was a soft-decline. Otherwise a single space.
17 Automatic Retry Flag 197 1 N 1 if the transaction will be automatically retried. Otherwise a single space.
18 Filler 198 53 S Spaces.

Report batch trailer

Each batch has 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 22 10 N Sum of all transaction amounts in the batch.
4 Client Company Code 18 10 AN Same as the value in the batch header.
5 Unique Batch Code 28 15 AN Same as the value in the batch header.
6 Filler 43 208 S Spaces

Report control trailer

The file trailer record is 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 Community Code 24 10 AN Same as the value in the file header.
6 Unique File Identifier 64 20 AN Same as the value in the file header.
7 Filler 84 167 S Spaces

CSV report

CSV
Legacy Format
Card Payments Only
Account Tokens Supported
AUD or NZD
Pre-Auth Not Supported

This format supports only card payments.

This report is plain text using UTF-8 character encoding. All records except the last are separated by the CR LF end-of-line marker. Fields may be enclosed in double quotes. If double quotes enclose a field, then a double quote appearing inside a field is escaped by preceding it with another double quote.

Column Value Description
A Transaction Number A unique reference for a transaction.
B Date The day on which this transaction was considered to have been processed. See Transaction Settlement for more. DD MMM YYYY format.
C Receipt Number Receipt number to display to customers.
D Merchant ID A reference to the supplier business you wish to process the payment for.
E Account Number The full card number, or an account token.
F Customer Number Your customer's number.
G Amount The transaction amount.
H Response Code The response code from the transaction processing.
I Response Description Description for the Response Codes.

Sample file

Transaction Number,Date,Receipt Number,Merchant ID,Account Number,Customer Number,Amount,Response Code,Response Description
PAYMENT1,17 Apr 2018,1224672314,MYSUPPLIER,4000000000000010,,100.41,08,Honour with identification
PAYMENT2,17 Apr 2018,1224672322,MYSUPPLIER,4000000000000093,,10.49,91,Issuer or switch is inoperative
PAYMENT3,17 Apr 2018,1224672332,MYSUPPLIER,4000000000000192,,50.00,05,Do not honour
PAYMENT4,17 Apr 2018,1224672342,MYSUPPLIER,4000000000000291,,100.00,04,Pick-up card
PAYMENT5,17 Apr 2018,1224672352,MYSUPPLIER,4000000000000390,,2100.79,01,Refer to card issuer

Westpac MTS rejects report

Fixed Width
Legacy Format
Card Payments Only
Account Tokens Supported
AUD Only
Capture Pre-Auth Only

The rejects file contains the list of all transactions that were declined during processing. All files are plain text using UTF-8 character encoding. The file has the following general structure:

Deposit file header

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

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N 1 to indicate file header.
2 Error Code 2-4 3 AN Always 000.
3 Facility Link ID 5-8 4 AN Same as the value specified in the payment file.
4 File Date 9-14 6 N File date from the payment file in YYMMDD format.
5 Deposit Sequence 15-16 2 N File sequence number (matches the sequence number in the payment file).
6 Posting Status 17 1 A O - Original
7 Processing Date 18-23 6 N File date from the payment file in YYMMDD format.
8 Filler 24-110 87 S Spaces.

Batch file header

One batch header record will be present for each payment batch.

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N 2 to indicate batch header.
2 Error Code 2-4 3 AN Always 000.
3 Merchant ID 5-12 8 AN Supplier business code that processed the transactions in this batch.
4 Merchant Name 13-37 25 AN Merchant's trading name.
5 Merchant Location 38-57 20 AN Merchant's trading location.
6 Merchant State 58-60 3 A Merchant's trading location state.
7 Batch Date 61-66 6 N Batch date from the payment file in YYMMDD format.
8 Batch Sequence 67-68 2 N Batch sequence from the payment file.
9 Posting Status 69 1 N O - Original
10 Filler 70-110 41 S Spaces.

Financial transaction detail

Each record represents a transaction that was declined during processing.

No Field Name Position Length Data Type Description
1 Transaction Type 1 1 N 3 for sale, 4 for refund.
2 Error Code 2-4 3 AN The response code from the transaction processing. Left-padded with zeros.
3 Merchant ID 5-12 8 N Same as the value specified in the payment file.
4 Card Number or Account Token 13-31 19 AN Left justified with trailing spaces. Account token or full card PAN.
5 Transaction Amount 32-42 11 N Same as the value specified in the payment file.
6 Transaction Date 43-48 6 N Transaction settlement date in YYMMDD format.
7 Trace Details 49-64 16 N A unique reference for a transaction.
8 Merchant Reference Number 65-70 6 AN Same as the value specified in the payment file.
9 Filler 71 1 N Zeros - not used.
10 Filler 72-77 6 AN Always ******.
11 Error Message 78-102 25 AN Description of why the transaction was declined.
12 Merchant Secondary Reference Number 103-110 8 AN Same as the value specified in the payment file.

Payment file model

Field Format Description
paymentFileId string Uniquely identifies the payment file. This value is generated by QuickStream when a payment file is created.
fileName string Unique file name for the payment file.
size integer The size in bytes of the file.
fileFormat string The file format.
createdDate date-time The date that the file was uploaded.
numberOfBatches integer The number of payment batches in the file.
totalTransactionCount integer The total number of transactions in the file.
totalTransactionAmount Money The total of all transactions in the file.
status string The status of the payment file. See Payment File Status.
links Array of Links Links to related documents and resources.

Example payment file response

{
    "paymentFileId" : "12345678",
    "fileName" : "payments.txt",
    "size" : "724",
    "fileFormat" : "MTS",
    "createdDate" : "2018-02-08T11:14:24+1100",
    "numberOfBatches" : "1",
    "totalTransactionCount" : "1",
    "totalTransactionAmount": {
            "currency": "AUD",
            "amount": 10.00,
            "displayAmount": "$10.00"
        },
    "status" : "COMPLETE",
    "links":[]
}

Payment file status

The status field describes the status of the payment file.

Status Notes
QUEUED Queued for processing. Get the status again in one minute.
PROCESSING Checking the file for format errors and processing payments in the file.
AWAITING_CLEARANCE QuickStream is waiting on all transactions to clear with the other financial institutions. Bank account payments may take up to 5 business days to clear.
COMPLETE Transactions have been processed. See List Payment Batches and List Payment Batch Transactions.
ERROR Unable to understand the file format. No transactions will be processed. See List Payment File Errors.

Payment batch model

Field Format Description
paymentBatchId string Uniquely identifies the payment batch. This value is generated by QuickStream when a payment file is created.
batchCode string The batch identifier provided in the payment file.
supplierBusinessCode string The business the payment batch was created against.
merchantAccount Merchant Account For credit card payments, your merchant facility.
directEntryAccount Direct Entry Account For Australian bank account payments, your direct entry settlement account.
paymentMethod string The type of payments in this batch. One of CREDIT_CARD or DIRECT_DEBIT.
createdDate date-time The date that the file was uploaded.
settlementDate date The settlement date of the transactions in the payment batch.
approvedTransactionCount integer The total number of approved transactions in the payment batch.
declinedTransactionCount integer The total number of declined transactions in the payment batch.
totalTransactionCount integer The total number of transactions in the payment batch.
approvedTransactionAmount Money The total of all approved transactions in the payment batch.
declinedTransactionAmount Money The total of all declined transactions in the payment batch.
totalTransactionAmount Money The total of all transactions in the payment batch.
links Array of Links Links to related documents and resources.

Example payment batch response

{
    "paymentBatchId" : "12345678",
    "paymentMethod": "CREDIT_CARD",
    "batchCode" : "2017120511236_01",
    "supplierBusinessCode" : "MYCOMPANY",
    "merchantAccount": {
        "merchantId":"12345678",
        "merchantName":"My Westpac Account",
        "settlementBsb":"032-002",
        "settlementAccountNumber":"123465",
        "displayName":"Your Company 032-002 123465 (12345678)",
        "acquiringInstitution": "WBC",
        "currency": "AUD"
    },
    "createdDate" : "2018-02-08T11:14:24+1100",
    "settlementDate" : "2018-02-08",
    "approvedTransactionCount" : 1,
    "declinedTransactionCount" : 0,
    "totalTransactionCount" : 1,
    "approvedTransactionAmount": {
        "currency": "AUD",
        "amount": 10.00,
        "displayAmount": "$10.00"
    },
    "declinedTransactionAmount": {
        "currency": "AUD",
        "amount": 0.00,
        "displayAmount": "$0.00"
    },
    "totalTransactionAmount": {
        "currency": "AUD",
        "amount": 10.00,
        "displayAmount": "$10.00"
    },
    "links":[]
}

File error model

Field Format Description
line integer The line number an error was found on.
field string The field name in the incoming file where the error was found.
value string The value of the field in the incoming file where the error was found.
errorMessage string The error message.

Example file error response

{
    "line"  : 1,
    "field" : "RecordType",
    "value" : "7",
    "errorMessage" : "This value is not from the list of allowed values: 1,2,3,4,5,6"
}

Transaction settlement

See Transaction Processing and Settlement.

Response codes

See Response Codes.

Test account numbers

To help with the testing process we provide a list of account numbers for you to use.

See Test Account Numbers.