Skip to main content

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. You must still update the Unique File Identifier and Unique Batch Code in the Flat File, or the Creation Date and Creation Sequence in the MTS orders file to unique values if you have already processed a payment file with these values. 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:

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 either AWAITING_CLEARANCE or 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,
  • the payment file has not finished processing.
This resource is valid when the file status is either AWAITING_CLEARANCE or 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 either AWAITING_CLEARANCE or 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 either AWAITING_CLEARANCE or 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 either AWAITING_CLEARANCE or 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 either AWAITING_CLEARANCE or 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:

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.

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.