Skip to main content

Tutorials and troubleshooting

Explore the following tutorials for help using the QuickStream REST API.

Explore the API using Postman

Postman is a HTTP client for testing RESTful web services. Use Postman when you wish to explore the QuickStream REST API.

Step 1: Install Postman

  1. Install Postman for Windows/MacOS/Linux.

Step 2: Use API key for Basic Auth

  1. Start Postman.
  2. Click the Authorization tab.
  3. Select Basic Auth from the menu.
  4. Enter your Publishable API key into the Username field.
  5. Press Update request

Shows the Postman Authorization tab with the API key entered into the Username field

Step 3: Explore the API from the root resource

  1. In Postman's URL bar, select GET.
  2. Enter the URL https://api.quickstream.westpac.com.au/rest/v1.
  3. Press Send.
  4. Click links in the response to open them in a new tab in Postman. Use Postman to send requests to these resources.

Step 4: Sending content in the body

  1. Click on the Body tab, and choose the "raw" radio option, then change the dropdown from "Text" to "JSON (application/json)".
  2. Enter the JSON data for the request.

Trusted frame

Use this tutorial to create a web page that takes a one-off credit card payment or stores credit card details in QuickVault. Your server will not store or process credit card details.

This iframe solution allows you to be compliant with PCI-DSS SAQ A. This is the easiest level of compliance.

It works as follows:

  1. Your server hosts a web page containing a form and quickstream-api.js.
  2. You call init with your Publishable API key and createTrustedFrame which creates a QuickStream iframe for collecting card details.
  3. The iframe sends card details securely to QuickStream.
  4. The iframe sends a single use token to your website.
  5. Your server uses the token in place of the card details when you take a payment or register an account.

Step 1: Host example page

Host this page on your website. Cardholders will enter their details on this page.

<!DOCTYPE html>
<html>
  <body>
    <!-- this form will POST a single use token to your server -->
    <form id="payment-form" action="/process-payment" method="post">
        <div data-quickstream-api="creditCardContainer"></div>
        <input id="make-payment-submit" type="submit" disabled="true"/>
    </form>
    <script src="https://api.quickstream.westpac.com.au/rest/v1/quickstream-api-1.0.min.js">
    </script>
    <script type="text/javascript">
        var submit = document.getElementById('make-payment-submit');
        QuickstreamAPI.init({
          publishableApiKey: "{publishableAPIKey}"
        });
        var trustedFrame;
        var options = {
          config: {
            supplierBusinessCode: "{supplierBusinessCode}"
          }
        };
        QuickstreamAPI.creditCards.createTrustedFrame(options, function(errors, data){
            trustedFrame = data.trustedFrame;
            if(errors){
              submit.disabled = true;
            } else {
              submit.disabled = false;
            }
        });
        var form = document.getElementById("payment-form");
        form.addEventListener("submit", function(event){
          event.preventDefault();
          trustedFrame.submitForm(function(errors, data){
            if(!errors){
              QuickstreamAPI.creditCards.appendTokenToForm(form, data.singleUseToken.singleUseTokenId);
              form.submit();
            }
          });
        });
    </script>       
  </body>
</html>

Open the page. You should see this error message in the console log.

QuickstreamAPI: The "Authorization" header contained an unknown API key. You must send your API key as the basic authentication username.

Step 2: Set publishable API key

  1. Sign in to QuickStream.
  2. Click on Administration -> Facility Settings in the menu.
  3. Go to REST API keys
  4. Click on your publishable key (or add a new one)
  5. Copy the key.
  6. In your web page, replace {publishableAPIKey} with your publishable API key.

You may also change /process-payments to a URL you prefer.

Open the page again. You should see this error message in the console log.

QuickstreamAPI: Invalid supplier business code.

Step 3: Set business

