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.

Get

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

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, Payment Reference Number or PayTo End-To-End ID.

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, Payment Reference Number or PayTo End-To-End ID.
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, using a single-use-token, a tokenised card or bank account, or a PayTo Agreement Token.

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": "MYBUSINESS",
    "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": "MYBUSINESS",
    "principalAmount": 100.00,
    "currency": "AUD",
    "eci": "PHONE"
}

To take a payment using a specified tokenised account:

{
    "transactionType": "PAYMENT",
    "accountToken": "QVTEST-143227292",
    "supplierBusinessCode": "MYBUSINESS",
    "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": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD",
    "eci": "INTERNET",
    "ipAddress" : "192.168.1.1"
}

To take a direct bank account payment:

{
    "transactionType" : "PAYMENT",
    "bankAccount": {
        "accountName": "Jane Smith",
        "bsb": "032-002",
        "accountNumber": "123465"
    },
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD"
}

To take a PayTo payment:

{
    "transactionType" : "PAYMENT",
    "payToData": {
        "endToEndId": "INV-123456790",
        "remittanceInformation1": "PAYMENT TO CUSTOMERA",
        "finalPayment": false,
        "agreementToken": "CUST123456789"
    },
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD"
}

To create an e-Commerce or Once-off PayTo agreement and take a payment together:

{
    "transactionType" : "PAYMENT",
    "payToData": {
        "endToEndId": "INV-123456790",
        "remittanceInformation1": "ECOM PAYMENT TO CUSTOMERA",
        "payToAgreement" : {
            "supplierBusinessCode": "MYBUSINESS",
            "paymentDetails": {
                "purpose": "RETL",
                "description": "Your license renewal payment."
            },
            "payerDetails": {
                "payerType": "PERS",
                "payerId": "PS19400650001",
                "payerName": "FIRSTNAME SURNAME",
                "payerReference": "PY19000890013",
                "payIdType": "EMAL",
                "payId": "FIRSTNAME.SURNAME@MYCUSTOMER.COM.AU"
            }
        }
    },
    "supplierBusinessCode": "MYBUSINESS",
    "principalAmount": 10.00,
    "currency" : "AUD"
}
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.
payToData PayTo Data Request Model Required when taking a payment for a PayTo Agreement. Use this field to supply information about the PayTo Agreement that this payment is for.
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.
mpgsData MPGS Data Request Model Required when your merchant is configured for Mastercard Payment Gateway Services. Send a value 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.
threeDS2 boolean Optional true if you have implemented EMV 3D Secure and are processing a card transaction using a single-use-token.
metadata Metadata Optional Use this field to supply extra information about the transaction.
debtRepayment boolean Optional This should be provided if the transaction is being used to repay a debt.

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, and you may only refund the full amount for PayTo payments.

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.
creditCard CreditCard Optional. If the original transaction was performed against a now expired Credit Card, use this field to provide the updated expiry date to process the refund.

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-authorisations

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 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.
threeDS2 boolean Optional true if you have implemented EMV 3D Secure and are processing this transaction using a single-use-token.
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
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.
threeDS2 boolean Optional true if you have implemented EMV 3D Secure and are processing this transaction using a single-use-token.
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.

Refer to the CSV transaction report file format.

Request models

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

Credit card refund request model

Field Format Required Description
expiryDateMonth string Required Two digit expiry month.
expiryDateYear string Required Four digit expiry year.

PayTo data request model

Field Format Required Description
agreementToken string Required when payToAgreement is not provided. The agreementToken representing an active PayTo Agreement this payment is taken against.
payToAgreement PayTo Agreement Request Model Required when agreementToken is not provided. The payToAgreement representing a new e-Commerce or Once-off PayTo agreement to be created. When the payer approves the PayTo agreement, the payment is taken automatically by QuickStream.
To create an e-Commerce or Once-off PayTo agreement you must provide specific fields in the payToAgreement object.

The following fields have requirements when set:
  • payToData.finalPayment=true (defaults to true when not provided.)
  • payToAgreement.respondByTimeMinutes must be <= 15.

The following fields must match the transaction request:
  • payToAgreement.supplierBusinessCode must be the same value as supplierBusinessCode.

Do not provide the following fields:
  • payToAgreement.paymentDetails.startDate (defaults to the current calendar date.)
  • payToAgreement.paymentDetails.endDate (defaults to the next calendar date.)
  • payToAgreement.paymentDetails.automaticRenewal (defaults to false.)
  • payToAgreement.paymentTerms.frequency (defaults to ADHO.)
  • payToAgreement.paymentTerms.numberOfPayments (defaults to 1.)
  • payToAgreement.paymentTerms.agreementType (defaults to FIXE.)
  • payToAgreement.paymentTerms.paymentAmount (defaults to principalAmount.)
  • payToAgreement.paymentTerms.pointInTime
  • payToAgreement.paymentTerms.firstPaymentAmount
  • payToAgreement.paymentTerms.lastPaymentAmount
  • payToAgreement.paymentTerms.maximumPaymentAmount

