Transactions API
Transactions API
Transactions include payments, refunds and preauths. Using this API you can:
- process payments using a card or bank account.
- perform pre-auth transactions using a card account.
- void a transaction to cancel it prior to settlement.
- refund a card or bank account payment.
- search and get details of transactions, regardless of how they were originally processed
- download CSV transaction reports for a settlement date.
Besides this API, QuickStream has other ways to take payments.
Processing transactions
There are several ways to specify the account used to perform transactions:
- Process transaction using a single-use-token - for accepting one-time transactions through a webpage or application. The easiest way to make these requests is to use Trusted Frame or Custom Form.
- Process transaction using tokenised account - for accepting transactions from an account that has been registered for a customer previously.
- Process transaction using account details - for accepting one-time transactions through your own server. Using this type of request will mean credit card data may be passing through your system. As a result, there may be extra PCI DSS considerations for your environment.
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:
- send a unique
Idempotency-Key
. - if you receive a network error, resend the request with the same
Idempotency-Key
. - if you receive 500 Internal Server Error, contact Technical Support.
- if you receive 503 Service Unavailable, the payment has not been processed. Wait 20 seconds and resend the request with a new idempotency key. Contact Technical Support if you continue to experience problems.
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:
accountToken
may be a new token generated by this API. It may also be an existing token generated by QuickVault. For example, you may already use account tokens to take payments via a batch file.
Process transaction using account details
To process a transaction using account details directly in the request, include a Credit Card Request Model or Bank Account Request Model in the Transaction Request Model creditCard
or bankAccount
fields.
You can use account details to process:
Electronic Commerce Indicator
The Electronic Commerce Indicator (ECI) is used by acquirers / issuers to determine the type of transaction being processed. The ECI value represents the source of the transaction request. The ECI will also determine whether you need to capture the CVN. An ECI can be INTERNET
, PHONE
, MAIL
, RECURRING
, INSTALMENT
.
ECI | Payment Type | Is a CVN Required? |
---|---|---|
INTERNET |
Internet Transaction for Payment | Yes |
PHONE |
Interactive Voice Recording or Call Centre Transaction | No |
MAIL |
Mail or Telephone Order Transaction | No |
RECURRING |
Recurring Transaction | No |
INSTALMENT |
Instalment Transaction | No |
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 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:
|
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:
|
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:
- List refunds of a transaction.
- List retries of a transaction.
- Void a transaction to cancel it when
voidable
istrue
. - Partially or fully refund a transaction when
refundable
istrue
.
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
Get a list of your 20 most recent transactions across your businesses. Provide supplierBusinessCode
to list the 20 most recent transactions for that business.
Request
GET /transactions?supplierBusinessCode={code}
Use your Secret API key to access this resource.
Path parameters
None.
Query parameters
Parameter Name | Format | Description |
---|---|---|
supplierBusinessCode |
string |
Optional. Provide the unique identifier for one of your businesses to list the 20 most recent transactions for only that business. See Business API for more. |
Request body
None.
Response
The most recent transaction is first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
422 |
UNPROCESSABLE ENTITY | The supplierBusinessCode query parameter may be incorrect. View more. |
List by reference number
List transactions by reference number. Use this resource to find transactions by Receipt, Customer Reference or Payment Reference Number.
Request
GET /transactions/for-reference-number?referenceNumber={string}
Use your Secret API key to access this resource.
Path parameters
None.
Query parameters
Parameter Name | Format | Description |
---|---|---|
referenceNumber |
string |
Get a list of transactions for the provided Receipt, Customer Reference or Payment Reference Number. |
Request body
None.
Response
This is a paginated resource. The most recent transaction is first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more. |
422 |
UNPROCESSABLE ENTITY | referenceNumber contains non-ASCII characters or is empty. View more. |
List by settlement date
Use this resource to list transactions by settlement date. Settlement is the process of paying you for transactions which have been processed. The Settlement Date is the day on which a transaction was considered to have been processed.
See Transaction Settlement for more.
Request
GET /transactions/for-settlement-date?settlementDate={date}
Use your Secret API key to access this resource.
Path parameters
None.
Query parameters
Parameter Name | Format | Description |
---|---|---|
settlementDate |
date |
The transaction settlement date. |
Request body
None.
Response
This is a paginated resource. The most recent transaction is first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more. |
422 |
UNPROCESSABLE ENTITY | settlementDate is not in the valid date format or is empty. View more. |
List by account token
Use this resource to list transactions taken for an Account Token.
Credit card and bank accounts are registered for customers. The unique identifier for a customer's credit card or bank account is a called an account token. Use an account token to take payments for those accounts. Use the Customers API to manage their account tokens.
Request
GET /transactions/for-account-token?accountToken={string}
Use your Secret API key to access this resource.
Path parameters
None.
Query parameters
Parameter Name | Format | Description |
---|---|---|
accountToken |
string |
The unique identifier for a customer's credit card or bank account. See Customers API for more. |
Request body
None.
Response
This is a paginated resource. The most recent transaction is first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The requested resource was not found. Check that the path is spelled correctly and refer to the response body for further details. View more. |
422 |
UNPROCESSABLE ENTITY | accountToken contains non-ASCII characters or is empty. View more |
List by credit card
Use this resource to list transactions taken using a credit card. Provide the first 6 and last 3 digits of the credit card number to search.
Request
GET /transactions/for-credit-card?firstSix={number}&lastThree={number}
Use your Secret API key to access this resource.
Path parameters
None.
Query parameters
Parameter Name | Format | Description |
---|---|---|
firstSix |
string |
The first six digits of the credit card number. |
lastThree |
string |
The last three digits of the credit card number. |
Request body
None.
Response
This is a paginated resource. The most recent transaction is first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The requested resource was not found. Check that the path is spelled correctly and refer to the response body for further details. View more. |
422 |
UNPROCESSABLE ENTITY | firstSix or lastThree contain non-numeric characters, is empty or has an invalid length. View more |
List by bank account
Use this resource to list transactions taken using an Australian bank account. Provide the BSB and Account Number of the payment bank account to search.
Request
GET /transactions/for-bank-account?bsb={string}&accountNumber={number}
Use your Secret API key to access this resource.
Path parameters
None.
Query parameters
Parameter Name | Format | Description |
---|---|---|
bsb |
string |
The BSB of the payment bank account. E.g. 032-002. |
accountNumber |
string |
The account number of the payment bank account. Account numbers are 6 to 9 digits. |
Request body
None.
Response
This is a paginated resource. Transactions are sorted with the most recent transaction first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The requested resource was not found. Check that the path is spelled correctly and refer to the response body for further details. View more. |
422 |
UNPROCESSABLE ENTITY | bsb or accountNumber contain non-ASCII characters, is empty or has an invalid length. View more |
List 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 suspension rules you have configured in QuickStream. Fraud Guard sets the transaction response code to 34 - Suspected Fraud
.
Sign in to QuickStream to complete or cancel a transaction.
Request
GET /transactions/suspended?supplierBusinessCode={code}&month={YYYY-MM}
Use your Secret API key to access this resource.
Path parameters
None.
Query parameters
Parameter Name | Format | Description |
---|---|---|
supplierBusinessCode |
string |
Optional. Provide the unique identifier for one of your businesses to list suspended transactions for only that business. See Business API for more. |
month |
date-month |
Provide the year and month YYYY-MM to list suspended transactions for only that period. You can search up to 6 months in the past. |
Request body
None.
Response
This is a paginated resource. Transactions are sorted with the most recent transaction first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The supplierBusinessCode or month query parameter may be incorrect. View more. |
List refunds of a transaction
Use this resource to list refunds of a transaction. A transaction may be refunded for the full amount, or a partial amount. The transactions returned by this resource make up the total amount of this transaction refunded to your customer.
Request
GET /transactions/{receiptNumber}/refunds
Use your Secret API key to access this resource.
Path parameters
Parameter Name | Format | Description |
---|---|---|
receiptNumber |
string |
List refunds the transaction with the receipt number provided. |
Request body
None.
Response
This is a paginated resource. The most recent refund transaction is first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more. |
List retries of a transaction
Use this resource to list the retries of a failed transaction.
Transactions that have been soft-declined by the account holder's financial institution can be retried and may be successful in the future. A failed transaction may be retried manually or automatically by configuring a schedule.
When a transaction is retried, a new transaction is attempted. This resource lists the retry attempts of a transaction.
Request
GET /transactions/{receiptNumber}/retries
Use your Secret API key to access this resource.
Path parameters
Parameter Name | Format | Description |
---|---|---|
receiptNumber |
string |
List retries of the transaction with the receipt number provided. |
Request body
None.
Response
This is a paginated resource. The most recent retry transaction is first.
Field | Format | Description |
---|---|---|
links |
Array of Links | Links to related documents and resources. |
data |
Array of Transaction Response Model | A paginated list of transactions. |
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
200 |
OK | The request has succeeded. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
404 |
NOT FOUND | The requested resource was not found. Check that the path is spelled correctly. Refer to the response body for further details. View more. |
List 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 or INSTALMENT . |
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. |
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. |
comment |
string |
Optional | A comment for the transaction. |
metadata |
Metadata | Optional. | Use this field to supply extra information about the transaction. |
You must handle errors and avoid duplicate transactions.
Fraud Guard is initiated on pre-authorisation. Pre-authorisations available for capture have already passed fraud guard validation.
To process a single-use-token pre-authorisation:
{
"transactionType" : "PREAUTH",
"singleUseTokenId": "dec2075f-da92-49df-8a92-f7e494f89c22",
"supplierBusinessCode": "MYSUPPLIER",
"principalAmount": 10.00,
"currency" : "AUD",
"eci": "INTERNET",
"ipAddress" : "192.168.1.1"
}
To process a pre-authorisation using a customer's default tokenised account:
{
"transactionType": "PREAUTH",
"customerId": "-13669603",
"supplierBusinessCode": "MYSUPPLIER",
"principalAmount": 100.00,
"currency": "AUD",
"eci": "PHONE"
}
To process a pre-authorisation using a specified tokenised account:
{
"transactionType": "PREAUTH",
"accountToken": "QVTEST-143227292",
"supplierBusinessCode": "MYSUPPLIER",
"principalAmount": 20.00,
"currency": "AUD",
"eci": "PHONE"
}
To process a direct pre-authorisation:
{
"transactionType" : "PREAUTH",
"creditCard": {
"cardholderName" : "Jane Smith",
"cardNumber" : "4242424242424242",
"expiryDateMonth": "12",
"expiryDateYear": "2022",
"cvn": "123"
},
"supplierBusinessCode": "MYSUPPLIER",
"principalAmount": 30.00,
"currency" : "AUD",
"eci": "INTERNET",
"ipAddress" : "192.168.1.1"
}
Response
If successful, this method returns a Transaction Response Model in the response body.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
201 |
CREATED | The request has succeeded and the transaction model is returned in the response body. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data. Refer to errors in the response body for more. View more. |
Capture pre-authorisation
Use this resource to capture a pre-authorisation. You can capture a pre-authorisation only once, for an amount up to double the pre-authorised amount.
Use List open pre-authorisations to find initial or a re-authorisation pre-authorisations that have not been captured. You can capture against an initial or a re-authorisation pre-authorisation.
Request
POST /transactions
Use your Secret API key to access this resource.
Request body
Field | Format | Required | Description |
---|---|---|---|
transactionType |
string |
Required | CAPTURE |
supplierBusinessCode |
string |
Required | The code that uniquely identifies your business. |
principalAmount |
Money | Required | The amount of the capture before any surcharge is added. Send a positive value that does not exceed double the amount of the pre-authorisation transaction. If the business referenced by supplierBusinessCode has card surcharges configured, a surcharge amount will be calculated and added to this amount. |
currency |
string |
Required | One of AUD or NZD . |
originalReceiptNumber |
string |
Required | The receipt number of the pre-authorisation transaction to capture. |
customerReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history. |
paymentReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Your reference for this transaction. |
comment |
string |
Optional | A comment for the transaction. |
metadata |
Metadata | Optional. | Use this field to supply extra information about the transaction. |
You must handle errors and avoid duplicate transactions. Do not send eci
or ipAddress
fields.
Capture a pre-authorisation
{
"originalReceiptNumber": "1204957935",
"transactionType" : "CAPTURE",
"principalAmount": 10.00,
"customerReferenceNumber": "JANESMITH",
"paymentReferenceNumber" : "CAPTUREPREAUTH1",
"currency" : "AUD",
"comment" : "Capturing a pre-authorisation."
}
Response
If successful, this method returns a Transaction Response Model in the response body.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
201 |
CREATED | The request has succeeded and the transaction model is returned in the response body. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data. Refer to errors in the response body for more. View more. |
Cancel a pre-authorisation
Use this resource to partially or fully cancel a pre-authorisation. You must perform the cancellation against the original successful Visa/Mastercard pre-authorisation transaction.
See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.
To perform a full cancellation of a pre-authorisation you must:
- send
cancellationType
=FULL
- send the full amount of the original pre-authorisation in
principalAmount
.
To perform a partial cancellation of a pre-authorisation you must:
- send
cancellationType
=PARTIAL
- send the partial amount of the outstanding balance that you wish to cancel of the original pre-authorisation in
principalAmount
.
Request
POST /transactions
Use your Secret API key to access this resource.
Request body
Field | Format | Required | Description |
---|---|---|---|
transactionType |
string |
Required | PREAUTH_CANCELLATION |
cancellationType |
string |
Required | FULL when performing a full cancellation of a pre-authorisation. PARTIAL when performing a partial cancellation of a pre-authorisation. |
principalAmount |
Money | Required | Send the full amount of the original pre-authorisation when performing a FULL cancellation. Send the partial amount to cancel of the original pre-authorisation when performing a PARTIAL cancellation. |
currency |
string |
Required | One of AUD or NZD . |
originalReceiptNumber |
string |
Required | The receipt number of the pre-authorisation transaction to perform the cancellation for. |
customerReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history. |
paymentReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Your reference for this transaction. |
comment |
string |
Optional | A comment for the transaction. |
metadata |
Metadata | Optional. | Use this field to supply extra information about the transaction. |
You must handle errors and avoid duplicate transactions. Do not send eci
or ipAddress
fields.
Full cancellation of a pre-authorisation
{
"originalReceiptNumber": "1204957975",
"transactionType" : "PREAUTH_CANCELLATION",
"cancellationType" : "FULL",
"principalAmount": 10.00,
"customerReferenceNumber": "JANESMITH",
"paymentReferenceNumber" : "CANCELPREAUTH1",
"currency" : "AUD",
"comment" : "Fully cancelling a pre-authorisation."
}
Partial cancellation of a pre-authorisation
{
"originalReceiptNumber": "1204957976",
"transactionType" : "PREAUTH_CANCELLATION",
"cancellationType" : "PARTIAL",
"principalAmount": 1.00,
"customerReferenceNumber": "JANESMITH",
"paymentReferenceNumber" : "CANCELPREAUTH2",
"currency" : "AUD",
"comment" : "Partially cancelling a pre-authorisation."
}
Response
If successful, this method returns a Transaction Response Model in the response body.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
201 |
CREATED | The request has succeeded and the transaction model is returned in the response body. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data. Refer to errors in the response body for more. View more. |
Incremental pre-authorisation
Use this resource to top-up the original amount of a pre-authorisation. You must perform the incremental pre-authorisation transaction against the original successful Visa/Mastercard pre-authorisation transaction.
Request
POST /transactions
Use your Secret API key to access this resource.
Request body
Field | Format | Required | Description |
---|---|---|---|
transactionType |
string |
Required | PREAUTH |
authorisationType |
string |
Required | INCREMENTAL |
principalAmount |
Money | Required | The amount to top-up the original pre-authorisation. |
currency |
string |
Required | One of AUD or NZD . |
originalReceiptNumber |
string |
Required | The receipt number of the pre-authorisation transaction to perform the top-up for. |
customerReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history. |
paymentReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Your reference for this transaction. |
comment |
string |
Optional | A comment for the transaction. |
metadata |
Metadata | Optional. | Use this field to supply extra information about the transaction. |
You must handle errors and avoid duplicate transactions. Do not send eci
or ipAddress
fields.
Incremental pre-authorisation (aka Top-Up)
{
"originalReceiptNumber": "1204957977",
"transactionType" : "PREAUTH",
"authorisationType" : "INCREMENTAL",
"principalAmount": 2.00,
"customerReferenceNumber": "JANESMITH",
"paymentReferenceNumber" : "INCREMEMTALPREAUTH1",
"currency" : "AUD",
"comment" : "Top-up a pre-authorisation."
}
Response
If successful, this method returns a Transaction Response Model in the response body.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
201 |
CREATED | The request has succeeded and the transaction model is returned in the response body. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data. Refer to errors in the response body for more. View more. |
Extension pre-authorisation
Use this resource to extend an original Mastercard pre-authorisation to the maximum validity period supported by the card scheme. You must perform the extension transaction against the original successful Mastercard pre-authorisation transaction.
See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.
Request
POST /transactions
Use your Secret API key to access this resource.
Request body
Field | Format | Required | Description |
---|---|---|---|
transactionType |
string |
Required | PREAUTH |
authorisationType |
string |
Required | EXTENSION |
principalAmount |
Money | Required | Send 0.00 . |
originalReceiptNumber |
string |
Required | The receipt number of the pre-authorisation transaction to perform the extension for. |
customerReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history. |
paymentReferenceNumber |
string |
Optional | Up to 100 ASCII characters. Case insensitive. Your reference for this transaction. |
comment |
string |
Optional | A comment for the transaction. |
metadata |
Metadata | Optional. | Use this field to supply extra information about the transaction. |
You must handle errors and avoid duplicate transactions. Do not send eci
or ipAddress
fields.
Incremental pre-authorisation (aka Top-Up)
{
"originalReceiptNumber": "1204957978",
"transactionType" : "PREAUTH",
"authorisationType" : "EXTENSION",
"principalAmount": 0.00,
"customerReferenceNumber": "JANESMITH",
"paymentReferenceNumber" : "EXTENSIONPREAUTH1",
"currency" : "AUD",
"comment" : "Extend a Mastercard pre-authorisation."
}
Response
If successful, this method returns a Transaction Response Model in the response body.
HTTP status codes
See HTTP Status Codes for more.
Status Code | Description | More information |
---|---|---|
201 |
CREATED | The request has succeeded and the transaction model is returned in the response body. |
401 |
UNAUTHORIZED | The secret API key in the request is expired, or you have used your Publishable API key instead of your Secret API key. View more. |
422 |
UNPROCESSABLE ENTITY | The request body contained invalid data. Refer to errors in the response body for more. View more. |
Re-authorisation pre-authorisation
Use this resource to re-authorise an original Visa pre-authorisation that has expired after the validity period supported by the card scheme.
See Mastercard and Visa pre-authorisation enhancements for information about validity periods, use-cases and support.
originalReceiptNumber
.
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. |
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 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:
- CSV report version 2 - The preferred format.
- CSV report version 1 - Legacy format.
The reports are plain text using UTF-8 character encoding. All records except the last are separated by the CR LF end-of-line marker. Fields may be enclosed in double quotes. If double quotes enclose a field, then a double quote appearing inside a field is escaped by preceding it with another double quote.
Handling additional columns
From time to time additional columns will be added to the format. To maintain backwards compatibility, use the columns
parameter to list the columns you would like in the transaction export each time it's generated. Check the change-log for when new columns are added to the report.
CSV report version 2
Column | Value | Description |
---|---|---|
A | Supplier Business Code | The supplier business that the transaction went to. |
B | Supplier Business Name | The name of the QuickStream Business that the transaction went to. |
C | Source | A code indicating the source of the transaction. For example RESTAPI or BATCH . |
D | Transaction Type | PAYMENT , REFUND , PREAUTH , CAPTURE or ACCOUNT_VERIFICATION . |
E | Receipt Number | The unique receipt number allocated by QuickStream to the transaction. |
F | Payment Reference | A payment level identifier for the transaction as passed to QuickStream by a product. For example, you may pass or ask your customer to enter a Payment Reference Number on your QuickWeb. |
G | Customer Reference Number | A customer level identifier for the transaction as passed by QuickStream by a product. For example, you may pass or ask your customer to enter a Customer Reference Number on your QuickWeb. |
H | Principal Amount | The principal amount of the transaction. This is the transaction amount before a surcharge has been applied. |
I | Surcharge Amount | The surcharge amount of the transaction. |
J | Total Amount | The total payment amount. This is Principal Amount, plus Surcharge Amount. |
K | Currency | The currency code of the transaction. |
L | Status | The status of the transaction. One of:
|
M | Response Code | Reason code for the status . See Response Codes. |
N | Response Description | Reason description for the status . |
O | Summary Code | Success indicator for the responseCode . See Response Codes. |
P | Settlement Date | The day on which this transaction was considered to have been processed. DD MMM YYYY format. |
Q | Transaction Time | Date and time (if known) when transaction processing was initiated. DD MMM YYYY HH:mm Z format. |
R | IP Address | The IP address of the customer. For example, 192.168.42.184 . |
S | Comment | A comment for the transaction. |
T | FraudGuard Result | The fraud guard result description. For facilities using Fraud Guard only. |
U | Original Receipt Number | If a refund, the original payment. If a payment, the original PREAUTH or the automatically-retried payment. |
V | Soft Decline | true if the transaction was a soft-decline. See Response Codes. |
W | Automatic Retry Date | The date the transaction will be automatically retried. DD MMM YYYY format. |
X | Authorisation Code | The authorisation code returned from the issuing bank for pre-auth transactions (at most 6 characters). Only for approved pre-auth transactions. |
Y | Authorisation Type | INCREMENTAL , EXTENSION , REAUTHORISATION . For pre-authorisation transactions only. |
Z | Cancellation Type | FULL or PARTIAL . For pre-authorisation cancellations only. |
AA | Login Name | The login name of the user who made the transaction. QuickTerminal transactions only. |
AB | Full Name | The full name of the user who made the transaction. QuickTerminal transactions only. |
AC | API Key | The API key name. For REST API transactions. |
AD | Account Type | The type of account used to make the transaction. One of CREDIT_CARD , BANK_ACCOUNT , NZ_BANK_ACCOUNT |
AE | Account Token | The account token. For transactions against registered accounts. |
AF | Cardholder Name | The cardholder name. For credit card transactions. |
AG | Card Number | The credit card number, masked. For credit card transactions. |
AH | Expiry Date | The credit card expiry date. For credit card transactions. |
AI | Card Type | The card type. CREDIT , DEBIT . Note: This is only for VISA and MASTERCARD . Other card types may be added in the future. |
AJ | Card Scheme | The credit card scheme for credit card transactions. One of:
|
AK | Bank Account Name | The payer's bank account name. For Australian bank account transactions. |
AL | Bank Account BSB | The bank account BSB. For Australian bank account transactions. |
AM | Bank Account Number | The bank account number. For bank account transactions. |
AN | NZ Bank Account Name | The payer's bank account name. For New Zealand bank account transactions. |
AO | NZ Bank Account Bank Code | The bank code. For New Zealand bank account transactions. |
AP | NZ Bank Account Branch Code | The branch code. For New Zealand bank account transactions. |
AQ | NZ Bank Account Number | The account number. For New Zealand bank account transactions. |
AR | NZ Bank Account Suffix | The account suffix. For New Zealand bank account transactions. |
AS | Customer Id | QuickStream's unique identifier for the customer. |
AT | Customer Number | Your reference for the customer. |
AU | Payment Schedule Id | QuickStream's unique identifier for the recurring payment. For recurring transactions. |
AV | Settlement Account | For Australian payments, the BSB and account number of your settlement account. For New Zealand payments, the bank, branch and account numbers of your settlement account. |
AW | Ecommerce Identifier | The ecommerce identifier description for the transaction. For credit card transactions. |
AX | Card Issuing Country | The two digit ISO country code of the card issuer. |
CSV report version 1
Column | Value | Description |
---|---|---|
A | Community Code | Your QuickStream Community Code. This code is your unique identifier for your QuickStream facility. |
B | Business Code | The supplier business that the transaction went to. |
C | Business Name | The name of the QuickStream Business that the transaction went to. |
D | Source | The source of the transaction. For example QuickWeb or QuickBatch. |
E | Order Type | The order type of the transaction. For example capture, refund or pre-auth. |
F | Receipt Number | The unique receipt number allocated by QuickStream to the transaction. |
G | Customer Reference Number | A customer level identifier for the transaction as passed by QuickStream by a product. For example, you may pass or ask your customer to enter a Customer Reference Number on your QuickWeb. |
H | Customer Number | A customer level identifier for the transaction. This has a value only when you allocate a transaction to a customer record in QuickStream. |
I | Payment Reference | A payment level identifier for the transaction as passed to QuickStream by a product. For example, you may pass or ask your customer to enter a Payment Reference Number on your QuickWeb. |
J | Payment Amount | The total payment amount. This is Principal Amount, plus Surcharge Amount. |
K | Principal Amount | The principal amount of the transaction. This is the transaction amount before a surcharge has been applied. |
L | Surcharge Amount | The surcharge amount of the transaction. |
M | Currency | The currency code of the transaction. |
N | Settlement Date | The settlement date of the transaction. |
O | Transaction Date/Time | The date and time QuickStream performed the transaction. |
P | Transaction Status | The response code. |
Q | Summary Code | The summary code for the given Transaction Status. |
R | Transaction Status Description | The description of the given Transaction Status. |
S | Summary Description | A short description about the Summary Code. One of:
|
T | Authorisation Code | For a pre-authorisation transaction this is the authorisation code returned from the bank. |
U | Settlement Account Name | The name of the settlement account. This is usually the Merchant ID for credit card transactions. |
V | Payment Instrument | The payment instrument used to make the transactions. |
W | Account Type | The type of account used to make the transaction. For example: differentiate between credit card and bank account transactions. |
X | Customer Account Business Code | The customer account business code. Not used for all solutions. |
Y | Credit Card Scheme | The credit card scheme for credit card transactions. One of:
|
Z | Credit Card Number | The credit card number, masked. |
AA | Credit Card Expiry Date | The credit card expiry date. |
AB | Cardholder Name | The cardholder name. |
AC | Bank Account Name | The payer's bank account name. For bank account transactions. |
AD | Bank Account BSB | The bank account BSB. For Australian bank account transactions. |
AE | Bank Account Number | The bank account number. For bank account transactions. |
AF | Bank Account Bank Code | The bank code. For New Zealand bank account transactions. |
AG | Bank Account Branch Code | The branch code. For New Zealand bank account transactions. |
AH | Bank Account Suffix | The account suffix. For New Zealand bank account transactions. |
AI | Login Name | The login name of the user who made the transaction. QuickTerminal transactions only. |
AJ | Full Name | The full name of the user who made the transaction. QuickTerminal transactions only. |
AK | Comment | The comment left by the user who made the transaction. QuickTerminal transactions only. |
AL | Related Transaction Receipt Number | If you retry, complete or refund a transaction, the original receipt number appears here. |
AM | Fraud Guard Result | The fraud guard result description. For facilities using Fraud Guard only. |
AN | Ecommerce Identifier | The ecommerce identifier description for the transaction. For credit card transactions. |
Credit card request model
Field | Format | Required | Description |
---|---|---|---|
cardholderName |
string |
Optional | Name printed on the card. |
cardNumber |
string |
Required | Digits printed on the card. |
expiryDateMonth |
string |
Required | Two digit expiry month. |
expiryDateYear |
string |
Required | Four digit expiry year. |
cvn |
string |
Required when eci = INTERNET |
Card Verification Number. Also known as Security Code, CVV2 and CVC2. The three or four digit security code. |
Bank account request model
Field | Format | Required | Description |
---|---|---|---|
accountName |
string |
Optional | Name of account holder. |
bsb |
string |
Required | The bank-state-branch holding their account. |
accountNumber |
string |
Required | The account number at that branch. |
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. |
Transaction response model
Field | Format | Description |
---|---|---|
receiptNumber |
string |
Receipt number to display to customers. |
transactionType |
string |
PAYMENT , REFUND , PREAUTH , CAPTURE or ACCOUNT_VERIFICATION . |
authorisationType |
string |
INCREMENTAL , EXTENSION , REAUTHORISATION . For pre-authorisation transactions only. |
cancellationType |
string |
FULL or PARTIAL . For pre-authorisation cancellations only. |
status |
string |
Approved , Approved* , Pending , Declined , Voided or Suspended . See transaction status. |
responseCode |
string |
Reason code for the status . See Response Codes for more. |
responseDescription |
string |
Reason description for the status . |
summaryCode |
string |
Success indicator for the responseCode . See Response Codes for more. |
fraudGuardResult |
string |
The result of Fraud Guard processing. null when transaction is not processed using Fraud Guard. |
originalReceiptNumber |
string |
If a refund, the original payment. If a payment, the original PREAUTH or the automatically-retried payment. |
customerReferenceNumber |
string |
Unique identifier for a customer. When this value matches a customer number, the transaction shows in their payment history. |
paymentReferenceNumber |
string |
Your reference for this transaction. |
comment |
string |
A comment for the transaction. |
metadata |
Metadata | Extra information about the transaction. See Take Payment. |
source |
string |
A code indicating the source of the transaction. For example, RESTAPI . |
ipAddress |
string |
The IP address of the customer. For example, 192.168.42.184 . |
settlementDate |
date |
The day on which this transaction was considered to have been processed. See Transaction Settlement for more. |
transactionTime |
date-time |
Date and time (if known) when transaction processing was initiated. |
voidable |
boolean |
If true , this transaction may be voided. See Void payment. |
refundable |
boolean |
If true , this transaction may be refunded. See Refund payment. |
principalAmount |
Money | Amount before any surcharge added. |
surchargeAmount |
Money | Amount of surcharge. See surcharges. |
totalAmount |
Money | Total amount of transaction. Principal amount plus surcharge. |
merchantAccount |
Merchant Account | For credit card payments, your merchant facility. |
directEntryAccount |
Direct Entry Account | For Australian bank account payments, your direct entry settlement account. |
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. |
expiryDateMonth |
string |
Two digit expiry month. |
expiryDateYear |
string |
Two digit expiry year. |
cardScheme |
string |
The card scheme. VISA , MASTERCARD , AMEX , DINERS , JCB , or UNIONPAY . |
cardType |
string |
The card type. CREDIT , DEBIT . Note: This is only for VISA and MASTERCARD . Other card types may be added in the future. |
cardholderName |
string |
The name printed on the card. |
maskedCardNumber4Digits |
string |
Masked credit card number displaying last 4 digits. |
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",
"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
:
- Sign into QuickStream Portal.
- Click on Administration -> Business Settings.
- Search for your business.
- 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.