REST API Reference

API reference

The QuickStream REST API is RESTful. The API authorisation framework is HTTP Basic Auth.

You send JSON formatted requests and the API returns JSON formatted responses. Because the REST API is based on open standards, you can use any web development language to access the API.

Access depends on the enabled capabilities of your QuickStream facility.

Our APIs

Transactions

Transactions include payments, voids, refunds and pre-auths.

Single-use-tokens

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

Customers

Customers store account and payment information and contact details.

Accounts

Accounts store the details of cards or bank accounts to be used for payment.

Payment files

Payment files contain transactions that you want QuickStream to process in payment batches.

Businesses

Business store business rules like surcharging and transaction settlement, and to assist data segregation.

Credit cards

Retrieve scheme details about a card.

API keys

Use your existing secret key to get a new secret key.

Recurring payments

Recurring payments are schedules describing repeated installments paid to your facility by customers.

To test your network connectivity and API credentials are working correctly, use the Root API.

Getting started

Read next:

Base URL

Use the QuickStream REST APIs in these environments:

Environment Description URL
Support This is the Test environment. Use your test API keys to make calls to the test URIs. https://api.quickstream.support.qvalent.com/rest/v1
Production This is the Live environment. Use your production API keys to make calls to the live URIs. https://api.quickstream.westpac.com.au/rest/v1

Versioning

The current version of the API is v1.

Our change log outlines changes between various API versions to help our merchants better integrate with our API service.

If we make any backwards incompatible changes we will release a new major version of the API.

Resources

The following changes will not result in a new API version:

  • Adding new resources.
  • Supporting new HTTP verbs.
  • Changing the length or format of IDs. You can assume IDs we generate will not exceed 255 characters. You should be able to handle IDs of up to 255 characters.
  • Adding new optional request parameters.
  • Adding new properties in responses.
  • Changing the order of properties in requests and responses.
  • Changing wording of error message designed to be displayed to users.
  • Improved error reporting when an invalid request is received.
  • Appending new fields to, or re-purposing filler fields in transaction reports.

Your software must be written to handle these types of changes.

JavaScript

The following changes to quickstream-api.js will not result in a new API version:

  • Changing resources used internally by quickstream-api.js.
  • Adding new properties to objects passed to callback functions.
  • Adding new optional properties to quickstream-api.js functions you call.
  • Modifying messages posted between quickstream-api.js and an iframe hosted by us.

Write your software based on the documented API.

Security

The following changes will not result in a new API version:

  • adding or removing TLS ciphers
  • changing supported TLS versions
  • changing the QuickStream server SSL certificate or which certificate authority signs this certificate
  • other changes made to improve security

If you believe we have made a backwards-incompatible change, please report a defect.

Credentials and security

Authentication and headers

Authentication to the API is via HTTP Basic Auth. All API requests must be made over HTTPS.

For example:

GET /rest/v1 HTTP/1.1
Host: api.quickstream.westpac.com.au
Authorization: Basic cXZ0ZXN0YXBpa2V5Og==
Accept: application/json
Request header Description
Authorization When you access a resource you must use your Secret API key or your Publishable API key. You must send an API key as the Basic Authentication username. Leave the password blank.
Accept Set to application-json. Required.
Idempotency-Key Contains a unique ID that you generate for enforcing idempotency. Omitting this header increases the risk of duplicate transactions. See Idempotent Requests.

API credentials

You must provide these values to access the API:

  • Secret API Key: allows you to process payments and provides full access to the API.
  • Publishable API Key: can be used in mobile applications and web pages and has limited access.

To get these values:

  1. Sign-in to QuickStream in the test or production environment.
  2. To get an API key, navigate to Administration -> Facility Settings -> Manage REST API Keys.

Secret API keys expire after 2 years and then you must use a new key. You can automate secret API key renewal.

Each resource in this API requires either your Secret API Key or Publishable API Key. No resources accept both keys.

Sending an invalid API key returns a 401 Unauthorized HTTP status code.

Sending a valid API key, but the wrong type of key for the resource returns a 403 Forbidden HTTP status code.

To test authentication, send a GET to the base URL.

IP address checking

By default, this API does not validate the IP address of incoming requests. To have this API check the incoming IP address of requests against a whitelist:

  1. Sign-in to QuickStream in the test or production environment.
  2. Navigate to Administration -> Facility Settings -> Manage IP Address Whitelist
  3. Enter the public network IP address(es) of the system that will send requests to this API.
  4. Navigate to Administration -> Facility Settings -> Manage REST API Keys.
  5. Toggle the option "Check requests against IP address whitelist" to On.

