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.

Getting started

• Sign-in to QuickStream Portal to get your API keys.
• This API is RESTful.
• Determine the base URL for the Test environment.
• Send your API key as the HTTP Basic Auth username. Leave the password blank.
• You send JSON formatted requests and the API returns JSON formatted responses.
• Avoid duplicate POSTs by using an Idempotency-Key header.
• You must put in place error handling based on HTTP status codes.
• Transactions, customers and accounts are the most important resources.
• To avoid processing credit card details on your server, use a single-use-token.
• CORS is not supported.
• Use QuickStream-API.js to securely collect payment account details from your customers and create payment flows.
• Refer to the REST API developer log to view requests from your system and responses from this API.

Read next:

• Explore the API using Postman Tutorial
• Resource Summary
• QuickStream-API.js

Base URL

Use the QuickStream REST APIs in these environments:

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

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 404 Not Found or 422 Unprocessable Entity 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.

Secret API Key expiry email

Secret API keys expire every 2 years. QuickStream sends an email when one or more of your Secret API keys will expire soon.

QuickStream sends the email to the email address configured on the Manage REST API Keys page.

To change the email address:

1. Sign in to QuickStream.
2. Navigate to Administration -> Facility Settings -> Manage REST API Keys.
3. Update the email address on this page and save.

Use a group email address rather than an individual person. This can ensure the relevant people in your company receive this email.

QuickStream sends the email when a Secret API Key will expire in 30 days and then again in 7 days. The email lists the keys, their expiry date and the date it was last used.

Follow the instructions in the email to get a new Secret API key. You may also automate the Secret API key renewal. Your systems must be updated to use new keys before the old ones expire.

If you have updated your systems to use a new Secret API key, you will still receive this email until your old keys expire.

Publishable API keys do not expire.

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. 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 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 support the following browsers:

• Microsoft Edge per Microsoft's lifecycle policy.
• The current and previous version of Microsoft Edge, Mozilla Firefox, Google Chrome, Apple Safari, iOS and Android.
• We require TLS v1.2 to be supported by the browser.

Our Technical Support Team responds to bug reports but we do not proactively test other browsers. If you find an issue with Trusted Frame 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:

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

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:

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

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.

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.

API keys

For API Keys Resource details, see API Keys API.

Businesses

For Businesses Resource details, see Businesses API.

Single-Use-Tokens

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

Transactions

For Transaction Resource details, see Transactions API.

Customers

For Customers Resource details, see Customers API.

Accounts

For Accounts Resource details, see Accounts API.

Recurring payments

For Recurring Payments Resource details, see Recurring Payments API.

Credit cards

For Credit Cards Resource details, see Credit Cards API.

Payment files

For Payment Files Resource details, see Payment Files API.

PayTo Agreements

For PayTo Agreements Resource details, see PayTo Agreements.

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.
• QuickStream REST API transaction error handling.

Error responses

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

For example:

{
    "links": [],
    "status": "",
    "requestMethod": "",
    "requestUrl": "",
    "customerMessage": "",
    "developerMessage": "",
    "errors": []
}

Field errors

The response body includes field-level validation errors.

For example:

{
    "messages": [],
    "fieldName": "",
    "fieldValue": ""
}

HTTP status codes

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

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.

Cross-Origin Resource Sharing

You may not call the QuickStream REST API using Ajax.

To send credit card or bank account details from the browser to QuickStream, implement the Trusted Frame solution. Using an iframe provides additional security and minimises your PCI-DSS scope.

If a resource requires your secret key, send the request from your server. For security, only your server is allowed to take payments, process refunds etc.

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.