Skip to main content

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, representing the source of the transaction request. When using an ECI of INTERNET a CVN should be provided.

ECI Payment Type
INTERNET Internet Transaction for Payment
PHONE Interactive Voice Recording or Call Centre Transaction
MAIL Mail or Telephone Order Transaction
RECURRING Recurring Transaction
INSTALMENT Instalment Transaction
5 Digital wallet transactions
6 Digital wallet transactions
7 Digital wallet transactions

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.

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.

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",
    "cardType": "CREDIT",
    "maskedCardNumber4Digits": "424242...4242"
  },
  "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

List up to your 20 most recent transactions on the current settlement date across your businesses. Provide supplierBusinessCode to list filter those 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 by New Zealand bank account

Use this resource to list transactions taken using an New Zealand bank account. Provide the Bank Code and Branch Code and Account Number of the payment bank account to search.

Request

GET /transactions/for-nz-bank-account?bankCode={number}&branchCode={number}&accountNumber={number}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters
Parameter Name Format Description
bankCode string The Bank Code of the payment bank account. Bank Codes are 2 digits.
branchCode string The Branch Code of the payment bank account. Branch Codes are 4 digits.
accountNumber string The Account Number of the payment bank account. Exclude the account suffix. Account numbers are 7 to 8 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 bankCode, branchCode 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 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 returned transactions

Use this resource to list Australian bank account transactions that have been returned on a certain date. A returned transaction is one that has been declined by the customer's bank. See Bank account transaction settlement for more information.

Request

GET /transactions/returns?date={YYYY-MM-DD}&supplierBusinessCode={code}

Use your Secret API key to access this resource.

Path parameters

None.

Query parameters
Parameter Name Format Description
date date The date the transactions were returned.
supplierBusinessCode string Optional. Provide the unique identifier for one of your businesses to list returned transactions for only that business. See Business API for more.
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 date query parameter may be incorrect. 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.

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, RECURRING, INSTALMENT, 5, 6 or 7.
cryptogram string Required when walletProvider is provided in the creditCard For wallet transactions, the cryptogram returned from the wallet provider's API (if applicable).
ipAddress string Required for single-use-token transactions and direct payments with the INTERNET ECI. This is the public Internet IP address of your customer. Only provide this field when processing a payment that has been actively initiated by customer over the Internet to your system. Do not provide this field when processing batches of payments via the API. Never provide your own servers or websites IP address in this field. 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.
nzBankAccount New Zealand Bank Account Request Model Required when using New Zealand 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.
storedCredentialData Stored Credential Data Request Model Optional Parameters that merchants must send when using stored credentials for Visa and Mastercard cards.
agreementId string Required when your merchant is configured for Mastercard Payment Gateway Services. Up to 90 ASCII characters. A unique identifier generated by the merchant, to identify a specific agreement established with the cardholder to process future merchant-initiated transaction (MIT) payments.
Send a value in this field when eci is RECURRING or INSTALMENT, and when storedCredentialData.usage is provided.
If you do not provide a value, QuickStream will generate and send a dummy identifier.
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, RECURRING or INSTALMENT.
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.
storedCredentialData Stored Credential Data Request Model Optional Parameters that merchants must send when using stored credentials for Visa and Mastercard cards.
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.
storedCredentialData Stored Credential Data Request Model Optional Parameters that merchants must send when using stored credentials for Visa and Mastercard cards.
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, RECURRING or INSTALMENT.
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.
storedCredentialData Stored Credential Data Request Model Optional Parameters that merchants must send when using stored credentials for Visa and Mastercard cards.
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/csv

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 202 when the report is generated. A subsequent request resulting in a 200 HTTP status code will download the 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.

Reefer to the CSV transaction report file format.

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.
walletProvider string Optional Specifies the wallet provider from which the card details were obtained, if applicable. Supported values: APPLE_PAY

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.

New Zealand bank account request model

Field Format Required Description
nzAccountName string Optional Name of account holder.
nzBankCode string Required The bank code holding their account.
nzBranchCode string Required The branch of the bank holding their account.
nzAccountNumber string Required The account number at that branch.
nzAccountSuffix string Required The account suffix.

Stored credential data request model

Field Format Required Description
entryMode string Optional Identifies how the card number was obtained:
  • MANUAL - The card number was manually entered into the system by the cardholder or the merchant.
  • STORED_CREDENTIAL - The card number is stored by the merchant or gateway to process future purchases for a cardholder.
Defaults to STORED_CREDENTIAL for payments using tokenised accounts, otherwise MANUAL.
usage string Optional Identifies the purpose of a stored card number.
  • INSTALMENT - A transaction in a fixed series of transactions for a single purchase of goods or services.
  • RECURRING - A transaction in a series of transactions that are processed at fixed, regular intervals (not to exceed one year between transactions) for purchase of goods or services provided at regular intervals.
  • UNSCHEDULED_CIT - A cardholder-initiated unscheduled transaction (which does not occur on a scheduled or regularly occurring transaction date).
  • UNSCHEDULED_MIT - A merchant-initiated unscheduled transaction (which does not occur on a scheduled or regularly occurring transaction date). The transaction is initiated by the merchant without active participation of the cardholder (e.g. account top-up).

