Transactions API

QuickStream REST API Reference

Transactions API

Transactions include payments, refunds and preauths. Using this API you can:

Besides this API, QuickStream has other ways to take payments.

Processing transactions

There are several ways to specify the account used to perform transactions:

You should avoid processing duplicate transactions.

If you are an Aggregator or Staged Digital Wallet Operator you may provide soft-descriptors in the Transaction Request Model.

Avoid duplicate transactions

To avoid processing duplicate transactions:

Process transaction using a single-use-token

Single-use-tokens allow you to avoid sending credit card or bank account details to your server.

To process a one-time credit card or bank account transaction, first generate a single-use-token and then include it in the Transaction Request Model singleUseTokenId field.

You can use single-use-tokens to process:

Process transaction using a tokenised account

To process a transaction using a tokenised account, you will need a customer with a registered account.

The payment can be made by including one of the two fields below in the request body:

  • the customerId representing a customer that has an enabled default tokenised account.
  • the accountToken representing an enabled tokenised account.

You can use tokenized accounts to process:

Process transaction using account details

To process a transaction using account details directly in the request, include a Credit Card Request Model or Bank Account Request Model in the Transaction Request Model creditCard or bankAccount fields.

You can use account details to process:

Electronic Commerce Indicator

The Electronic Commerce Indicator (ECI) is used by acquirers / issuers to determine the type of transaction being processed. The ECI value represents the source of the transaction request. The ECI will also determine whether you need to capture the CVN. An ECI can be INTERNET, PHONE, MAIL, RECURRING.

ECI Payment Type Is a CVN Required?
INTERNET Internet Transaction for Payment Yes
PHONE Interactive Voice Recording or Call Centre Transaction No
MAIL Mail or Telephone Order Transaction No
RECURRING Recurring Transaction No

Get details

Use this resource to get the details of a transaction. You can take the following actions on a transaction:

Request

GET /transactions/{receiptNumber}

Use your Secret API key to access this resource.

Get transaction details

GET /rest/v1/transactions/{receiptNumber} HTTP/1.1
Host: api.quickstream.westpac.com.au
Authorization: Basic U0XBTjZfU0VDX2t0dTM1Y2ZmdTg3M2N4NDMzemNzcHF6bmNmNTg2anRrZno5MjU2dnQ3a3NuZ3M4OHp1OGd5bTN1MmRoajo=

Path parameters

Parameter Name Format Description
receiptNumber string Get the transaction with the receipt number provided.

Request body

None.

Response

If successful, this method returns a Transaction Response Model in the response body.

Transaction response

{
  "links": [],
  "receiptNumber": "1234567890",
  "transactionType": "PAYMENT",
  "status": "Approved",
  "responseCode": "08",
  "responseDescription": "Honour with identification",
  "summaryCode": "0",
  "fraudGuardResult": null,
  "customerReferenceNumber": "CUSTOMER1",
  "paymentReferenceNumber": "INVOICE1",
  "comment": "Credit card payment for Jane Smith.",
  "source": "RESTAPI",
  "settlementDate": "2017-01-01",
  "transactionTime": "2017-01-01T10:26:36+1000",
  "refundable": false,
  "voidable": true,
  "principalAmount": {
    "currency": "AUD",
    "amount": 10.00,
    "displayAmount": "$10.00"
  },
  "surchargeAmount": {
    "currency": "AUD",
    "amount": 1.00,
    "displayAmount": "$1.00"
  },
  "totalAmount": {
    "currency": "AUD",
    "amount": 11.00,
    "displayAmount": "$11.00"
  },
  "merchantAccount": {
    "merchantId": "12345678",
    "merchantName": "My Westpac Account",
    "settlementBsb": "032-002",
    "settlementAccountNumber": "1234576",
    "displayName": "Your Company 032-002 123465 (12345678)",
    "acquiringInstitution": "WBC",
    "currency": "AUD"
  },  
  "creditCard": {
    "accountType": "CREDIT_CARD",
    "accountToken": "MYCOMPANY-123456789",
    "defaultAccount": true,
    "cardNumber": "424242...242",
    "expiryDateMonth": "01",
    "expiryDateYear": "17",
    "cardScheme": "VISA",
    "cardholderName": "Jane Smith"
  },
  "metadata": {
    "extraInformation": "123456789",
    "moreInformation": "testData"
  }
}

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check the receipt number is valid. Refer to the response body for further details.

List recent transactions

Get a list of your 20 most recent transactions across your businesses. Provide supplierBusinessCode to list the 20 most recent transactions for that business.

Request

GET /transactions?supplierBusinessCode={code}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
supplierBusinessCode string Optional. Provide the unique identifier for one of your businesses to list the 20 most recent transactions for only that business. See Business API for more.

Request body

None.

Response

The most recent transaction is first.

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.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The supplierBusinessCode query parameter may be incorrect. View more.

List by reference number

List transactions by reference number. Use this resource to find transactions by Receipt, Customer Reference or Payment Reference Number.

Request

GET /transactions/for-reference-number?referenceNumber={string}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
referenceNumber string Get a list of transactions for the provided Receipt, Customer Reference or Payment Reference Number.

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more.
422 UNPROCESSABLE ENTITY referenceNumber contains non-ASCII characters or is empty. View more.

List by settlement date

Use this resource to list transactions by settlement date. Settlement is the process of paying you for transactions which have been processed. The Settlement Date is the day on which a transaction was considered to have been processed.

See Transaction Settlement for more.

Request

GET /transactions/for-settlement-date?settlementDate={date}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
settlementDate date The transaction settlement date.

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more.
422 UNPROCESSABLE ENTITY settlementDate is not in the valid date format or is empty. View more.

List by account token

Use this resource to list transactions taken for an Account Token.