The supplierBusinessCode is a reference to a business in your facility. A business contains a merchant facility that settles funds to a settlement account. It also has a list of accepted card types and any surcharges you have configured.

  1. Sign in to QuickStream.
  2. Click on Administration -> Facility Settings in the menu.
  3. Go to View connection details and then select the REST API tab.
  4. Copy a value for supplierBusinessCode from the list.
  5. In your web page, replace {supplierBusinessCode} with this value.

You can also use the REST API to list business that can accept REST API payments.

Step 4: Test page

Load your web page, you should see the credit card form.

Enter these card details:

Field Value
Cardholder name Token tutorial
Credit card number 4242 4242 4242 4242
Expiry date 12/2022
CVN 123

Your browser will POST to /process-payment on your server. The POST includes a parameter like this:

singleUseTokenId: 32500dec-569e-4bca-b3ed-c9596048f658

Step 5: Take payment or register card account

You can now use the single use token to take a payment or register the card in QuickStream.

When you receive a POST to /process-payment you should:

  1. Read the single use token from the parameter.
  2. Verify your customer using a session cookie.
  3. Using your secret API key and the single use token, send a request to take a one-time payment.

If you need to take more than one payment with the card details, you should register the card:

  1. Find a customer by your customer number or by the customerId.
  2. If your customer doesn't exist, create one.
  3. Using the single use token, send a request to register the card.
  4. You will recieve an account token.

You should then take payments using the account token via this API or using batch payment file.

If the customer already has an account token with the same card number, registering it again will update the expiry date and cardholder name and return the same account token.

Step 6: Improve your solution

You may now improve your solution by:

Tokenisation using Trusted Frame

Tokenisation (or registering a payment account) is a process by which card/bank account details are replaced with a surrogate value called an Account Token. Use the Trusted Frame to collect card/bank account details from a customer, then create a Single use token and send it to your server instead of the payment account details.

The tutorials below illustrate common ways of doing this.

See more about the differences between Account Tokens and Single use tokens.

Find or create the customer and tokenise at the same time

This is a possible scenario where the customer can be known or created after initialising the Trusted Frame to collect account details.

Sequence diagram illustrating the steps below.

Step Description
1 Your web app initialises the Trusted Frame.
2 The payer enters account details into the Trusted Frame.
3 The Trusted Frame generates a Single Use Token. The API responds with a Single Use Token Model.
Your web app retrieves it from the Trusted Frame, and adds the singleUseTokenId to your form.
4 Your web app will submit the singleUseTokenId to your server.
5 Your server finds a customer using the customerNumber, or by customerId. If the customer does not exist, create one.
The API responds with a Customer Model. The customerId property is the unique identifier for the customer.
6 Use the singleUseTokenId and customerId to register an account for a customer.
The API responds with a Customer Account Model. The accountToken property is the permanent token for the account. Use it to take payments later.
7 Generate a receipt/confirmation for the payer.

Find or create the customer first, then tokenise

This is a possible scenario where the customer can be known or created prior to initialising the Trusted Frame to collect payment account details.

Sequence diagram illustrating the steps below.

Step Description
1 Your server finds a customer using the customerNumber, or by customerId. If the customer does not exist, create one.
The API responds with a Customer Model. The customerId property is the unique identifier for the customer.
2 Provide the customerId back to your web app or store it for later.
3 Your web app initialises the Trusted Frame.
4 The payer enters account details into the Trusted Frame.
5 The Trusted Frame generates a Single Use Token. The API responds with a Single Use Token Model.
Your web app retrieves it from the Trusted Frame, and adds the singleUseTokenId to your form.
6 Your web app will submit the singleUseTokenId to your server.
7 Use the singleUseTokenId and customerId to register an account for a customer.
The API responds with a Customer Account Model. The accountToken property is the permanent token for the account. Use it to take payments later.
8 Generate a receipt/confirmation for the payer.

Tokenisation using Trusted Frame without customer details

This is a possible scenario where your system stores your customer details. This tutorial creates the same entities in the above tutorials, but removes the call to create a customer.

Sequence diagram illustrating the steps below.