Sending a request with a valid API key from an IP address that is not in the whitelist returns a 401 Unauthorized HTTP status code.

Secret API Key restrictions

You may create Secret API Keys with Business restrictions.

This API will reject requests using Secret API Keys with Business restrictions if the resource relates to a Business that is not configured on the key. For example, a Secret API key restricted to Business A cannot take or see payments for Business B.

To create a Secret API key with Business restrictions:

  1. Sign-in to QuickStream in the test or production environment.
  2. Navigate to Administration -> Facility Settings -> Manage REST API Keys
  3. Create a new Secret API Key and configure the list of Businesses that this key may access.

Sending a request with for a resource that does not meet the key's restrictions returns a 401 Unauthorized HTTP status code.

Secret API keys with restrictions cannot be automatically renewed using this API. You must sign in to QuickStream to create a new key.

You cannot edit a restricted Secret API key once it is created.

Sharing Secret API Keys

Your company's implementation of the REST API may require you to share a Secret API Key with a third party. Secret API Keys grant access to the API, and must be securely handled throughout their life cycle. By sharing a Secret API Key with another party, you are trusting them to manage it correctly.

Secret API keys expire every 2 years. You may need to follow a renewal process every 2 years for any Secret API Key you have shared. Keep in mind that no approach to security can guarantee 100% security.

Transport layer security

You must secure your connection using Transport Layer Security (TLS) 1.2 over HTTPS. All JavaScript is served over TLS, preventing man-in-the-middle attacks.

Cross-site scripting

Trusted Frame is secure against cross site scripting. We follow OWASP secure coding practices and are a fully PCI compliant service provider. However, you are responsible for the security of your page that loads the Trusted Frame or Custom Form. This includes following OWASP secure coding practices and preventing cross-site scripting.

DDOS protection

This API has Distributed Denial-of-Service (DDOS) protection. DDOS protection is used to prevent malicious users using all the available resources.

Browser compatibility

With Trusted Frame and Custom Form we endeavour to support all recent versions of major internet browsers. To provide the best and most secure customer experience, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.

Trusted Frame and Custom Form support the following browsers:

Our Technical Support Team responds to bug reports but we do not proactively test other browsers. If you find an issue with Trusted Frame or Custom Form on a specific browser, please let us know.

PCI compliance

QuickStream securely stores and processes card data for you. QuickStream is hosted and maintained by Qvalent Pty Ltd, a wholly owned subsidiary of Westpac Banking Corporation. Qvalent is a Level 1 PCI DSS Compliant Service Provider.

Read more about PCI Compliance.

HTTP verbs

The standard HTTP verbs used are:

Verb Purpose
GET Read a resource
PUT Create or replace a resource when URL is known
POST Create a resource when URL is not known
PATCH Update details of a resource
DELETE Delete a resource

Idempotent requests

You should set a unique value for the Idempotency-Key header on POST requests. Use a UUID for your idempotency key.

For example

POST /rest/v1/transactions HTTP/1.1
Host: api.quickstream.westpac.com.au
Idempotency-Key: a1b22c16-4870-428c-a199-6203cbec7290
Authorization: Basic cXZ0ZXN0YXBpa2V5Og==
Accept: application/json

This allows you to retry requests after a network failure without accidental duplication. If you get a network error or timeout, you should resend the request with the same Idempotency-Key.

If you resend a POST request with the same value for the Idempotency-Key, you will get the original response. If the server is still processing the original POST, you will receive 429 Too Many Requests.

When identifying whether a previous response should be returned we will ignore all aspects of the incoming request apart from the Idempotency-Key. For example, a request to a different endpoint will still result in the response from the original request being returned.

Idempotency keys expire after 22 hours. The maximum length is 60 ASCII characters.

HATEOAS and pagination

If available, each response from the API includes an array of contextual HATEOAS links. You can follow links returned in responses to related resources.

Open help URLs in your browser to access developer help (usually this reference).

Resources which return lists use a standard structure:

  • The data JSON property holds up to 20 items.
  • More results can be found by following next and prev links.

See Links for the response body.

Links

The response body contains links in most responses generated by this API.

For example:

{
    "rel": "",
    "href": "",
    "requestMethod": ""
}
Field Format Data
rel string The relationship to the resource. Open help URLs in a browser to view this developer reference. next and prev are used for paginated resources.
href string URL of a related document or resource.
requestMethod string HTTP Verb

Filtering

You can use query parameters to filter the responses to some GET requests.

For example, the Recent Transaction Search returns transactions processed against any business. To view recent transactions for a single business provide the supplierBusinessCode query parameter.

For example