Credit card and bank accounts are registered for customers. The unique identifier for a customer's credit card or bank account is a called an account token. Use an account token to take payments for those accounts. Use the Customers API to manage their account tokens.

Request

GET /transactions/for-account-token?accountToken={string}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
accountToken string The unique identifier for a customer's credit card or bank account. See Customers API for more.

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly and refer to the response body for further details. View more.
422 UNPROCESSABLE ENTITY accountToken contains non-ASCII characters or is empty. View more

List by credit card

Use this resource to list transactions taken using a credit card. Provide the first 6 and last 3 digits of the credit card number to search.

Request

GET /transactions/for-credit-card?firstSix={number}&lastThree={number}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
firstSix string The first six digits of the credit card number.
lastThree string The last three digits of the credit card number.

Request body

None.

Response

This is a paginated resource. The most recent transaction is first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly and refer to the response body for further details. View more.
422 UNPROCESSABLE ENTITY firstSix or lastThree contain non-numeric characters, is empty or has an invalid length. View more

List by bank account

Use this resource to list transactions taken using an Australian bank account. Provide the BSB and Account Number of the payment bank account to search.

Request

GET /transactions/for-bank-account?bsb={string}&accountNumber={number}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
bsb string The BSB of the payment bank account. E.g. 032-002.
accountNumber string The account number of the payment bank account. Account numbers are 6 to 9 digits.

Request body

None.

Response

This is a paginated resource. Transactions are sorted with the most recent transaction first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly and refer to the response body for further details. View more.
422 UNPROCESSABLE ENTITY bsb or accountNumber contain non-ASCII characters, is empty or has an invalid length. View more

List suspended transactions

Use this resource to list transactions suspended by Fraud Guard. A transaction is suspended when Fraud Guard has deemed it suspicious based on the suspension rules you have configured in QuickStream. Fraud Guard sets the transaction response code to 34 - Suspected Fraud.

Sign in to QuickStream to complete or cancel a transaction.

Request

GET /transactions/suspended?supplierBusinessCode={code}&month={YYYY-MM}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
supplierBusinessCode string Optional. Provide the unique identifier for one of your businesses to list suspended transactions for only that business. See Business API for more.
month date-month Provide the year and month YYYY-MM to list suspended transactions for only that period. You can search up to 6 months in the past.

Request body

None.

Response

This is a paginated resource. Transactions are sorted with the most recent transaction first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The supplierBusinessCode or month query parameter may be incorrect. View more.

List refunds of a transaction

Use this resource to list refunds of a transaction. A transaction may be refunded for the full amount, or a partial amount. The transactions returned by this resource make up the total amount of this transaction refunded to your customer.

Request

GET /transactions/{receiptNumber}/refunds

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
receiptNumber string List refunds the transaction with the receipt number provided.

Request body

None.

Response

This is a paginated resource. The most recent refund transaction is first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more.

List retries of a transaction

Use this resource to list the retries of a failed transaction.

Transactions that have been soft-declined by the account holder's financial institution can be retried and may be successful in the future. A failed transaction may be retried manually or automatically by configuring a schedule.

When a transaction is retried, a new transaction is attempted. This resource lists the retry attempts of a transaction.

Request

GET /transactions/{receiptNumber}/retries

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
receiptNumber string List retries of the transaction with the receipt number provided.

Request body

None.

Response

This is a paginated resource. The most recent retry transaction is first.

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

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
200 OK The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more.

List open pre-authorisations

Use this resource to list initial pre-authorisation or a re-authorisation transactions that have not been captured. You can capture against an initial pre-authorisation or a re-authorisation transaction.

Request

GET /transactions/open-preauths?month={YYYY-MM}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
month date-month Return the list of open pre-authorisations by month and year. e.g. 2018-01 for January 2018.
supplierBusinessCode string Optional. Provide the unique identifier for one of your businesses to list the open pre-authorisations for only that business. See Business API for more.

Request body

None.

Response

The most recent open pre-authorisation for the month is first.

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.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The supplierBusinessCode query parameter may be incorrect. View more.

Soft descriptors for aggregators

Soft-descriptors are informational fields that Aggregators must collect for each transaction about a sub-merchant. These merchant descriptor fields allow some control over the cardholder narrative for each transaction. The fields below can be provided in the request body containing details of your sub-merchant. If you provide one field, you must provide all fields.

Field Format Description
merchantName string Up to 22 characters. This field is only relevant for credit card payments for Aggregators.
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.
merchantStreetAddress string Up to 48 characters. This field is only relevant for credit card payments for Aggregators.
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.
merchantLocation string Up to 13 characters. This field is only relevant for credit card payments for Aggregators.
The city or suburb of the sub-merchant's trading address.
merchantState string 2 or 3 characters. This field is only relevant for credit card payments for Aggregators.
The state of the sub-merchant's trading address. One of:
  • NSW
  • ACT
  • VIC
  • QLD
  • NT
  • SA
  • WA
  • TAS
merchantCountry string This field is only relevant for credit card payments for Aggregators.
Must be set to AU.
The sub-merchant must be registered in Australia and have a presence and process payments within Australia.
merchantPostCode string 4 characters. This field is only relevant for credit card payments for Aggregators.
The postal code of the sub-merchant's trading address.
subMerchantId string Up to 15 characters. This field is only relevant for credit card payments for Aggregators.
A unique identifier for your sub-merchant. The aggregator allocates the sub-merchant identifier. Westpac does not allocate this value.

Take payment

Use this resource to take card or bank account payments. You can provide account details directly, from a single-use-token or using a tokenised account.

Request

POST /transactions

Use your Secret API key to access this resource.

To take a card payment using a single-use-token:

{
    "transactionType" : "PAYMENT",
    "singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 10.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

To take a payment using a customer's default tokenised account:

{
    "transactionType": "PAYMENT",
    "customerId": "-13669603",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 100.00,
    "currency": "AUD",
    "eci": "PHONE"
}

To take a payment using a specified tokenised account:

{
    "transactionType": "PAYMENT",
    "accountToken": "QVTEST-143227292",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 100.00,
    "currency": "AUD",
    "eci": "PHONE"
}

To take a direct card payment:

{
    "transactionType" : "PAYMENT",
    "creditCard": {
        "cardholderName" : "Jane Smith",
        "cardNumber" : "4242424242424242",
        "expiryDateMonth": "12",
        "expiryDateYear": "2022",
        "cvn": "123"
    },
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 10.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

Request body

Field Format Required Description
transactionType string Required PAYMENT
supplierBusinessCode string Required The code that uniquely identifies your business.
principalAmount Money Required The amount of the payment before any surcharge is added. If the business referenced by supplierBusinessCode has card surcharges configured, a surcharge amount will be calculated and added to this amount.
currency string Required One of AUD or NZD.
eci string Required for card payments. The Electronic Commerce Indicator (ECI). INTERNET, PHONE, MAIL or RECURRING.
ipAddress string Required for all single-use-token transactions and for direct payments with the INTERNET ECI. The IP address of the payer. This must be a public IP address. It must not be the internal IP address of your private network. Used by Fraud Guard to suspend suspicious transactions.
singleUseTokenId string Required when taking a payment using a single-use-token A token issued by QuickStream which holds card or bank account details. See Process transaction using a single-use-token.
customerId string Required when taking a payment using the customer's default account. The customerId representing a customer that has an enabled default account. See Process transaction using a tokenised account.
accountToken string Required when taking a payment using an Account Token. The accountToken representing an enabled account. See Process transaction using a tokenised account.
creditCard Credit Card Request Model Required when using card details The payment account to process a transaction. See Process transaction using account details.
bankAccount Bank Account Request Model Required when using Australian bank account details The payment account to process a transaction. See Process transaction using account details.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

You must handle errors and avoid duplicate transactions.

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data, the refund amount exceeds the payment amount of the original transaction, or the transaction may have been previously refunded. Refer to errors in the response body for more. View more

Void payment

Use this resource to void a transaction.

If you void a transaction, it will not appear on your customer's statement or form part of your settlement total. To determine if a transaction can be voided, get the transaction details and use the voidable field.

Request

POST /transactions/{receiptNumber}/void

Use your Secret API key to access this resource.

Path parameters

Parameter Name Format Description
receiptNumber string The receipt number of the transaction to void.

Request body

None.

Response

If successful, this method returns a Transaction Response 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.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
404 NOT FOUND The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more.

Refund payment

Use this resource to refund a payment.

To determine if a payment can be refunded, get the transaction details and use the refundable field. The refund will credit the bank account or credit card used on the payment. You can never refund more than the payment amount.

You can list the refunds of a transactions.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required REFUND
principalAmount Money Required The amount to refund before any surcharge is added. If the business referenced by supplierBusinessCode has card surcharges configured, a surcharge amount will be calculated and added to this amount.
currency string Required One of AUD or NZD.
originalReceiptNumber string Required The receipt number of the transaction to refund.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

Refund a transaction

{
    "originalReceiptNumber": "1204957934",
    "transactionType" : "REFUND",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "REFUND1",
    "currency" : "AUD",
    "comment" : "Refund a payment for Jane Smith."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data, the refund amount exceeds the payment amount of the original transaction, or the transaction may have been previously refunded. Refer to errors in the response body for more. View more

Pre-authorisation

Use this resource to pre-authorise a card payment. Later, capture the pre-authorisation to charge the card. Approved pre-authorisation transactions that have not yet been captured are listed in QuickStream Portal.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required PREAUTH
supplierBusinessCode string Required The code that uniquely identifies your business.
principalAmount Money Required The amount to pre-authorise before any surcharge is added. If the business referenced by supplierBusinessCode has card surcharges configured, a surcharge amount will be calculated and added to this amount.
currency string Required One of AUD or NZD.
eci string Required. The Electronic Commerce Indicator (ECI). INTERNET, PHONE, MAIL or RECURRING.
ipAddress string Required for all single-use-token transactions and for direct payments with the INTERNET ECI. The IP address of the payer. This must be a public IP address. It must not be the internal IP address of your private network. Used by Fraud Guard to suspend suspicious transactions.
singleUseTokenId string Required when pre-authorising a payment using a single-use-token A token issued by QuickStream which holds card or bank account details. See Process transaction using a single-use-token.
customerId string Required when pre-authorising a payment using the customer's default account. The customerId representing a customer that has an enabled default account. See tokenised account payments.
accountToken string Required when pre-authorising a payment using an Account Token. The accountToken representing an enabled account. See Process transaction using a tokenised account.
creditCard Credit Card Request Model Required when using card details The payment account to process a transaction. See Process transaction using account details.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

You must handle errors and avoid duplicate transactions.

Fraud Guard is initiated on pre-authorisation. Pre-authorisations available for capture have already passed fraud guard validation.

To process a single-use-token pre-authorisation:

{
    "transactionType" : "PREAUTH",
    "singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 10.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

To process a pre-authorisation using a customer's default tokenised account:

{
    "transactionType": "PREAUTH",
    "customerId": "-13669603",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 100.00,
    "currency": "AUD",
    "eci": "PHONE"
}

To process a pre-authorisation using a specified tokenised account:

{
    "transactionType": "PREAUTH",
    "accountToken": "QVTEST-143227292",
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 20.00,
    "currency": "AUD",
    "eci": "PHONE"
}

To process a direct pre-authorisation:

{
    "transactionType" : "PREAUTH",
    "creditCard": {
        "cardholderName" : "Jane Smith",
        "cardNumber" : "4242424242424242",
        "expiryDateMonth": "12",
        "expiryDateYear": "2022",
        "cvn": "123"
    },
    "supplierBusinessCode": "MYSUPPLIER",
    "principalAmount": 30.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the transaction model is returned in the response body.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

Capture pre-authorisation

Use this resource to capture a pre-authorisation. You can capture a pre-authorisation only once, for an amount up to double the pre-authorised amount.

Use List open pre-authorisations to find initial or a re-authorisation pre-authorisations that have not been captured. You can capture against an initial or a re-authorisation pre-authorisation.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required CAPTURE
supplierBusinessCode string Required The code that uniquely identifies your business.
principalAmount Money Required The amount of the capture before any surcharge is added. Send a positive value that does not exceed double the amount of the pre-authorisation transaction. If the business referenced by supplierBusinessCode has card surcharges configured, a surcharge amount will be calculated and added to this amount.
currency string Required One of AUD or NZD.
originalReceiptNumber string Required The receipt number of the pre-authorisation transaction to capture.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Capture a pre-authorisation

{
    "originalReceiptNumber": "1204957935",
    "transactionType" : "CAPTURE",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "CAPTUREPREAUTH1",
    "currency" : "AUD",
    "comment" : "Capturing a pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the transaction model is returned in the response body.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

Cancel a pre-authorisation

Use this resource to partially or fully cancel a pre-authorisation. You must perform the cancellation against the original successful Visa/Mastercard pre-authorisation transaction.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

To perform a full cancellation of a pre-authorisation you must:

  • send cancellationType = FULL
  • send the full amount of the original pre-authorisation in principalAmount.

To perform a partial cancellation of a pre-authorisation you must:

  • send cancellationType = PARTIAL
  • send the partial amount of the outstanding balance that you wish to cancel of the original pre-authorisation in principalAmount.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required PREAUTH_CANCELLATION
cancellationType string Required FULL when performing a full cancellation of a pre-authorisation. PARTIAL when performing a partial cancellation of a pre-authorisation.
principalAmount Money Required Send the full amount of the original pre-authorisation when performing a FULL cancellation. Send the partial amount to cancel of the original pre-authorisation when performing a PARTIAL cancellation.
currency string Required One of AUD or NZD.
originalReceiptNumber string Required The receipt number of the pre-authorisation transaction to perform the cancellation for.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Full cancellation of a pre-authorisation

{
    "originalReceiptNumber": "1204957975",
    "transactionType" : "PREAUTH_CANCELLATION",
    "cancellationType" : "FULL",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "CANCELPREAUTH1",
    "currency" : "AUD",
    "comment" : "Fully cancelling a pre-authorisation."
}

Partial cancellation of a pre-authorisation

{
    "originalReceiptNumber": "1204957976",
    "transactionType" : "PREAUTH_CANCELLATION",
    "cancellationType" : "PARTIAL",
    "principalAmount": 1.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "CANCELPREAUTH2",
    "currency" : "AUD",
    "comment" : "Partially cancelling a pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the transaction model is returned in the response body.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

Incremental pre-authorisation

Use this resource to top-up the original amount of a pre-authorisation. You must perform the incremental pre-authorisation transaction against the original successful Visa/Mastercard pre-authorisation transaction.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required PREAUTH
authorisationType string Required INCREMENTAL
principalAmount Money Required The amount to top-up the original pre-authorisation.
currency string Required One of AUD or NZD.
originalReceiptNumber string Required The receipt number of the pre-authorisation transaction to perform the top-up for.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Incremental pre-authorisation (aka Top-Up)

{
    "originalReceiptNumber": "1204957977",
    "transactionType" : "PREAUTH",
    "authorisationType" : "INCREMENTAL",
    "principalAmount": 2.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "INCREMEMTALPREAUTH1",
    "currency" : "AUD",
    "comment" : "Top-up a pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the transaction model is returned in the response body.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

Extension pre-authorisation

Use this resource to extend an original Mastercard pre-authorisation to the maximum validity period supported by the card scheme. You must perform the extension transaction against the original successful Mastercard pre-authorisation transaction.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required PREAUTH
authorisationType string Required EXTENSION
principalAmount Money Required Send 0.00.
originalReceiptNumber string Required The receipt number of the pre-authorisation transaction to perform the extension for.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Incremental pre-authorisation (aka Top-Up)

{
    "originalReceiptNumber": "1204957978",
    "transactionType" : "PREAUTH",
    "authorisationType" : "EXTENSION",
    "principalAmount": 0.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "EXTENSIONPREAUTH1",
    "currency" : "AUD",
    "comment" : "Extend a Mastercard pre-authorisation."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the transaction model is returned in the response body.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

Re-authorisation pre-authorisation

Use this resource to re-authorise an original Visa pre-authorisation that has expired after the validity period supported by the card scheme.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required PREAUTH
authorisationType string Required REAUTHORISATION
principalAmount Money Required The full amount to re-authorise.
originalReceiptNumber string Required The receipt number of the pre-authorisation transaction to perform the re-authorisation for.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

You must handle errors and avoid duplicate transactions. Do not send eci or ipAddress fields.

Incremental pre-authorisation (aka Top-Up)

{
    "originalReceiptNumber": "1204957979",
    "transactionType" : "PREAUTH",
    "authorisationType" : "REAUTHORISATION",
    "principalAmount": 10.00,
    "customerReferenceNumber": "JANESMITH",
    "paymentReferenceNumber" : "REAUTHORISATIONPREAUTH1",
    "currency" : "AUD",
    "comment" : "Re-authorise a Visa pre-authorisation after it expired."
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the transaction model is returned in the response body.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

Account verification

Use this resource to perform an account verification transaction.

See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.

Request

POST /transactions

Use your Secret API key to access this resource.

Request body

Field Format Required Description
transactionType string Required ACCOUNT_VERIFICATION
supplierBusinessCode string Required The code that uniquely identifies your business.
eci string Required. The Electronic Commerce Indicator (ECI). INTERNET, PHONE, MAIL or RECURRING.
ipAddress string Required for all single-use-token transactions and for direct account transactions with the INTERNET ECI. The IP address of the payer. This must be a public IP address. It must not be the internal IP address of your private network. Used by Fraud Guard to suspend suspicious transactions.
singleUseTokenId string Required when verifying an account using a single-use-token A token issued by QuickStream which holds card or bank account details. See Process transaction using a single-use-token.
customerId string Required when verifying an account using the customer's default account. The customerId representing a customer that has an enabled default account. See Process transaction using a tokenised account.
accountToken string Required when verifying an account using an Account Token. The accountToken representing an enabled account. See Process transaction using a tokenised account.
creditCard Credit Card Request Model Required when using card details The payment account to process a transaction. See Process transaction using account details.
customerReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Optional Up to 100 ASCII characters. Case insensitive. Your reference for this transaction.
comment string Optional A comment for the transaction.
metadata Metadata Optional. Use this field to supply extra information about the transaction.

To process a single-use-token account verification:

{
    "transactionType" : "ACCOUNT_VERIFICATION",
    "singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22",
    "supplierBusinessCode": "MYSUPPLIER",
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

To process an account verification using a customer's default tokenised account:

{
    "transactionType": "ACCOUNT_VERIFICATION",
    "customerId": "-13669603",
    "supplierBusinessCode": "MYSUPPLIER",
    "currency": "AUD",
    "eci": "PHONE"
}

To process an account verification using a specified tokenised account:

{
    "transactionType": "ACCOUNT_VERIFICATION",
    "accountToken": "QVTEST-143227292",
    "supplierBusinessCode": "MYSUPPLIER",
    "currency": "AUD",
    "eci": "PHONE"
}

To process a direct account verification:

{
    "transactionType" : "ACCOUNT_VERIFICATION",
    "creditCard": {
        "cardholderName" : "Jane Smith",
        "cardNumber" : "4242424242424242",
        "expiryDateMonth": "12",
        "expiryDateYear": "2022",
        "cvn": "123"
    },
    "supplierBusinessCode": "MYSUPPLIER",
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

Response

If successful, this method returns a Transaction Response Model in the response body.

HTTP status codes

See HTTP Status Codes for more.

Status Code Description More information
201 CREATED The request has succeeded and the transaction model is returned in the response body.
401 UNAUTHORIZED The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more.
422 UNPROCESSABLE ENTITY The request body contained invalid data. Refer to errors in the response body for more. View more.

Download CSV report

Use this resource to download a CSV report of transactions for a settlement date.

Request

GET /transactions

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters

Parameter Name Format Description
version string 1 or 2. See transaction report formats.
settlementDate date The transaction settlement date.
transactionStatus string Optional. Filter the transactions by their status. Approved or Declined.
supplierBusinessCode string Optional. Provide the unique identifier for one of your businesses to filter transactions for only that business. See Business API for more.
source string Optional. Provide a comma separated list of source codes to filter transactions by their source.
excludePreAuths boolean Optional. Send true to exclude pre-authorisations. Defaults to false.
columns string Optional. Provide a comma separated list of column headers to configure the columns returned in the report. To include metadata values in the report use metadata_yourMetadataKey. For example, provide Receipt Number,Total Amount,Payment Reference to include just the receipt number, total amount and payment reference.

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.
406 NOT ACCEPTABLE The Accept header must be text/plain or not provided.
422 UNPROCESSABLE ENTITY The request parameters contained invalid data. Refer to errors in the response body for more. View more

Transaction report formats

The following transaction report formats are available:

The reports are 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.

Handling additional columns

From time to time additional columns will be added to the format. To maintain backwards compatibility, use the columns parameter to list the columns you would like in the transaction export each time it's generated. Check the change-log for when new columns are added to the report.

CSV report version 2

Column Value Description
A Supplier Business Code The supplier business that the transaction went to.
B Supplier Business Name The name of the QuickStream Business that the transaction went to.
C Source A code indicating the source of the transaction. For example RESTAPI or BATCH.
D Transaction Type PAYMENT, REFUND, PREAUTH, CAPTURE or ACCOUNT_VERIFICATION.
E Receipt Number The unique receipt number allocated by QuickStream to the transaction.
F Payment Reference A payment level identifier for the transaction as passed to QuickStream by a product. For example, you may pass or ask your customer to enter a Payment Reference Number on your QuickWeb.
G Customer Reference Number A customer level identifier for the transaction as passed by QuickStream by a product. For example, you may pass or ask your customer to enter a Customer Reference Number on your QuickWeb.
H Principal Amount The principal amount of the transaction. This is the transaction amount before a surcharge has been applied.
I Surcharge Amount The surcharge amount of the transaction.
J Total Amount The total payment amount. This is Principal Amount, plus Surcharge Amount.
K Currency The currency code of the transaction.
L Status The status of the transaction. One of:
  • Declined - The transaction was declined by the other financial institution.
  • Approved - The transaction was approved.
  • Approved* - The transaction was sent to the other financial institution and waiting for a response.
  • Void - The transaction was cancelled before settlement.
  • Error - May indicate the transaction was not processed.
M Response Code Reason code for the status. See Response Codes.
N Response Description Reason description for the status.
O Summary Code Success indicator for the responseCode. See Response Codes.
P Settlement Date The day on which this transaction was considered to have been processed. DD MMM YYYY format.
Q Transaction Time Date and time (if known) when transaction processing was initiated. DD MMM YYYY HH:mm Z format.
R IP Address The IP address of the customer. For example, 192.168.42.184.
S Comment A comment for the transaction.
T FraudGuard Result The fraud guard result description. For facilities using Fraud Guard only.
U Original Receipt Number If a refund, the original payment. If a payment, the original PREAUTH or the automatically-retried payment.
V Soft Decline true if the transaction was a soft-decline. See Response Codes.
W Automatic Retry Date The date the transaction will be automatically retried. DD MMM YYYY format.
X Authorisation Code The authorisation code returned from the issuing bank for pre-auth transactions (at most 6 characters). Only for approved pre-auth transactions.
Y Authorisation Type INCREMENTAL, EXTENSION, REAUTHORISATION. For pre-authorisation transactions only.
Z Cancellation Type FULL or PARTIAL. For pre-authorisation cancellations only.
AA Login Name The login name of the user who made the transaction. QuickTerminal transactions only.
AB Full Name The full name of the user who made the transaction. QuickTerminal transactions only.
AC API Key The API key name. For REST API transactions.
AD Account Type The type of account used to make the transaction. One of CREDIT_CARD, BANK_ACCOUNT, NZ_BANK_ACCOUNT
AE Account Token The account token. For transactions against registered accounts.
AF Cardholder Name The cardholder name. For credit card transactions.
AG Card Number The credit card number, masked. For credit card transactions.
AH Expiry Date The credit card expiry date. For credit card transactions.
AI Card Type The card type. CREDIT, DEBIT. Note: This is only for VISA and MASTERCARD. Other card types may be added in the future.
AJ Card Scheme The credit card scheme for credit card transactions. One of:
  • VISA
  • MASTERCARD
  • AMEX
  • DINERS
  • UNIONPAY
  • UNKNOWN
  • JCB
AK Bank Account Name The payer's bank account name. For Australian bank account transactions.
AL Bank Account BSB The bank account BSB. For Australian bank account transactions.
AM Bank Account Number The bank account number. For bank account transactions.
AN NZ Bank Account Name The payer's bank account name. For New Zealand bank account transactions.
AO NZ Bank Account Bank Code The bank code. For New Zealand bank account transactions.
AP NZ Bank Account Branch Code The branch code. For New Zealand bank account transactions.
AQ NZ Bank Account Number The account number. For New Zealand bank account transactions.
AR NZ Bank Account Suffix The account suffix. For New Zealand bank account transactions.
AS Customer Id QuickStream's unique identifier for the customer.
AT Customer Number Your reference for the customer.
AU Payment Schedule Id QuickStream's unique identifier for the recurring payment. For recurring transactions.
AV Settlement Account For Australian payments, the BSB and account number of your settlement account. For New Zealand payments, the bank, branch and account numbers of your settlement account.

CSV report version 1

Column Value Description
A Community Code Your QuickStream Community Code. This code is your unique identifier for your QuickStream facility.
B Business Code The supplier business that the transaction went to.
C Business Name The name of the QuickStream Business that the transaction went to.
D Source The source of the transaction. For example QuickWeb or QuickBatch.
E Order Type The order type of the transaction. For example capture, refund or pre-auth.
F Receipt Number The unique receipt number allocated by QuickStream to the transaction.
G Customer Reference Number A customer level identifier for the transaction as passed by QuickStream by a product. For example, you may pass or ask your customer to enter a Customer Reference Number on your QuickWeb.
H Customer Number A customer level identifier for the transaction. This has a value only when you allocate a transaction to a customer record in QuickStream.
I Payment Reference A payment level identifier for the transaction as passed to QuickStream by a product. For example, you may pass or ask your customer to enter a Payment Reference Number on your QuickWeb.
J Payment Amount The total payment amount. This is Principal Amount, plus Surcharge Amount.
K Principal Amount The principal amount of the transaction. This is the transaction amount before a surcharge has been applied.
L Surcharge Amount The surcharge amount of the transaction.
M Currency The currency code of the transaction.
N Settlement Date The settlement date of the transaction.
O Transaction Date/Time The date and time QuickStream performed the transaction.
P Transaction Status The response code.
Q Summary Code The summary code for the given Transaction Status.
R Transaction Status Description The description of the given Transaction Status.
S Summary Description A short description about the Summary Code. One of:
  • Declined - The transaction was declined by the other financial institution.
  • Approved - The transaction was approved.
  • Approved* - The transaction was sent to the other financial institution and waiting for a response.
  • Void - The transaction was cancelled through QuickStream Portal or QuickGateway before settlement.
  • Error - May indicate the transaction was not processed. Use QuickStream Portal to query the transaction.
T Authorisation Code For a pre-authorisation transaction this is the authorisation code returned from the bank.
U Settlement Account Name The name of the settlement account. This is usually the Merchant ID for credit card transactions.
V Payment Instrument The payment instrument used to make the transactions.
W Account Type The type of account used to make the transaction. For example: differentiate between credit card and bank account transactions.
X Customer Account Business Code The customer account business code. Not used for all solutions.
Y Credit Card Scheme The credit card scheme for credit card transactions. One of:
  • VISA
  • MASTERCARD
  • AMEX
  • DINERS
  • UNIONPAY
  • UNKNOWN
  • JCB
Z Credit Card Number The credit card number, masked.
AA Credit Card Expiry Date The credit card expiry date.
AB Cardholder Name The cardholder name.
AC Bank Account Name The payer's bank account name. For bank account transactions.
AD Bank Account BSB The bank account BSB. For Australian bank account transactions.
AE Bank Account Number The bank account number. For bank account transactions.
AF Bank Account Bank Code The bank code. For New Zealand bank account transactions.
AG Bank Account Branch Code The branch code. For New Zealand bank account transactions.
AH Bank Account Suffix The account suffix. For New Zealand bank account transactions.
AI Login Name The login name of the user who made the transaction. QuickTerminal transactions only.
AJ Full Name The full name of the user who made the transaction. QuickTerminal transactions only.
AK Comment The comment left by the user who made the transaction. QuickTerminal transactions only.
AL Related Transaction Receipt Number If you retry, complete or refund a transaction, the original receipt number appears here.
AM Fraud Guard Result The fraud guard result description. For facilities using Fraud Guard only.
AN Ecommerce Identifier The ecommerce identifier description for the transaction. For credit card transactions.

Credit card request model

Field Format Required Description
cardholderName string Optional Name printed on the card.
cardNumber string Required Digits printed on the card.
expiryDateMonth string Required Two digit expiry month.
expiryDateYear string Required Four digit expiry year.
cvn string Required when eci = INTERNET Card Verification Number. Also known as Security Code, CVV2 and CVC2. The three or four digit security code.

Bank account request model

Field Format Required Description
accountName string Optional Name of account holder.
bsb string Required The bank-state-branch holding their account.
accountNumber string Required The account number at that branch.

Transaction response model

Field Format Description
receiptNumber string Receipt number to display to customers.
transactionType string PAYMENT, REFUND, PREAUTH, CAPTURE or ACCOUNT_VERIFICATION.
authorisationType string INCREMENTAL, EXTENSION, REAUTHORISATION. For pre-authorisation transactions only.
cancellationType string FULL or PARTIAL. For pre-authorisation cancellations only.
status string Approved, Approved*, Pending, Declined, Voided or Suspended. See transaction status.
responseCode string Reason code for the status. See Response Codes for more.
responseDescription string Reason description for the status.
summaryCode string Success indicator for the responseCode. See Response Codes for more.
fraudGuardResult string The result of Fraud Guard processing. null when transaction is not processed using Fraud Guard.
originalReceiptNumber string If a refund, the original payment. If a payment, the original PREAUTH or the automatically-retried payment.
customerReferenceNumber string Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history.
paymentReferenceNumber string Your reference for this transaction.
comment string A comment for the transaction.
metadata Metadata Extra information about the transaction. See Take Payment.
source string A code indicating the source of the transaction. For example, RESTAPI.
ipAddress string The IP address of the customer. For example, 192.168.42.184.
settlementDate date The day on which this transaction was considered to have been processed. See Transaction Settlement for more.
transactionTime date-time Date and time (if known) when transaction processing was initiated.
voidable boolean If true, this transaction may be voided. See Void payment.
refundable boolean If true, this transaction may be refunded. See Refund payment.
principalAmount Money Amount before any surcharge added.
surchargeAmount Money Amount of surcharge. See surcharges.
totalAmount Money Total amount of transaction. Principal amount plus surcharge.
merchantAccount Merchant Account For credit card payments, your merchant facility.
directEntryAccount Direct Entry Account For Australian bank account payments, your direct entry settlement account.
creditCard Credit Card For credit card payments, your customer's credit card.
bankAccount Bank Account For Australian bank account payments, your customer's bank account.
merchantName string This field is only relevant for credit card payments for Aggregators. The sub-merchant name.
merchantStreetAddress string This field is only relevant for credit card payments for Aggregators. The street address of the sub-merchant's trading address.
merchantLocation string This field is only relevant for credit card payments for Aggregators. The city or suburb of the sub-merchant's trading address.
merchantState string This field is only relevant for credit card payments for Aggregators.The state of the sub-merchant's trading address.
merchantCountry string This field is only relevant for credit card payments for Aggregators. Always AU.
merchantPostCode string This field is only relevant for credit card payments for Aggregators. The postal code of the sub-merchant's trading address.
subMerchantId string This field is only relevant for credit card payments for Aggregators. A unique identifier for your sub-merchant. The aggregator allocates the sub-merchant identifier. Westpac does not allocate this value.
authorisationCode string The authorisation code returned from the issuing bank for pre-auth transactions (at most 6 characters). Only for approved pre-auth transactions.
authorisationTraceId string Returned by Visa and Mastercard to identify the lifecycle of a pre-auth or purchase (at most 15 characters). In most cases you can ignore this field.
links Array of Links Links to related resources/documentation.

Example credit card transaction response

{
  "receiptNumber": "1234567890",
  "transactionType": "PAYMENT",
  "status": "Approved",
  "responseCode": "08",
  "responseDescription": "Honour with identification",
  "summaryCode": "0",
  "fraudGuardResult": null,
  "customerReferenceNumber": "CUSTOMER1",
  "paymentReferenceNumber": "INVOICE1",
  "comment": "Credit card payment for Jane Smith.",
  "source": "RESTAPI",
  "settlementDate": "2017-01-01",
  "transactionTime": "2017-01-01T10:26:36+1000",
  "refundable": false,
  "voidable": true,
  "principalAmount": {
    "currency": "AUD",
    "amount": 10.00,
    "displayAmount": "$10.00"
  },
  "surchargeAmount": {
    "currency": "AUD",
    "amount": 1.00,
    "displayAmount": "$1.00"
  },
  "totalAmount": {
    "currency": "AUD",
    "amount": 11.00,
    "displayAmount": "$11.00"
  },
  "merchantAccount": {
    "merchantId": "12345678",
    "merchantName": "My Westpac Account",
    "settlementBsb": "032-002",
    "settlementAccountNumber": "1234576",
    "displayName": "Your Company 032-002 123465 (12345678)",
    "acquiringInstitution": "WBC",
    "currency": "AUD"
  },  
  "creditCard": {
    "accountType": "CREDIT_CARD",
    "accountToken": "MYCOMPANY-123456789",
    "defaultAccount": true,
    "cardNumber": "424242...242",
    "expiryDateMonth": "01",
    "expiryDateYear": "17",
    "cardScheme": "VISA",
    "cardholderName": "Jane Smith",
    "maskedCardNumber4Digits": "424242...4242"
  },
  "metadata": {
    "extraInformation": "123456789",
    "moreInformation": "testData"
  },
  "links": []
}

Transaction status

Status Meaning
Approved A successful transaction.
Approved* A successful transaction during a period when it may be declined or dishonoured.
Pending Currently processing.
Declined An unsuccessful transaction. See responseCode and responseDescription for more.
Voided Originally Approved, but then cancelled prior to settlement. Does not appear on your customer's statement or form part of your settlement total.
Suspended A payment suspended by Fraud Guard before processing.

See Response Codes for more.

Metadata model

Metadata may be used to store extra information about a transaction. It is represented as an object with up to 20 key/value string pairs. Data in a request body not conforming to the following format will result in a 422 Unprocessable Entity response.

Field Format Description
key string Maximum 40 ASCII characters.
value string Optional. Maximum 255 ASCII characters.

Example metadata object

{
    "metadata": {
      "serialCode": "18777-231-2A",
      "sequenceNumber": "005",
      "customerPackage": "Basic (BAPK)"
    }
}

Credit card model

Field Format Description
accountType string CREDIT_CARD
accountToken string The account token. See Register Account for more.
defaultAccount boolean If true, this account will be used for the owning customer where an account token is not specified. This includes taking payments by customerId and creating recurring payments without an accountToken.
cardNumber string Masked credit card number.
expiryDateMonth string Two digit expiry month.
expiryDateYear string Two digit expiry year.
cardScheme string The card scheme. VISA, MASTERCARD, AMEX, DINERS, JCB, or UNIONPAY.
cardType string The card type. CREDIT, DEBIT. Note: This is only for VISA and MASTERCARD. Other card types may be added in the future.
cardholderName string The name printed on the card.
maskedCardNumber4Digits string Masked credit card number displaying last 4 digits.
links Array of Links Links to related documents and resources.

Example credit card response


{
    "accountType": "CREDIT_CARD",
    "accountToken": "MYCOMPANY-123456789",
    "defaultAccount": true,
    "cardNumber": "424242...242",
    "expiryDateMonth": "01",
    "expiryDateYear": "17",
    "cardScheme": "VISA",
    "cardType": "CREDIT",
    "cardholderName": "Jane Smith",
    "maskedCardNumber4Digits": "424242...4242",
    "links": []
}

Bank account model

Field Format Description
accountType string DIRECT_DEBIT
accountToken string The account token. See Register Account for more.
defaultAccount boolean If true, this account will be used for the owning customer where an account token is not specified. This includes taking payments by customerId and creating recurring payments without an accountToken.
accountName string Name of account holder.
displayName string The bank account display name.
currency string AUD
bsb string The bank-state-branch holding their account.
accountNumber string The account number at that branch.
links Array of Links Links to related documents and resources.

Example bank account response

{
    "accountType": "DIRECT_DEBIT",
    "accountToken": "MYCOMPANY-123456780",
    "defaultAccount": true,
    "accountName": "Jane's Bank Account",
    "displayName": "Jane's Bank Account",
    "currency": "AUD",
    "bsb": "032-000",
    "accountNumber": "123465",
    "links": []
}

Merchant account model

Field Format Description
merchantId string Uniquely identifies a merchant facility. Issued by us.
merchantName string
settlementBsb string The BSB of your settlement bank account. Australian Westpac merchant facilities only.
settlementAccountNumber string The account number of your settlement bank account. Australian Westpac merchant facilities only.
settlementSurchargeBsb string The BSB of your surcharge settlement bank account. Only present if a separate surcharge account is utilised. Australian Westpac merchant facilities only.
settlementSurchargeAccountNumber string The account number of your surcharge settlement bank account. Only present if a separate surcharge account is utilised. Australian Westpac merchant facilities only.
displayName string A customer-friendly display name.
acquiringInstitution string A code describing the aquiring financial institution for this merchant facility. Usually WBC.
currency string The currency accepted by this merchant facility.

Example merchant accounts response

{ 
   "merchantId":"12345678",
   "merchantName":"My Westpac Account",
   "settlementBsb":"032-002",
   "settlementAccountNumber":"123465",
   "settlementSurchargeBsb": "032-002",
   "settlementSurchargeAccountNumber": "1234576",
   "displayName":"Your Company 032-002 123465 (12345678)",
   "acquiringInstitution": "WBC",
   "currency": "AUD"
}

Direct entry account model

Field Format Description
displayName string A customer-friendly display name.
currency string The currency of the account. For example, AUD.
directEntryUserId string A unique direct entry user identification number, issued by us.
directEntryUserName string The name associated with the direct entry user Id. Australian Westpac accounts only.
accountName string Name used to open your bank account.
settlementBsb string The BSB of your settlement bank account.
settlementAccountNumber string The account number of your settlement bank account.
remitterName string Trading Name of your business. This appears on your customer's bank statement.

Example Australian Direct Entry Accounts response

{
  "accountName": "My Bank Account",
  "displayName": "My Bank Account 032-002 123465 (411111)",
  "currency": "AUD",
  "directEntryUserId": "411111",
  "directEntryUserName": "My Company",
  "settlementBsb": "032-002",
  "settlementAccountNumber": "123465"
}

To change the remitterName:

  1. Sign into QuickStream Portal.
  2. Click on Administration -> Business Settings.
  3. Search for your business.
  4. Click on View Settlement Accounts linked to this business.

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.