Tutorials

Tutorials and troubleshooting

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

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.

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

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 VeriSign Class 3 Primary CA - G5 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.