GET /rest/v1/transactions?supplierBusinessCode=MYSUPPLIER HTTP/1.1
Host: api.quickstream.westpac.com.au
Authorization: Basic cXZ0ZXN0YXBpa2V5Og==
Accept: application/json

Dates

Dates are requested and returned as a string in the following formats:

Reference Format Description
date YYYY-MM-DD For dates with no time component, use the ISO-8601 short date format. An example is the settlement date, which groups together transactions which are part of the same logical banking day.
date-time YYYY-MM-DDTHH:mm:ssZ For dates with a time component, use the ISO-8601 extended format.
date-month YYYY-MM For dates with no day component, use the ISO-8601 year and month format. This format is used to filter large result sets by month and year.

Credit card expiry dates are an exception to the above formats. A credit card expiry month is treated as a two digit string. A credit card expiry year is treated as a two digit string. This matches what is printed on credit cards.

For example:

{
    "settlementDate": "2022-01-02",
    "month": "2022-01",
    "transactionDateTime": "2022-01-02T03:48:40+00:00",
    "expiryDateMonth": "01",
    "expiryDateYear": "22"
}

Money

Money request

Provide monetary amounts in requests as numeric values to two decimal places.

For example:

{
    "transactionAmount": 1005.25
}

Money response

This API returns monetary amounts in responses with the following response body.

Field Format Data
currency string ISO 4217 currency code.
amount decimal Monetary amount to two decimal places.
displayAmount string A customer friendly amount you can display to your customers.

For example:

{
    "transactionSuccessAmount": {
        "currency" : "AUD",
        "amount": 1005.25,
        "displayAmount": "$1,005.25"
    }
}

Money response with surcharge

Some monetary amounts returned in responses will have extra information about any surcharges included in the total amount.

Field Format Data
principalAmount As above The amount of the payment before any surcharge is added.
surchargeAmount As above Amount of surcharge. See List accepted cards.
totalAmount As above Total amount of transaction. Principal amount plus surcharge.

For example:

{
    "instalmentAmount": {
        "principalAmount": {
            "currency": "AUD",
            "amount": 992.10,
            "displayAmount": "$992.10"
        },
        "surchargeAmount": {
            "currency": "AUD",
            "amount": 24.80,
            "displayAmount": "$24.80"
        },
        "totalAmount": {
            "currency" : "AUD",
            "amount": 1016.90,
            "displayAmount": "$1,016.90"
        }
    }
}

Resource summary

This API reference is organised by resource type. Each resource type has one or more data models and one or more methods.

Root

For Root Resource details, see Root API.

Action HTTP request Description
Get GET / Gets information about your facility. Use to test your network connectivity and API credentials are working correctly.

API keys

For API Keys Resource details, see API Keys API.

Action HTTP request Description
Get latest GET /api-keys/latest Get your latest Secret API Key and automate your secret key renewal code.

Businesses

For Businesses Resource details, see Businesses API.

Action HTTP request Description
Get GET /businesses/{supplierBusinessCode} Get the details of a business.
List GET /businesses List the businesses in your facility.
List accepted cards GET /businesses/{supplierBusinessCode}/accepted-cards List the accepted card schemes.
List card surcharges GET /businesses/{supplierBusinessCode}/card-surcharges List the accepted credit card schemes, types and surcharge rates for a business.
Query card surcharge POST /businesses/{supplierBusinessCode}/query-card-surcharge Find the surcharge information for a card number.

Single-Use-Tokens

For Single-Use-Tokens Resource details, see Single-Use-Tokens API.

Action HTTP request Description
Generate token POST /single-use-tokens Generate a single-use-token for credit card or bank account details.

Transactions

For Transaction Resource details, see Transactions API.

Action HTTP request Description
Get details GET /transactions/{receiptNumber} Get the transaction details.
List GET /transactions List your 20 most recent transactions.
List by reference GET /transactions/for-reference-number List transactions by reference.
List by settlement date GET /transactions/for-settlement-date List transactions by settlement date.
List by account token GET /transactions/for-account-token/{accountToken} List transactions by account token.
List by credit card GET /transactions/for-credit-card List transactions by credit card.
List by bank account GET /transactions/for-bank-account List transactions by bank account.
List suspended GET /transactions/suspended List transactions suspended by Fraud Guard.
List refunds of a transaction GET /transactions/{receiptNumber}/refunds List refunds of a transaction.
List retries of a transaction GET /transactions/{receiptNumber}/retries List retries of a transaction.
Take payment POST /transactions Take a credit card or bank account payment.
Void transaction POST /transactions/{receiptNumber}/void Void a payment.
Refund payment POST /transactions Refund a payment.
Pre-authorisation POST /transactions Take a credit card or bank account payment.
Capture pre-authorisation POST /transactions Capture a pre-authorisation.
Account verification POST /transactions Verify a Visa or Mastercard account.

