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

Install Postman for Windows/MacOS/Linux.

Step 2: Use API key for Basic Auth

Start Postman.
Click the Authorization tab.
Select Basic Auth from the menu.
Enter your Publishable API key into the Username field.
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

In Postman's URL bar, select GET.
Enter the URL https://api.quickstream.westpac.com.au/rest/v1.
Press Send.
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

Click on the Body tab, and choose the "raw" radio option, then change the dropdown from "Text" to "JSON (application/json)".
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:

Your server hosts a web page containing a form and quickstream-api.js.
You call init with your Publishable API key and createTrustedFrame which creates a QuickStream iframe for collecting card details.
The iframe sends card details securely to QuickStream.
The iframe sends a single use token to your website.
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

Sign in to QuickStream.
Click on Administration -> Facility Settings in the menu.
Go to REST API keys
Click on your publishable key (or add a new one)
Copy the key.
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.

Sign in to QuickStream.
Click on Administration -> Facility Settings in the menu.
Go to View connection details and then select the REST API tab.
Copy a value for supplierBusinessCode from the list.
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:

Read the single use token from the parameter.
Verify your customer using a session cookie.
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:

Find a customer by your customer number or by the customerId.
If your customer doesn't exist, create one.
Using the single use token, send a request to register the card.
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:

Avoiding duplicates by using an Idempotency-Key header.
Handling errors.
Styling the iframe.
Protecting your site from card testing.
Adding bank accounts.
Updating card or bank accounts for an existing customer.
Handling a service outage.

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.