Step Description
1 Your web app initialises the Trusted Frame.
2 The payer enters account details into the Trusted Frame.
3 The Trusted Frame generates a Single Use Token. The API responds with a Single Use Token Model.
Your web app retrieves it from the Trusted Frame, and adds the singleUseTokenId to your form.
4 Your web app will submit the singleUseTokenId to your server.
5 Use the singleUseTokenId to register an account without customer details.
6 The API responds with a Customer Account Model. The accountToken property is the permanent token for the account. Use it to take payments later. The customerId property is the unique identifier for the customer that this API has generated for this account.
7 Generate a receipt/confirmation for the payer.

Take payments using Trusted Frame

This is a common scenario where you want to take a one-off payment from a web application.

Sequence diagram illustrating the steps below.

Step Description
1 Your web app initialises the Trusted Frame.
2 The payer enters account details into the Trusted Frame.
3 The Trusted Frame generates a Single Use Token. The API responds with a Single Use Token Model.
Your web app retrieves it from the Trusted Frame, and adds the singleUseTokenId to your form.
4 Your web app will submit the singleUseTokenId to your server.
5 Your server takes a payment using the singleUseTokenId.
The API responds with a Transaction Response Model. The receiptNumber property is the unique identifier for a transaction.
6 Determine if the transaction was successful using the status property.
7 Generate a receipt/confirmation for the payer.

Upload payment files

Sequence diagram illustrating the steps below.

This is a common scenario where you want to upload a payment file to process transactions in bulk.

See also Using curl to upload a payment file.

Step Description
1 Create a payment file in one of the available formats.
2 Upload the payment file. Set the file parameter to the file name. Set the format parameter to the format of the payment file.
The API responds with a Payment File Model. The paymentFileId property is the unique identifier for a payment file. The status property describes the processing status of the payment file.
3 Get the payment file later to check the status.
4 If the file has errors, list and report them to your team internally. Fix the errors and upload the file again with a new file name.
5 If the file is processing, wait until it is in the COMPLETE status.
6 Your server may check the status of each payment batch in the file. The API returns a Payment Batch Model.
Your server may also check the status of each transaction. The API returns a Transaction Response Model.
7 When the file status is COMPLETE your server will download the transaction report in one of the of the available formats.

Use curl to check network

For your software to work, your server must be able to connect to QuickStream. Follow these details to determine if there is a problem with your network or your software.

Step 1: Download and install curl

Download and install the curl client for your platform from http://curl.haxx.se/download.html. Be sure to download the correct distribution for your server's operating system. You must download a version that includes SSL support.

If you are using Windows, we recommend that you download the binary distribution listed under the heading Win32 - Generic labelled Win32 2000/XP, binary and SSL and maintained by Gunter Knauf. This document does not provide a direct link because you should always download the latest version.

Step 2: Get the root resource for the API

To test if your server can connect to QuickStream: 

curl -i --basic --user "{publishableApiKey}:" {baseURL}

Replace {publishableApiKey} with your Publishable API Key. Replace {baseURL} with the Base URL for the environment you're working in.

Using curl to upload a payment file

Use this tutorial to upload a payment file. Complete the curl network connectivity tutorial first to ensure curl can connect to QuickStream.

See also Upload payment files.

Step 1: Generate a payment file

Your software must generate a file in one of the payment file formats. Each file must have a unique name.

In this tutorial, we assume the file is called example.csv.

Step 2: Save API key to file

  1. Enter the following into a text file:

     curl
 basic
 user={secretApiKey}:
 silent
 show-error
 fail

  2. Replace {secretApiKey} with your Secret API Key.

  3. Save the file as quickstream-curl-config.txt.

Step 3: Upload a payment file

To upload a payment file:

curl --config quickstream-curl-config.txt -F "file=@example.csv" {baseURL}/payment-files

Replace {baseURL} with the Base URL for the environment you're working in.

Step 4: Improve your solution

You may now improve your solution by:

  • Logging errors
  • Automating the process by creating a scheduled task. Refer to your operating system's documentation.
  • Polling the status of your file.
  • Downloading errors in your file and reporting them to staff.