Customers

For Customers Resource details, see Customers API.

Action HTTP request Description
Get GET /customers/{customerId} Get the details of a customer.
Search GET /customers Search all customers.
Create POST /customers Create a new customer.
Update PUT /customers/{customerId} Update a customer.
Update customer status PATCH /customers/{customerId} Enable or disable a customer.
List accounts GET /customers/{customerId}/accounts List the accounts registered for a customer.
Register account POST /customers/{customerId}/accounts Register a new account for a customer.
List recurring payments GET /customers/{customerId}/recurring-payments Lists recurring payments for a customer.
Create recurring payment POST /customers/{customerId}/recurring-payments Create a recurring payment for a customer.
List payment history GET /customers/{customerId}/transactions List the payment history for a customer.

Accounts

For Accounts Resource details, see Accounts API.

Action HTTP request Description
Get GET /accounts/{accountToken} Get the details of an account.
Update PATCH /accounts/{accountToken} Update the account holder name or expiry date of an account.
Disable DELETE /accounts/{accountToken} Disable an account.

Recurring payments

For Recurring Payments Resource details, see Recurring Payments API.

Action HTTP request Description
Get GET /recurring-payments/{paymentScheduleId} Get the details of a recurring payment.
Update PUT /recurring-payments/{paymentScheduleId} Update a recurring payment.
Stop PATCH /recurring-payments/{paymentScheduleId} Stop a recurring payment.
List payment history GET /recurring-payments/{paymentScheduleId}/transactions List the payment history for a recurring payment.

Credit cards

For Credit Cards Resource details, see Credit Cards API.

Action HTTP request Description
Get card scheme GET /credit-cards/card-schemes/{cardBIN} Get the card scheme from a credit card BIN.

Payment files

For Payment Files Resource details, see Payment Files API.

Action HTTP request Description
Upload payment file POST /payment-files Payment files contain transactions that you want QuickStream to process.
Get payment file GET /payment-files/{paymentFileId} Get the details of a payment file.
List payment files GET /payment-files List the previous 365 days of payment files.
List payment file errors GET /payment-files/{paymentFileId}/errors Use this resource to list the errors in a payment file.
Get payment batch GET /payment-batches/{paymentBatchId} Get the details of a payment batch.
List payment batches GET /payment-files/{paymentFileId}/payment-batches A payment file contains one or more payment batches.
List payment batch transactions GET /payment-batches/{paymentBatchId}/transactions Use this resource to list the transactions in a payment batch.
Download Flat file report GET /payment-files/{paymentFileId}/csv Use this resource if your software is compatible with the CSV report format.
Download CSV report GET /payment-files/{paymentFileId}/flat-file Use this resource if your software is compatible with the Flat File report format.
Download Westpac MTS Rejects report GET /payment-files/{paymentFileId}/mts-rejects Use this resource if your software is compatible with the Westpac MTS Rejects report format.

Errors

Error handling

If you receive one of these responses, wait 20 seconds and then resend the request with the same Idempotency-Key:

  • 429 Too Many Requests
  • 503 Service Unavailable
  • A transient network error, such as a time-out or closed socket

If you receive a 422 Unprocessable Entity you may display the error message to your user and allow them to correct the data.

If you receive any other response code, you should log the response code and response body.

See HTTP Status Codes.

Error responses

The response body for all HTTP errors includes additional error details.

For example:

{
    "links": [],
    "status": "",
    "requestMethod": "",
    "requestUrl": "",
    "customerMessage": "",
    "developerMessage": "",
    "errors": []
}
Field Format Data
links Array of Links One or more links related to the error.
status string HTTP status code.
requestMethod string HTTP method used in the request that resulted in this error.
requestUrl string URL used in the request that resulted in this error.
customerMessage string A user friendly message you can display to your customers.
developerMessage string A developer friendly message that may provide more information.
errors Array of Field Errors (optional) A list of validation errors that may be applicable to the response.

Field errors

The response body includes field-level validation errors.

For example:

{
    "messages": [],
    "fieldName": "",
    "fieldValue": ""
}
Field Format Data
messages Array of string An error message you can display to your customers. Do not rely on error messages as we may change them without notice.
fieldName string The name of the field in the request that resulted in this error.
fieldValue string The value of the field provided in the request that resulted in this error.

HTTP status codes

QuickStream REST API returns standard HTTP status codes for successful and error responses.