Defaults to RECURRING when eci=RECURRING or INSTALMENT when eci=INSTALMENT. Otherwise this field defaults to UNSCHEDULED_MIT.

Only applicable to Take payment, Pre-authorisation, Capture pre-authorisation, and Account verification.
networkTransactionId string Optional Available for Visa only. Used to identify the previous transaction for the cardholder when using a stored credential.

When using Scheme Tokenisation, this field defaults to the networkTransactionId returned in an Account Verification transaction that the system performs when storing a card account (Scheme Tokenisation must be activated on your facility).

Stored credential transactions

A stored credential is information that is stored by a merchant or its agent to process future purchases for a cardholder. This generally consists of the card number, expiry date and cardholder name. A credential is not considered a stored credential when the merchant or its agent stores the credential to complete a single transaction. The parameters that merchants must send when using stored credentials for Visa and Mastercard cards are below.

There are different data requirements for the initial transaction vs subsequent transactions. The table below summarises the differences:

Field Initial transaction Subsequent transaction
entryMode MANUAL STORED_CREDENTIAL
usage
(Visa only)
Identify the intended usage of the stored card number using INSTALMENT, RECURRING, UNSCHEDULED_CIT or UNSCHEDULED_MIT. Identify the purpose of this transaction using one of INSTALMENT, RECURRING, UNSCHEDULED_CIT or UNSCHEDULED_MIT.
networkTransactionId
(Visa only)
Not used. You must do the following:
  1. Store the value from the networkTransactionId parameter from the response to the initial transaction (if present).
  2. Provide this value (if present) in the networkTransactionId parameter in subsequent transaction requests.

QuickStream uses default values for these when not provided. See the Stored credential data request model.

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. See Response Codes
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.
nzDirectEntryAccount New Zealand Direct Entry Account For New Zealand 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.
nzBankAccount New Zealand Bank Account For New Zealand 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 Deprecated Use networkTransactionId.
networkTransactionId 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",
    "cardType": "CREDIT",
    "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 displaying the first 6 and last 3 digits.
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 the first 6 and last 4 digits.
panType string
  • FPAN (default) - the card number from a physical card. Also known as "Funding PAN".
  • DPAN - a digitised card number from a wallet provider or scheme tokenisation service. Also known as "Digital PAN".
walletProvider string Specifies the wallet provider from which the card details were obtained, if applicable. APPLE_PAY, GOOGLE_PAY
customerId string QuickStream's unique identifier for the customer. This customer is created automatically when using Register account without customer details or by instruction from your server when using Create customer and then Register customer account. See Get Customer for more.
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",
    "panType": "FPAN",
    "customerId" : 123456789,
    "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.
customerId string QuickStream's unique identifier for the customer. This customer is created automatically when using Register account without customer details or by instruction from your server when using Create customer and then Register customer account. See Get Customer for more.
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",
    "customerId" : 123456789,
    "links": []
}

New Zealand bank account model

Field Format Description
accountType string DIRECT_DEBIT_NZ
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.
nzAccountName string Name of account holder.
displayName string The bank account display name.
currency string NZD
nzBankCode string The bank holding their account.
nzBranchCode string The branch holding their account.
nzAccountNumber string The account number at that branch.
nzAccountSuffix string The type of account.
customerId string QuickStream's unique identifier for the customer. This customer is created automatically when using Register account without customer details or by instruction from your server when using Create customer and then Register customer account. See Get Customer for more.
links Array of Links Links to related documents and resources.

Example New Zealand bank account response

{
    "accountType": "DIRECT_DEBIT_NZ",
    "accountToken": "MYCOMPANY-123456780",
    "defaultAccount": true,
    "nzAccountName": "Jane's Bank Account",
    "displayName": "Jane's Bank Account",
    "currency": "NZD",
    "nzBankCode": "01",
    "nzBranchCode": "0001",
    "nzAccountNumber": "0000001",
    "nzAccountSuffix": "00",
    "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.

New Zealand direct entry account model

Field Format Description
displayName string A customer-friendly display name.
currency string The currency of the account. For example, NZD.
debitUserId string A unique direct entry user identification number, issued by us.
nzAccountName string Name used to open your bank account.
nzBankCode string The bank code of your settlement bank account.
nzBranchCode string The branch code of your settlement bank account.
nzAccountNumber string The account number of your settlement bank account.
nzAccountSuffix string The account number suffix of your settlement bank account.

Example New Zealand direct entry account response

{
  "nzAccountName": "My Bank Account",
  "displayName": "My Bank Account 010001-0000002-00 (NZ Account)",
  "currency": "NZD",
  "debitUserId": null,
  "nzBankCode": "01",
  "nzBranchCode": "0001",
  "nzAccountNumber": "0000002",
  "nzAccountSuffix": "00"
}

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.