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
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.
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 andcreateTrustedFrame
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.
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.
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.
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.
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
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
-
Enter the following into a text file:
curl basic user={secretApiKey}: silent show-error fail
-
Replace
{secretApiKey}
with your Secret API Key. -
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:
- 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: "{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 |
![]() |
MASTERCARD |
![]() |
AMEX |
![]() |
DINERS |
![]() |
UNIONPAY |
Validating credit card fields using quickstream-api.js
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: "{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.