Status Code Description More information
200 OK The request has succeeded.
201 CREATED The server has created the resource you requested. If you created a transaction, you must use the status field to determine if the transaction was approved. The Location header points to the new resource.
202 ACCEPTED The request has been accepted for processing, but the processing has not completed.

For transactions, this response code is returned if the banking network is slow to respond when processing a transaction. The status of the transaction will be pending. To find out if a transaction is approved or declined, send a request to get transaction details.
204 NO CONTENT Response to a successful request that won't be returning a body. This response code is returned for DELETE requests.
301 MOVED PERMANENTLY The resource requested is located at a different URI. See Base Url.
400 BAD REQUEST The request could not be understood by the server due to malformed syntax.

This response code is returned if the Idempotency-Key header is too long. This response code is returned if you send query parameters on a PUT, POST or PATCH request.
401 UNAUTHORIZED View more.
403 FORBIDDEN View more.
404 NOT FOUND View more.
405 METHOD NOT ALLOWED A request was made of a resource using a request method not supported by that resource. For example, you sent a POST to a resource that only allows GET. Refer to the documentation of the resource for supported methods.
406 NOT ACCEPTABLE The server can not send the representation requested by the client. For example, the accept header provided was not application/json.
407 PROXY AUTHENTICATION REQUIRED This error is returned by your proxy server, not QuickStream. You need to configure a proxy username and password in order to access the internet.
409 CONFLICT The server can not process the request as it has conflicted with another request. For example, this occurs if you attempt to create two customers with the same customer number simultaneously. See Idempotent Requests.
415 UNSUPPORTED_MEDIA_TYPE The server can not process the content type which was provided. The content type header provided was not application/json.
422 UNPROCESSABLE ENTITY View more.
429 TOO MANY REQUESTS View more.
500 INTERNAL SERVER ERROR View more.
501 NOT IMPLEMENTED The server does not recognize the request method. Use one of the standard HTTP verbs.
503 SERVICE UNAVAILABLE View more.

401 Unauthorized

The server can not authenticate the details in the Authorization header or your facility is set to reject requests from IP addresses it does not recognise. The response body contains more specific information.

This indicates that you have not passed a valid API key, the key has expired, or the Authorization header is not formatted correctly. Correctly formatted requests include a header like this:

Authorization: Basic cXZ0ZXN0YXBpa2V5Og==

The letters after Basic are the base-64 encoded representation of your API key.

See Authentication and Headers and IP address checking.

403 Forbidden

A valid API key was provided, but it does not have access to the requested resource.

Incorrect API key

Check if you have provided your publishable API key when you should have provided your secret API key. Refer to the documentation of the resource for supported API keys.

See API Credentials for information on API keys.

Facility setup incomplete

Your facility configuration is not completed. Contact your Westpac representative.

Facility is not live

Your facility is not live in the Production environment. This error is not returned in the Support (test) environment. Contact your Westpac representative.

404 Not Found

The server has not found anything matching the Request-URI. The response body may contain more information.

Check if your Secret API key has Business restrictions, and the requested resource relates to a Business that it cannot access.

422 Unprocessable Entity

The server can not process the content of the request.

Check if your Secret API key has Business restrictions, and the requested resource relates to a Business that it cannot access.

The response body indicates which parameters are in error. You may display the error messages to users.

You should resend the request with corrected parameters.

Payment method required

The requested payment method is not accepted by your facility. For example, you tried to make a bank account payment when your facility is not set up to accept bank account payments.

429 Too Many Requests

When a request is rejected due to rate limiting you have sent too many requests in a given amount of time. If you send more than 10 simultaneous requests, you may receive this response code.

If you resend a POST with an Idempotency-Key before the server has processed the original request, you will receive this response code. You should wait for 20 seconds and resend the request with the same Idempotency-Key. See Idempotent Requests.

Token quota exceeded

A quota of 1000 unused single-use-tokens applies per facility and per IP address. Immediately after obtaining a single-use-token, you should use it.

If you exceed the quota, it is likely that you are creating tokens and not using them. Tokens expire after 10 minutes. After they expire, you can create more.

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

You should not resend the request. The server may have completed some of the request processing. Contact QuickStream Technical Support. Provide the following information:

  • the QuickStream community code for your facility,
  • the method you sent in the request (e.g. GET, POST),
  • the URL you sent in the request,
  • the date/time of the request,
  • the response body returned by the server (if any).

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

If you continue to experience problems, contact QuickStream Technical Support. Provide the following information:

  • the QuickStream community code for your facility,
  • the method you sent in the request (e.g. GET, POST),
  • the URL you sent in the request,
  • the date/time of the request,
  • the response body returned by the server (if any).

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.