Tutorials

Explore the following tutorials for help using the QuickStream 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

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.

QuickStream-API.js tutorials

Displaying card scheme logos

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

To do this:

• Use QuickstreamAPI.creditCards.getAcceptedCards( 'SUPPLIER_BUSINESS_CODE', callback ); to retrieve a list of the credit card types accepted for that facility.
• In your callback function, for each card scheme code display an appropriate card scheme logo.
• The data also contains the surcharge rate you've set for each card scheme.

For example

QuickstreamAPI.init( {
    publishableApiKey: "PUBLISHABLE_API_KEY"
} );
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
	MASTERCARD
	AMEX
	DINERS
	UNIONPAY

Validating credit card fields

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

To do this:

• Create a form with elements having the data-quickstream-api attribute.
• Use QuickstreamAPI.creditCards.getCardScheme( form, callback ); to retrieve the card scheme type from the credit card BIN.
• Use QuickstreamAPI.creditCards.validateCardNumber( form, callback ); to validate a credit card number.
• Use QuickstreamAPI.creditCards.validateExpiryDate( form, callback ); to validate the expiry date fields
• Use QuickstreamAPI.creditCards.validateCvn( form, callback ); to validate the CVN.

For example

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

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

Handling service outage

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: "PUBLISHABLE_API_KEY"
    } );
    ...
} else {
    // handle error
    document.forms[0].innerHTML = '<div class="alert">This service is unavailable. Please check back shortly.</div>';
}

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.

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.

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.

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.