Handling service outage using quickstream-api.js

If QuickStream-API.js cannot be retrieved (such as during a service outage), handle it by checking if window.QuickstreamAPI exists.

For example

if( window.QuickstreamAPI ) {
    QuickstreamAPI.init( {
        publishableApiKey: "{publishableAPIKey}"
    } );
    ...
} else {
    // handle error
    document.forms[0].innerHTML = '<div class="alert">This service is unavailable. Please check back shortly.</div>';
}

Displaying card scheme logos using quickstream-api.js

Using QuickStream-API.js you can display card scheme logos based on the setup of your QuickStream facility.

To do this:

For example

QuickstreamAPI.init( {
    publishableApiKey: "{publishableAPIKey}"
} );
QuickstreamAPI.creditCards.getAcceptedCards( "SUPPLIER_BUSINESS_CODE", function( errors, data ) {
    if( !errors ) {
        data.forEach( function( acceptedCard ) {
            switch ( acceptedCard.cardScheme ) {
                case "VISA" :
                    // Show the card scheme logo
                    break;
                case "MASTERCARD" : break;
                case "AMEX" : break;
                case "DINERS" : break;
                case "JCB" : break;
                case "UNIONPAY" : break;
            }
        } );
    }
} );

You can download and use the latest card scheme logos below. Do not link to a logo URL directly as they may change.

Card Scheme Logo Code
Visa Logo VISA
Mastercard Logo MASTERCARD
American Express Logo AMEX
Diners Club Logo DINERS
Union Pay Logo UNIONPAY

Validating credit card fields using quickstream-api.js

Using QuickStream-API.js you can validate credit card fields.

To do this:

For example

QuickstreamAPI.init( {
    publishableApiKey: "{publishableAPIKey}"
} );

// retrieve the card type from the credit card BIN.
QuickstreamAPI.creditCards.getCardScheme( form, function( errors, data ) {
    if( !errors ) {
        switch( data ) {
            case "VISA" : break;
            case "MASTERCARD" : break;
            case "AMEX" : break;
            case "DINERS" : break;
            case "UNIONPAY" : break;
        }
    } 
} );

// validate the card number entered
QuickstreamAPI.creditCards.validateCardNumber( form, function( errors, data ) {
    if( !errors && data.isValid ) {
       // card number is valid
    }
} );

// validate the expiry date
QuickstreamAPI.creditCards.validateExpiryDate( form, function( errors, data ) {
    if ( !errors ) {
        // expiry date is valid
    } else {
        errors.forEach( error ) {
            if( error.fieldName == "expiryDateMonth" ) {
                // handle month error
            } else if ( error.fieldName == "expiryDateYear" ) {
                // handle year error
            }
        }
    }
} );

// validate the CVN
QuickstreamAPI.creditCards.validateCvn( form, function( errors, data ) {
    if ( !errors ) {
        // CVN is valid
    }
} );

Transaction error handling

This API responds with Errors when a request is not processed successfully. When a transaction request is successfully processed this API returns a Transaction Response Code. Error information is provided in the summaryCode and a description of the error in the responseCode and responseDescription fields in the Transaction Response Model.

Use the table below to determine the appropriate system behaviour for each summaryCode.

Summary Code Description Recommended System Action
0 Transaction Approved Transaction is successful. No further action required.
1 Transaction Declined Transaction has been declined by the financial institution. See Transaction Response Code for common response codes.
In many cases, the problem can be addressed by either:
  • Carefully checking the card details and correcting any mistakes before creating a new transaction; or
  • Create a new transaction with an alternative card.
The reason for the decline may not always be obvious from the detailed response code. For example, Do Not Honour (05) may require offline follow up with the financial institution that issued the card.
2 Transaction Erred Transaction is of an unknown status. See Summary code 2 below.
3 Transaction Rejected Transaction request has been rejected by the API, often due to invalid system configuration. This is similar to the Transaction Declined (summaryCode of 1) in terms of error handling. Refer to the detailed response code and either:
  • Correct the transaction details if required and retry under as a new transaction; or
  • Handle offline through QuickStream Technical Support if unable to be resolved.