Note: This endpoint will create the PayTo Agreement under a new Customer with a generated customerNumber. You will still receive Webhook Notifications.
endToEndId string Optional A unique identifier to unambiguously identify the transaction. This identifier would typically be used by both the Payee and Payer to reconcile the payment. Defaults to receiptNumber when not provided. Up to 35 characters.
remittanceInformation1 string Optional Information supplied to enable the matching/reconciliation of a transaction with the items that the payment is intended to settle, such as commercial invoices in an accounts receivable system, in an unstructured form.

When provided, the first 35 characters of this field will also form part of the payment narrative on the Payee's bank statement.

Up to 140 characters.
remittanceInformation1 string Optional Up to 140 characters.
finalPayment boolean Optional Set to true when this is the final payment for the PayTo Agreement. If this payment is successful, the PayTo Agreement will be automatically canclled.

This is the same process calling the Status Amendment endpoint with a statusCode of CANCELLED.

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.

MPGS data request model

Field Format Required Description
agreementId string Required 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.

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)"
    }
}

Response models

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.
supplierBusinessCode string The code that uniquely identifies your business.
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 Only relevant for credit card payments for Aggregators. The sub-merchant name.
merchantStreetAddress string Only relevant for credit card payments for Aggregators. The street address of the sub-merchant's trading address.
merchantLocation string Only relevant for credit card payments for Aggregators. The city or suburb of the sub-merchant's trading address.
merchantState string Only relevant for credit card payments for Aggregators.The state of the sub-merchant's trading address.
merchantCountry string Only relevant for credit card payments for Aggregators. Always AU.
merchantPostCode string Only relevant for credit card payments for Aggregators. The postal code of the sub-merchant's trading address.
subMerchantId string 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.
debtRepayment boolean Whether this transaction was used to repay a debt. In most cases you can ignore this field.
merchantAdviceCode string Additional information from the scheme about why a transaction was approved or declined.
payToData PayTo Data For PayTo transactions, data provided about the PayTo transaction.
payToPayerAccount PayTo Payer Account For PayTo transactions, your Payer's account details.
payToPayeeAccount PayTo Payee Account For PayTo transactions, your Payee account details.

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,
  "supplierBusinessCode": "MYBUSINESS",
  "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": [],
  "debtRepayment": false
}
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.

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.
For scheme tokenised accounts, this would display the last 3 digits in the following format: xxxxxx...242.
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.
For scheme tokenised accounts, this would display the last 4 digits in the following format: xxxxxx...4242.
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-in to 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"
}

PayTo data model

Field Format Description
agreementToken string The PayTo Agreement that this transaction was performed against.
endToEndId string A unique identifier to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain.
priority string The priority of the instruction.
remittanceInformation1 string Information supplied to enable the matching/reconciliation of a transaction with the items that the payment is intended to settle, such as commercial invoices in an accounts receivable system, in an unstructured form.
remittanceInformation2 string

PayTo Payer account model

Field Format Description
accountType string Always PAYTO
customerId string QuickStream's unique identifier for the customer.

This customer is created automatically when using the Create PayTo Agreement endpoint, or from your server when using Create customer and then Create PayTo Agreement For Customer. See Get Customer for more.
payerType string The type of Payer.
payerId string Your unique customer identifier for this Payer.
payerName string The name of the Payer.
ultimatePayerName string The trading name of an organisation or the name of the receiver of goods or services.
bsb string The masked BSB number fo the Payer's payment account.
maskedAccountNumber string The masked Account number for the Payer's payment account.
payIdType string The PayID type.
payId string The masked PayID for the Payer's payment account.

PayTo Payee account model

Field Format Description
displayName string A customer-friendly display name.
currency string Always AUD

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:

Process transaction using PayTo Agreement Token

To process a transaction using a PayTo Agreement Token, you will need a customer with a Payto Agreement.

The payment can be made by including the agreementToken representing an active PayTo Agreement.

You may also provide additional information in the paytoData request object.

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 transactions
PHONE Interactive voice recording or call centre transactions
MAIL Mail or telephone order transactions
RECURRING Recurring Transactions, or Customer-Initiated transactions where the Credentials are stored as an Account Token.
INSTALMENT Instalment transactions and transactions where the credentials are stored as an Account Token for the purpose of taking instalment transactions.
5 Digital wallet and 3D-Secure transactions
6 Digital wallet and 3D-Secure transactions
7 Digital wallet and 3D-Secure 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.

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.

Westpac Privacy Statement

Privacy Statement (for individuals whose personal information may be collected - in this clause referred to as "you"). All personal information we collect about you is collected, used and disclosed by us in accordance with our Privacy Statement which is available at Privacy Statement or by calling us through your relationship manager or Westpac representative. Our Privacy Statement also provides information about how you can access and correct your personal information and make a complaint. You do not have to provide us with any personal information but, if you don't, we may not be able to process an application or a request for a product or service.