Summary code 2

A transaction may be received and processed by a financial institution but a system or network error may occur such that a response is not returned. Given that QuickStream does not know the status but it may have been successfully approved and the card debited, we must return the "Transaction Erred" status summaryCode = 2. An outage with the financial institution may last for some time and therefore your exception handling process must handle this rare but possible situation.

The recommended action is as follows:

  1. Request GET /transactions/{receiptNumber}. The API returns the most recent response and may be different to the response originally received.
  2. If summaryCode is 0, 1 or 3 in the response, then the transaction may be handled as if the response was received on the first attempt.
  3. If summaryCode is 2 after the first attempt, the transaction should be marked as held within your system. As the transaction may have been processed, it is not recommended that the transaction be retried by creating a new transaction. Your system should indicate to the end user that the status of the transaction is unknown and that they should contact your customer service personnel during applicable hours or provide a receipt number and contact the end user if the transaction is subsequently found to fail.
  4. If summaryCode is 2 after initial attempts, request GET /transactions/{receiptNumber} after settlement cutoff to try to automatically determine the status. QuickStream has processes in place to try to update these transactions with the final status and will endeavour to have statuses updated by settlement cutoff. This means that in many cases, the status will be available automatically if re-queries are attempted after this time.
  5. If summaryCode is 2 after settlement cutoff, we recommend re-querying at the same time on the following day as it may take up to 48 hours for the final status of transactions to be updated under some circumstances.
  6. For transactions that remain unresolved, your customer service would then try to resolve the situation by first using QuickStream Portal to query the transaction status. If this does not resolve the issue, the exception details should be communicated to QuickStream Technical Support for resolution. This would require details on the original transaction (particularly the receiptNumber), responses and exception handling actions attempted thus far.

Some customers, with a need for minimal customer impact of outages, have implemented additional business logic that tries to protect the end customer from such issues. As this may be useful in your implementation, a typical process is as follows:

  • If an API call returns a summaryCode of 0, 1 or 3 then your system handles this as per normal.
  • If an API call returns a summaryCode of 2 then your system handles this by returning a receipt number to the end customer and then tries to determine the transaction result in the background. This ensures that the end customer is not impacted by an outage period. If the transaction subsequently fails, this will require handling through an internal customer care process and may require contact with the end customer.

Troubleshooting

HTTP status codes other than 200

See: HTTP Status Codes.

curl: (60) SSL Certificate Problem: Unable to get local issuer certificate

Your server does not trust the server TLS certificate presented by QuickStream. Typically this is due to an out-dated root CA certificate bundle on your server. Download and install an updated root certificate for your server.

curl: (56) Received HTTP code 407 from proxy after connects

Your network has a proxy server. To test if your server can connect to QuickStream through the proxy server:

curl --proxy {proxyServer} --proxy-user {proxyUsernamePassword} -i --basic --user "{publishableApiKey}:" {baseURL}

Your software must connect to QuickStream through the proxy server.

curl: (6) Couldn't resolve host 'api.quickstream.westpac.com.au' or 'api.quickstream.support.qvalent.com'

DNS resolution failed. You may need to authenticate with your proxy server.

Disclaimer

The information contained in this publication is provided for learning purposes only and is subject to change. Revisions may be issued from time to time that encompass changes or additions to this module.

This is a guide only and it is not comprehensive. It does not impinge on or overrule any formal arrangement you may enter into with the Bank. The Bank and its officers shall not have any liability for any losses of any kind incurred in connection with any action, inaction or decision taken in reliance on the information herein or for any inaccuracies, errors or omissions. In this publication references to the "Bank" are to Westpac Banking Corporation ABN 33 007 457 141 and to any of its operating Divisions, including BankSA and St.George.