QuickStream-API.js Reference

QuickStream-API.js is a JavaScript library containing helper functions for collecting credit card details, validating these details and obtaining a single-use-token without any sensitive details ever touching your servers. All sensitive data is sent directly from the customer’s browser to our QuickStream servers.

Including QuickStream-API.js On Your Website

To begin using QuickStream-API.js on your website, you first need to include the library and initialise it with your publishable API key. You can do this by including the following on your page (replace the initialisation values with your own):

<script type="text/javascript" src="https://api.quickstream.westpac.com.au/rest/v1/quickstream-api-1.0.min.js"></script>
<script>
    QuickstreamAPI.init( {
        publishableApiKey: "PUBLISHABLE_API_KEY"
    } );
</script>

QuickstreamAPI Module

QuickstreamAPI is the main module in the QuickStream-API.js library. It provides access to initialisation functions and to the submodules that rely on these values.

QuickstreamAPI contains the following submodules:

  • creditCards
  • bankAccounts

Before looking at these submodules, the callback function and the Error object must be introduced, since these supporting structures are extensively used throughout the library.

callback( errors, data ) → void

Many functions made available throughout the QuickStream-API.js library take a callback function as the final parameter. This callback function follows the error-first-callback pattern, where the first parameter will receive a list of errors if the calling function fails, and the second parameter will receive the resultant data if the calling function is successful.

PARAMETERS

Name Type Attributes Description
errors array of Error An array of Error objects that describe the errors encountered by the calling function.
data object An object that contains name/value pairs representing the successful result of the calling function.

EXAMPLE

let callback = function( errors, data ) {
    if ( errors ) {
        // Perform error handling here
    }
    else {
        console.log( data );
    }
}

Error

This object represents an error condition. Generally an array of these objects are provided as the first parameter to callbacks throughout the library.

PROPERTIES

Name Type Attributes Description
fieldName string The name of the field for which an error has been generated.
messages array of string An array of error messages. Each message represents a different error with the current field.

EXAMPLE

{
    fieldName: "cardNumber",
    messages: [ "Invalid credit card number." ]
}

init( data ) → void

This is used to initialise the library.

PARAMETERS

Name Type Attributes Description
data object Contains initialisation data as name/value pairs.

The data parameter is a JavaScript object and must contain your publishable API key. All other name/value pairs you provide in data will be discarded.

EXAMPLE

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

getPublishableApiKey() → string

Returns the publishable API key that was passed in when init( data ) was called, or undefined if the library hasn’t been initialised yet.

EXAMPLE

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

QuickstreamAPI.getPublishableApiKey(); // Returns "PUBLISHABLE_API_KEY"

isInitialised() → boolean

Returns true if the publishable API key has been initialised with a value. Otherwise returns false.

QuickstreamAPI.isInitialised(); // Returns false

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

QuickstreamAPI.isInitialised(); // Returns true

Credit Cards Module

QuickstreamAPI provides a Credit Cards module, which can accessed via QuickstreamAPI.creditCards. This module provides access to the following components:

  • Custom Form - you create your own form, and use the helper methods provided in QuickstreamAPI.creditCards to perform actions (such as retrieving a single-use-token)
  • Trusted Frame - automatically appends an iFrame containing a credit card form to your page. You don’t host the credit card form (we do), so your PCI DSS obligations are minimised.

Custom Form

The Custom Form component of QuickstreamAPI.creditCards allows you to mark the credit card form inputs in your HTML using data attributes, and then easily perform the following actions via the provided helper functions:

  • Validating credit card details your customer has entered into a form
  • Generating a single-use-token from these details
  • Appending the token to the form as a hidden field
  • Appending any errors encountered when trying to create the token to the form

Form Structure

You have the flexibility to create, structure and style your credit card form however you like. All you need to do to allow QuickstreamAPI.creditCards to extract credit card details from your form is to add the appropriate data-quickstream-api attributes to your form inputs.

The required attributes are:

Attribute Name/Value Description
data-quickstream-api="cardholderName" Apply to the input that the customer enters their cardholder name into.
data-quickstream-api="cardNumber" Apply to the input that the customer enters their credit card number into.
data-quickstream-api="expiryDateMonth" Apply to the input that the customer enters their card’s expiry month into.
data-quickstream-api="expiryDateYear" Apply to the input that the customer enters their card’s expiry year into.
data-quickstream-api="cvn" Apply to the input that the customer enters their card verification number into.

EXAMPLE

This is an example form containing the required attributes.

<form method="POST" action="/MakePayment">
    <div class="field">
        <label>Cardholder Name:</label>
        <input type="text" data-quickstream-api="cardholderName"/>
    </div>

    <div class="field">
        <label>Card Number:</label>
        <input type="text" data-quickstream-api="cardNumber"/>
    </div>

    <div class="field">
        <label>Expiry Date:</label>
        <input type="text" data-quickstream-api="expiryDateMonth"/>
        <input type="text" data-quickstream-api="expiryDateYear"/>
    </div>

    <div class="field">
        <label>CVN:</label>
        <input type="text" data-quickstream-api="cvn"/>
    </div>

    <button type="submit">Make Payment</button>
</form>

getToken( form, supplierBusinessCode, callback ) → void

Used to obtain a single-use-token that encapsulates your customer’s credit card information. This token can subsequently be passed to the QuickStream server in a REST API request to perform a transaction (see Transactions API).

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the credit card form on your page. This is the form your customer has entered their credit card details into.
supplierBusinessCode string The supplier business code that uniquely identifies the supplier business in the QuickStream system that you wish to generate the token for. For more information, see Single-Use-Tokens API.
callback callback The callback function that is executed after receiving the response from the REST request.

When there are no errors, the data parameter of callback has the following form:

{
    singleUseToken: {
        singleUseTokenId: "TOKEN_VALUE"
        accountType: "CREDIT_CARD"
        creditCard: {
            cardNumber: "424242...242"
            expiryDateMonth: "01"
            expiryDateYear: "17"
            cardScheme: "VISA"
            cardType: "CREDIT"
            cardholderName: "Jane Smith"
            surchargePercentage: "0.400"
        }
    }
    form: form
    token: "TOKEN_VALUE"
}

Where form is the HTMLFormElement originally provided to this function, and singleUseToken.singleUseTokenId is the generated single-use-token string.

Note: The token field has been deprecated in favour of using singleUseToken.singleUseTokenId.

EXAMPLE

QuickstreamAPI.creditCards.getToken( form, "SUPPLIER_CODE", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( data.singleUseToken.singleUseTokenId ); // Outputs single-use-token string to browser console
    }
} );

getAcceptedCards( supplierBusinessCode, callback ) → void

This function can be used to obtain a list of credit card schemes that are accepted by the business uniquely identified by supplierBusinessCode. This function performs a REST request to access this information (see Businesses API for more details).

PARAMETERS

Name Type Attributes Description
supplierBusinessCode string The supplier business code that uniquely identifies the supplier business in the QuickStream system that you wish to generate the token for. For more information, see Single-Use-Tokens API.
callback callback The callback function that is executed after receiving the response from the REST request.

When there are no errors, the data parameter of callback has the following form:

[
    {
        cardScheme: "VISA"
    },
    {
        cardScheme: "MASTERCARD"
    }
]

EXAMPLE

QuickstreamAPI.creditCards.getAcceptedCards( "SUPPLIER_CODE", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        data.forEach( function( current ) {
            console.log( current.cardScheme );

            // Example output:
            // VISA
            // MASTERCARD
            // AMEX
        } );
    }
} );

getCardScheme( form, callback ) → void

This function can be used to determine the scheme of the credit card number your customer has entered into the credit card form on your page.

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the credit card form on your page. This is the form your customer has entered their credit card details into.

form will be inspected for an input with the data-quickstream-api='cardNumber' attribute. The value of this input will be used to determine the card scheme.

callback callback The callback function that is executed after receiving the response from the REST request.

When there are no errors, the data parameter of callback is a string representing the card scheme, and can have one of the following values:

  • "VISA"
  • "MASTERCARD"
  • "AMEX"
  • "DINERS"
  • "JCB"
  • "UNIONPAY"

EXAMPLE

QuickstreamAPI.creditCards.getCardScheme( form, function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( data ); // Writes the card scheme to the browser console, e.g. "MASTERCARD"
    }
} );

validateCardNumber( form, callback ) → void

You can use this function to validate the credit card number your customer has entered into your credit card form. This function will use the Luhn Algorithm to determine whether the credit card value is valid or invalid.

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the credit card form on your page. This is the form your customer has entered their credit card details into.

form will be inspected for an input with the data-quickstream-api='cardNumber' attribute. The value of this input will be validated using the Luhn Algorithm.

callback callback The callback function that is executed after validation is performed.

The data parameter of callback has the following form:

{
    isValid: true,
}

Where isValid is a boolean value describing whether the input value was valid or invalid.

EXAMPLE

QuickstreamAPI.creditCards.validateCardNumber( form, function( errors, data ) {
    console.log( data.isValid ); // Example output: false
} );

validateExpiryDate( form, callback ) → void

You can use this function to validate the expiry date your customer has entered into your credit card form. Expiry dates are valid if the entered month/year are valid values, and the entered month/year is not in the past.

For example

Assuming the current date is 31st March, 2017:

  • 02/2017 is invalid
  • 03/2017 is valid
  • 04/2017 is valid

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the credit card form on your page. This is the form your customer has entered their credit card details into.

form will be inspected for inputs with the data-quickstream-api='expiryDateMonth' or data-quickstream-api='expiryDateYear' attributes. The month/year validation will be applied to the values of these inputs.

callback callback The callback function that is executed after validation is performed.

The data parameter of callback has the following form:

{
    isValid: true,
}

Where isValid is a boolean value describing whether the input values were valid or invalid.

EXAMPLE

QuickstreamAPI.creditCards.validateExpiryDate( form, function( errors, data ) {
    console.log( data.isValid ); // Example output: false
} );

validateCvn( form, callback ) → void

You can use this function to validate the card verification number your customer has entered into your credit card form. This function determines the card scheme from the credit card number entered by your customer, and then uses the card scheme’s CVN rules to validate the CVN value.

For example

Assuming the following credit-card-number / cvn pairs:

  • 4564710000000004 / 847 is valid
  • 376000000000006 / 2349 is valid
  • 5163200000000008 / 0700 is invalid

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the credit card form on your page. This is the form your customer has entered their credit card details into.

form will be inspected for inputs with the data-quickstream-api='cardNumber' or data-quickstream-api='cvn' attributes. The value of the credit card number input will be used to determine the card scheme, which in turn is used to validate the value of the CVN input.

callback callback The callback function that is executed after validation is performed.

The data parameter of callback has the following form:

{
    isValid: true,
}

Where isValid is a boolean value describing whether the input value was valid or invalid.

EXAMPLE

QuickstreamAPI.creditCards.validateCvn( form, function( errors, data ) {
    console.log( data.isValid ); // Example output: false
} );

appendErrors( form, errors ) → void

This helper function can be used to append error message to the appropriate fields in your credit card form. It is intended to be used in conjunction with callback.

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the credit card form on your page. This is the form your customer has entered their credit card details into.
errors array of Error An array of Error objects that describe the error messages to be attached to appropriate credit card form fields.

EXAMPLE

Given the following HTML structure and the call to appendErrors( form, errors ):

<form method="POST" action="/MakePayment">
    ...
    <div class="field">
        <label>Card Number:</label>
        <input type="text" data-quickstream-api="cardNumber"/>
    </div>

    <div class="field">
        <label>Expiry Date:</label>
        <input type="text" data-quickstream-api="expiryDateMonth"/>
        <input type="text" data-quickstream-api="expiryDateYear"/>
    </div>
    ...
</form>
QuickstreamAPI.creditCards.appendErrors( form, [
    {
        fieldName: "cardNumber",
        fieldValue: "12345",
        messages: [ "Invalid credit card number." ]
    },
    {
        fieldName: "expiryDateMonth",
        fieldValue: "89",
        messages: [ "Invalid expiry date." ]
    }
] );

The credit card form HTML will be modified as shown. Notice that the erroneous inputs receive an error class, and the error messages for each input are appended immediately after the element they’re associated with.

<form method="POST" action="/MakePayment">
    ...
    <div class="field">
        <label>Card Number:</label>
        <input type="text" class="error" data-quickstream-api="cardNumber"/>
        <div class="error" data-field-name="cardNumber">Invalid credit card number.</div>
    </div>

    <div class="field">
        <label>Expiry Date:</label>
        <input type="text" class="error" data-quickstream-api="expiryDateMonth"/>
        <div class="error" data-field-name="expiryDateMonth">Invalid expiry date.</div>
        <input type="text" data-quickstream-api="expiryDateYear"/>
    </div>
    ...
</form>

appendTokenToForm( form, singleUseTokenId ) → void

This helper function can be used to append the single-use-token string returned by getToken( form, supplierBusinessCode, callback ) to the credit card form as a hidden input value.

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the credit card form on your page. This is the form your customer has entered their credit card details into.
singleUseTokenId string The single-use-token string.

EXAMPLE

QuickstreamAPI.creditCards.appendTokenToForm( form, "TOKEN_VALUE" );

Will append the following HTML as the first child of form.

<input type="hidden" name="singleUseTokenId" value="TOKEN_VALUE"/>

Trusted Frame

The Trusted Frame component of QuickstreamAPI.creditCards automatically adds an iFrame containing a credit card form to your page. Since the credit card form is not hosted by you (it is hosted on our servers), your PCI DSS obligations are minimised.

You have the ability to configure the Trusted Frame on initialisation, and interact with the iFrame after initialisation. Using the provided helper functions, you can:

  • Clear fields
  • Change input placeholders
  • Change styles
  • Register event handlers for field events, including change, focus, blur and error

Continue reading for details on how to use Trusted Frame.

HTML Structure

You can place the Trusted Frame anywhere on your page. All you need to do is mark a block element with the data-quickstream-api="creditCardContainer" attribute so that the QuickstreamAPI.creditCards module knows where to append your Trusted Frame.

EXAMPLE

This is an example snippet containing the required attribute.

<div data-quickstream-api="creditCardContainer">
  <!-- The Trusted Frame will be inserted in here -->
</div>

createTrustedFrame( options, callback ) → TrustedFrameInstance

Used to initialise and append the Trusted Frame to your webpage.

PARAMETERS

Name Type Attributes Description
options TrustedFrameConfigObject A standard JavaScript object containing name/value pairs describing the configuration of the Trusted Frame. See TrustedFrameConfigObject for the structure and available values of this object.
callback callback The callback function that is executed after the initialisation of the Trusted Frame.

When there are no errors, the data parameter of callback has the following form:

{
    trustedFrame: TrustedFrameInstance
}

Where TrustedFrameInstance is an object containing helper functions for interacting with the created iFrame (including submitting the credit card form).

EXAMPLE

var trustedFrame;

var options = {
    config: {
        supplierBusinessCode: "SUPPLIER_CODE" // This is a required config option
    }
};

QuickstreamAPI.creditCards.createTrustedFrame( options, function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        trustedFrame = data.trustedFrame
    }
} );

TrustedFrameConfigObject

A JavaScript object that encapsulates the configuration data used to initialise a Trusted Frame. See the tables below for more details on the structure.

Property Type Required Default Description
config ConfigObject Required Contains required configuration values for Trusted Frame initialisation. See ConfigObject for more details.
iframe IframeObject Optional See IframeObject for the default values. Contains configuration values relating to the visual styling of the iFrame. This includes the width, height, scrollbar visibility and other supported CSS properties. See IframeObject for more details.
showAcceptedCards boolean Optional true Set to false to hide the accepted card logos.
body StyleableObject Optional Contains CSS properties for styling the body element of the Trusted Frame. This allows you to set font styles, color etc. that apply to the entire iFrame. See StyleableObject for more details.
labels StyleableObject Optional Contains CSS properties for styling the label elements of the Trusted Frame. This allows you to set font styles, padding, color etc. that apply to all labels in the iFrame. See StyleableObject for more details.
cardholderName HideableFieldObject Optional Contains configuration values relating to the appearance of the cardholder name form field. These include the ability to change the field’s visibility, label, placeholder, input type and CSS properties. See HideableFieldObject for more details.
cardNumber FieldObject Optional Contains configuration values relating to the appearance of the card number form field. These include the ability to change the field’s label, placeholder, input type and CSS properties. See FieldObject for more details.
expiryDateMonth ExpiryMonthFieldObject Optional Contains configuration values relating to the appearance of the expiry month form field. These include the ability to change the field’s label, option format, default option visibility and CSS properties. See ExpiryMonthFieldObject for more details.
expiryDateYear ExpiryYearFieldObject Optional Contains configuration values relating to the appearance of the expiry year form field. These include the ability to change the field’s label, default option visibility and CSS properties. See ExpiryYearFieldObject for more details.
cvn HideableFieldObject Optional Contains configuration values relating to the appearance of the CVN form field. These include the ability to change the field’s visibility, label, placeholder, input type and CSS properties. See HideableFieldObject for more details.
ConfigObject
Property Type Required Default Description
supplierBusinessCode string Required The supplier business code that uniquely identifies your supplier business in the QuickStream system.
IframeObject
Property Type Required Default Description
width int Optional 800 Integer that sets the width of the iFrame.
height int Optional 300 Integer that sets the height of the iFrame.
scrolling string Optional "no" String that determines whether the iFrame has visible scrollbars. Supported values are:
  • no
  • yes
  • auto
style StyleObject Optional Contains CSS properties used to style the iFrame. See StyleObject for more details.
StyleableObject
Property Type Required Default Description
style StyleObject Optional Contains CSS properties used to style the target element/s. See StyleObject for more details.
HideableFieldObject
Property Type Required Default Description
hidden boolean Optional false Set to true to hide the field.
label string Optional Replace the field’s default label with one of your choosing.
placeholder string Optional Specify a placeholder value for the target field.
inputType string Optional "text" Change the default input type to another. Supported values are as defined in the W3C Recommendation.
style StyleObject Optional Contains CSS properties used to style the target field. See StyleObject for more details.
FieldObject
Property Type Required Default Description
label string Optional Replace the field’s default label with one of your choosing.
placeholder string Optional Specify a placeholder value for the target field.
inputType string Optional "text" Change the default input type to another. Supported values are as defined in the W3C Recommendation.
style StyleObject Optional Contains CSS properties used to style the target field. See StyleObject for more details.
ExpiryMonthFieldObject
Property Type Required Default Description
label string Optional Replace the field’s default label with one of your choosing.
hideDefault boolean Optional false Set to true to hide the default expiry month value. This causes the first option (01 - January) to be auto-selected.
optionFormat string Optional "NUMBER" Change the format that expiry month options are presented in. Supported values are:
  • NUMBER
  • NAME
style StyleObject Optional Contains CSS properties used to style the expiry month field. See StyleObject for more details.
ExpiryYearFieldObject
Property Type Required Default Description
label string Optional Replace the field’s default label with one of your choosing.
hideDefault boolean Optional false Set to true to hide the default expiry year value. This causes the first option (current year) to be auto-selected.
style StyleObject Optional Contains CSS properties used to style the expiry year field. See StyleObject for more details.
StyleObject
Property Type Required Default Description
"css-property-name" string Optional Each name/value pair in this object map directly to CSS property/value pairs. For example, a valid instance of StyleObject could look like the following:
{
    "border-color": "green"
    padding: "5px"
}

The supported CSS properties are:

  • appearance
  • background
  • background-attachment
  • background-blend-mode
  • background-clip
  • background-color
  • background-image
  • background-origin
  • background-position
  • background-repeat
  • background-size
  • border
  • border-block-end
  • border-block-end-color
  • border-block-end-style
  • border-block-end-width
  • border-block-start
  • border-block-start-color
  • border-block-start-style
  • border-block-start-width
  • border-bottom
  • border-bottom-color
  • border-bottom-left-radius
  • border-bottom-right-radius
  • border-bottom-style
  • border-bottom-width
  • border-collapse
  • border-color
  • border-image
  • border-image-outset
  • border-image-repeat
  • border-image-slice
  • border-image-source
  • border-image-width
  • border-inline-end
  • border-inline-end-color
  • border-inline-end-style
  • border-inline-end-width
  • border-inline-start
  • border-inline-start-color
  • border-inline-start-style
  • border-inline-start-width
  • border-left
  • border-left-color
  • border-left-style
  • border-left-width
  • border-radius
  • border-right
  • border-right-color
  • border-right-style
  • border-right-width
  • border-spacing
  • border-style
  • border-top
  • border-top-color
  • border-top-left-radius
  • border-top-right-radius
  • border-top-style
  • border-top-width
  • border-width
  • bottom
  • box-shadow
  • box-sizing
  • color
  • direction
  • display
  • font
  • font-family
  • font-size
  • font-size-adjust
  • font-stretch
  • font-style
  • font-variant
  • font-variant-alternates
  • font-variant-caps
  • font-variant-east-asian
  • font-variant-ligatures
  • font-variant-numeric
  • font-variant-position
  • font-weight
  • height
  • left
  • letter-spacing
  • line-height
  • margin
  • margin-block-end
  • margin-block-start
  • margin-bottom
  • margin-inline-end
  • margin-inline-start
  • margin-left
  • margin-right
  • margin-top
  • max-height
  • max-width
  • min-height
  • min-width
  • opacity
  • outline
  • outline-color
  • outline-offset
  • outline-style
  • outline-width
  • overflow
  • overflow-wrap
  • overflow-x
  • overflow-y
  • padding
  • padding-bottom
  • padding-left
  • padding-right
  • padding-top
  • position
  • right
  • text-align
  • text-decoration
  • text-decoration-color
  • text-decoration-line
  • text-decoration-style
  • text-emphasis
  • text-emphasis-color
  • text-emphasis-position
  • text-emphasis-style
  • text-indent
  • text-orientation
  • text-overflow
  • text-shadow
  • text-transform
  • text-underline-position
  • top
  • transform
  • transform-box
  • transform-origin
  • transform-style
  • transition
  • transition-delay
  • transition-duration
  • transition-property
  • transition-timing-function
  • vertical-align
  • white-space
  • width
  • word-break
  • word-spacing
  • word-wrap
  • z-index

TrustedFrameInstance

The TrustedFrameInstance allows you to interact with the Trusted Frame and the credit card form within it. The following functions are available:

clearField( fieldName, callback ) → void

Use this function to clear the contents of a field.

PARAMETERS

Name Type Description
fieldName string The name of the field that you would like to clear. Available field names are:
  • cardholderName
  • cardNumber
  • expiryDateMonth
  • expiryDateYear
  • cvn
callback callback A callback function to be executed after sending the action message to the Trusted Frame.

EXAMPLE

trustedFrame.clearField( "cardNumber", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "cardNumber has been cleared!" );
    }
} );
changePlaceholder( fieldName, placeholder, callback ) → void

Allows you to change the placeholder text of a field input.

PARAMETERS

Name Type Description
fieldName string The name of the field for which you would like to set the placeholder text. Available field names are:
  • cardholderName
  • cardNumber
  • expiryDateMonth
  • expiryDateYear
  • cvn
placeholder string Your chosen placeholder text.
callback callback A callback function to be executed after sending the action message to the Trusted Frame.

EXAMPLE

trustedFrame.changePlaceholder( "cardholderName", "John Smith", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "cardholderName placeholder has been changed!" );
    }
} );
changeStyle( elementName, style, callback ) → void

Apply your choice of supported CSS properties to the chosen Trusted Frame element.

PARAMETERS

Name Type Description
elementName string The name of the element to which you would like to apply the specified CSS properties. Available element names are:
  • body
  • labels
  • cardholderName
  • cardNumber
  • expiryDateMonth
  • expiryDateYear
  • cvn
style StyleObject Contains CSS properties used to style the target element/s. See StyleObject for more details.
callback callback A callback function to be executed after sending the action message to the Trusted Frame.

EXAMPLE

var style = {
    color: "blue",
    "margin-right": "25px"
};

trustedFrame.changeStyle( "labels", style, function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "labels styling has been changed!" );
    }
} );
setEventHandler( fieldName, event, handler ) → void

Allows you to trigger a handler function when a specified event occurs for a field.

PARAMETERS

Name Type Description
fieldName string The name of the field for which you would like to register the event handler function. Available field names are:
  • cardholderName
  • cardNumber
  • expiryDateMonth
  • expiryDateYear
  • cvn
event string The event type that should trigger the event handler function. Available event types are:
  • focus
  • change
  • error
  • blur
handler function A function to be executed when an event occurs.

For focus, change and blur events, the argument passed to handler has the following form:

{
    eventType: "focus"
    fieldName: "cardNumber"
}

For the error event, the argument passed to handler has the form:

{
    eventType: "error"
    fieldName: "cvn"
    errorMessages: [ "Required field." ]
}

EXAMPLE

trustedFrame.setEventHandler( "cvn", "error", function( event ) {
    console.log( event.fieldName + ": " + event.errorMessages[0] ); // cvn: Required field.
} );
getEventHandlers() → EventHandlersObject

Returns an EventHandlersObject that contains all of the event handlers registered to the Trusted Frame. The EventHandlersObject has the following form:

{
    cardNumber: {
        focus: function( event ) { ... },
        blur: function( event ) { ... }
    },
    expiryDateMonth: {
        error: function( event ) { ... }
    },
    cvn : {
        change: function( event ) { ... }
    }
}

Where first-level properties are named after the fields, second-level properties are the events for that field, and the values of these the event handlers that are triggered.

submitForm( callback ) → void

Submits the credit card form within the Trusted Frame. You can provide a callback function which will receive either the field errors (if the form fails validation), or the generated single-use-token.

PARAMETERS

Name Type Description
callback callback A callback function to be executed after receiving the results of the credit card form submission.

When there are no errors, the data parameter of callback has the following form:

{
    singleUseToken: {
        singleUseTokenId: "TOKEN_VALUE"
        accountType: "CREDIT_CARD"
        creditCard: {
            cardNumber: "424242...242"
            expiryDateMonth: "01"
            expiryDateYear: "17"
            cardScheme: "VISA"
            cardType: "CREDIT"
            cardholderName: "Jane Smith"
            surchargePercentage: "0.400"
        }
    }
    token: "TOKEN_VALUE"
}

Note: The token field has been deprecated in favour of using singleUseTokenId.

EXAMPLE

trustedFrame.submitForm( function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "singleUseTokenId is " + data.singleUseToken.singleUseTokenId ); // singleUseTokenId is TOKEN_VALUE
    }
} );
teardown( callback ) → void

Call this function to destroy and remove the Trusted Frame from your webpage. Once a Trusted Frame has been torn down, it can no longer be used. Subsequent calls to other Trusted Frame functions will result in an error message.

PARAMETERS

Name Type Description
callback callback A callback function to be executed after the Trusted Frame has been destroyed.

EXAMPLE

trustedFrame.teardown( function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "Trusted Frame has been destroyed." );
    }
} );

Bank Accounts Module

QuickstreamAPI provides a Bank Accounts module, which can accessed via QuickstreamAPI.bankAccounts. This module provides access to the following components:

  • Custom Form - you create your own form, and use the helper methods provided in QuickstreamAPI.bankAccounts to perform actions (such as retrieving a single-use-token)
  • Trusted Frame - automatically appends an iFrame containing a bank account form to your page.

Custom Form

The Custom Form component of QuickstreamAPI.bankAccounts allows you to mark the bank account form inputs in your HTML using data attributes, and then easily perform the following actions via the provided helper functions:

  • Validating bank account details your customer has entered into a form
  • Generating a single-use-token from these details
  • Appending the token to the form as a hidden field
  • Appending any errors encountered when trying to create the token to the form

Form Structure

You have the flexibility to create, structure and style your bank account form however you like. All you need to do to allow QuickstreamAPI.bankAccounts to extract bank account details from your form is to add the appropriate data-quickstream-api attributes to your form inputs.

The required attributes are:

Attribute Name/Value Description
data-quickstream-api="accountName" Apply to the input that the customer enters their account name into.
data-quickstream-api="bsb" Apply to the input that the customer enters their bsb number into.
data-quickstream-api="accountNumber" Apply to the input that the customer enters their account number into.

EXAMPLE

This is an example form containing the required attributes.

<form method="POST" action="/MakePayment">
    <div class="field">
        <label>Account Name:</label>
        <input type="text" data-quickstream-api="accountName"/>
    </div>

    <div class="field">
        <label>BSB:</label>
        <input type="text" data-quickstream-api="bsb"/>
    </div>

    <div class="field">
        <label>Account Number:</label>
        <input type="text" data-quickstream-api="accountNumber"/>
    </div>

    <button type="submit">Make Payment</button>
</form>

getToken( form, supplierBusinessCode, callback ) → void

Used to obtain a single-use-token that encapsulates your customer’s bank account information. This token can subsequently be passed to the QuickStream server in a REST API request to perform a transaction (see Transactions API).

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the bank account form on your page. This is the form your customer has entered their bank account details into.
supplierBusinessCode string The supplier business code that uniquely identifies the supplier business in the QuickStream system that you wish to generate the token for. For more information, see Single-Use-Tokens API.
callback callback The callback function that is executed after receiving the response from the REST request.

When there are no errors, the data parameter of callback has the following form:

{
    singleUseToken: {
        singleUseTokenId: "TOKEN_VALUE"
        accountType: "DIRECT_DEBIT"
        bankAccount: {
            bsb: "xxx-000"
            accountNumber: "xxx007"
            accountName: "Jane Smith"
        }
    }
    form: form
    token: "TOKEN_VALUE"
}

Where form is the HTMLFormElement originally provided to this function, and singleUseToken.singleUseTokenId is the generated single-use-token string.

Note: The token field has been deprecated in favour of using singleUseToken.singleUseTokenId.

EXAMPLE

QuickstreamAPI.bankAccounts.getToken( form, "SUPPLIER_CODE", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( data.singleUseToken.singleUseTokenId ); // Outputs single-use-token string to browser console
    }
} );

validateBsb( form, callback ) → void

You can use this function to perform basic validation on the BSB your customer has entered into your bank account form.

For example

Assuming the following BSBs:

  • 032050 is valid
  • 032-050 is valid
  • 32-50 is invalid

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the bank account form on your page. This is the form your customer has entered their bank account details into.

form will be inspected for an input with the data-quickstream-api='bsb' attribute.

callback callback The callback function that is executed after validation is performed.

The data parameter of callback has the following form:

{
    isValid: true,
}

Where isValid is a boolean value describing whether the input value was valid or invalid.

EXAMPLE

QuickstreamAPI.bankAccounts.validateBsb( form, function( errors, data ) {
    console.log( data.isValid ); // Example output: false
} );

validateAccountNumber( form, callback ) → void

You can use this function to perform basic validation on the bank account number your customer has entered into your bank account form.

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the bank account form on your page. This is the form your customer has entered their bank account details into.

form will be inspected for an input with the data-quickstream-api='accountNumber' attribute.

callback callback The callback function that is executed after validation is performed.

The data parameter of callback has the following form:

{
    isValid: true,
}

Where isValid is a boolean value describing whether the input value was valid or invalid.

EXAMPLE

QuickstreamAPI.bankAccounts.validateAccountNumber( form, function( errors, data ) {
    console.log( data.isValid ); // Example output: false
} );

appendErrors( form, errors ) → void

This helper function can be used to append error message to the appropriate fields in your bank account form. It is intended to be used in conjunction with callback.

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the bank account form on your page. This is the form your customer has entered their bank account details into.
errors array of Error An array of Error objects that describe the error messages to be attached to appropriate bank account form fields.

EXAMPLE

Given the following HTML structure and the call to appendErrors( form, errors ):

<form method="POST" action="/MakePayment">
    ...
    <div class="field">
        <label>BSB:</label>
        <input type="text" data-quickstream-api="bsb"/>
    </div>

    <div class="field">
        <label>Account Number:</label>
        <input type="text" data-quickstream-api="accountNumber"/>
    </div>
    ...
</form>
QuickstreamAPI.bankAccounts.appendErrors( form, [
    {
        fieldName: "bsb",
        fieldValue: "abc",
        messages: [ "Invalid BSB" ]
    },
    {
        fieldName: "accountNumber",
        fieldValue: "xyzabc",
        messages: [ "Invalid number." ]
    }
] );

The bank account form HTML will be modified as shown. Notice that the erroneous inputs receive an error class, and the error messages for each input are appended immediately after the element they’re associated with.

<form method="POST" action="/MakePayment">
    ...
    <div class="field">
        <label>BSB:</label>
        <input type="text" class="error" data-quickstream-api="bsb"/>
        <div class="error" data-field-name="bsb">Invalid BSB</div>
    </div>

    <div class="field">
        <label>Account Number:</label>
        <input type="text" class="error" data-quickstream-api="accountNumber"/>
        <div class="error" data-field-name="accountNumber">Invalid number.</div>
    </div>
    ...
</form>

appendTokenToForm( form, token ) → void

This helper function can be used to append the single-use-token string returned by getToken( form, supplierBusinessCode, callback ) to the bank account form as a hidden input value.

PARAMETERS

Name Type Attributes Description
form HTMLFormElement The HTMLFormElement that represents the bank account form on your page. This is the form your customer has entered their bank account details into.
token string The single-use-token string.

EXAMPLE

QuickstreamAPI.bankAccounts.appendTokenToForm( form, "TOKEN_VALUE" );

Will append the following HTML as the first child of form.

<input type="hidden" name="singleUseTokenId" value="TOKEN_VALUE"/>

Trusted Frame

The Trusted Frame component of QuickstreamAPI.bankAccounts automatically adds an iFrame containing a bank account form to your page.

You have the ability to configure the Trusted Frame on initialisation, and interact with the iFrame after initialisation. Using the provided helper functions, you can:

  • Clear fields
  • Change input placeholders
  • Change styles
  • Register event handlers for field events, including change, focus, blur and error

Continue reading for details on how to use Trusted Frame.

HTML Structure

You can place the Trusted Frame anywhere on your page. All you need to do is mark a block element with the data-quickstream-api="bankAccountContainer" attribute so that the QuickstreamAPI.bankAccounts module knows where to append your Trusted Frame.

EXAMPLE

This is an example snippet containing the required attribute.

<div data-quickstream-api="bankAccountContainer">
  <!-- The Trusted Frame will be inserted in here -->
</div>

createTrustedFrame( options, callback ) → TrustedFrameInstance

Used to initialise and append the Trusted Frame to your webpage.

PARAMETERS

Name Type Attributes Description
options TrustedFrameConfigObject A standard JavaScript object containing name/value pairs describing the configuration of the Trusted Frame. See TrustedFrameConfigObject for the structure and available values of this object.
callback callback The callback function that is executed after the initialisation of the Trusted Frame.

When there are no errors, the data parameter of callback has the following form:

{
    trustedFrame: TrustedFrameInstance
}

Where TrustedFrameInstance is an object containing helper functions for interacting with the created iFrame (including submitting the bank account form).

EXAMPLE

var trustedFrame;

var options = {
    config: {
        supplierBusinessCode: "SUPPLIER_CODE" // This is a required config option
    }
};

QuickstreamAPI.bankAccounts.createTrustedFrame( options, function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        trustedFrame = data.trustedFrame
    }
} );

TrustedFrameConfigObject

A JavaScript object that encapsulates the configuration data used to initialise a Trusted Frame. See the tables below for more details on the structure.

Property Type Required Default Description
config ConfigObject Required Contains required configuration values for Trusted Frame initialisation. See ConfigObject for more details.
iframe IframeObject Optional See IframeObject for the default values. Contains configuration values relating to the visual styling of the iFrame. This includes the width, height, scrollbar visibility and other supported CSS properties. See IframeObject for more details.
body StyleableObject Optional Contains CSS properties for styling the body element of the Trusted Frame. This allows you to set font styles, color etc. that apply to the entire iFrame. See StyleableObject for more details.
labels StyleableObject Optional Contains CSS properties for styling the label elements of the Trusted Frame. This allows you to set font styles, padding, color etc. that apply to all labels in the iFrame. See StyleableObject for more details.
accountName FieldObject Optional Contains configuration values relating to the appearance of the account name form field. These include the ability to change the field’s label, placeholder, input type and CSS properties. See FieldObject for more details.
bsb FieldObject Optional Contains configuration values relating to the appearance of the BSB form field. These include the ability to change the field’s label, placeholder, input type and CSS properties. See FieldObject for more details.
accountNumber FieldObject Optional Contains configuration values relating to the appearance of the account number form field. These include the ability to change the field’s label, placeholder, input type and CSS properties. See FieldObject for more details.
ConfigObject
Property Type Required Default Description
supplierBusinessCode string Required The supplier business code that uniquely identifies your supplier business in the QuickStream system.
IframeObject
Property Type Required Default Description
width int Optional 800 Integer that sets the width of the iFrame.
height int Optional 300 Integer that sets the height of the iFrame.
scrolling string Optional "no" String that determines whether the iFrame has visible scrollbars. Supported values are:
  • no
  • yes
  • auto
style StyleObject Optional Contains CSS properties used to style the iFrame. See StyleObject for more details.
StyleableObject
Property Type Required Default Description
style StyleObject Optional Contains CSS properties used to style the target element/s. See StyleObject for more details.
FieldObject
Property Type Required Default Description
label string Optional Replace the field’s default label with one of your choosing.
placeholder string Optional Specify a placeholder value for the target field.
inputType string Optional "text" Change the default input type to another. Supported values are as defined in the W3C Recommendation.
style StyleObject Optional Contains CSS properties used to style the target field. See StyleObject for more details.
StyleObject
Property Type Required Default Description
"css-property-name" string Optional Each name/value pair in this object map directly to CSS property/value pairs. For example, a valid instance of StyleObject could look like the following:
{
    "border-color": "green"
    padding: "5px"
}

The supported CSS properties are:

  • appearance
  • background
  • background-attachment
  • background-blend-mode
  • background-clip
  • background-color
  • background-image
  • background-origin
  • background-position
  • background-repeat
  • background-size
  • border
  • border-block-end
  • border-block-end-color
  • border-block-end-style
  • border-block-end-width
  • border-block-start
  • border-block-start-color
  • border-block-start-style
  • border-block-start-width
  • border-bottom
  • border-bottom-color
  • border-bottom-left-radius
  • border-bottom-right-radius
  • border-bottom-style
  • border-bottom-width
  • border-collapse
  • border-color
  • border-image
  • border-image-outset
  • border-image-repeat
  • border-image-slice
  • border-image-source
  • border-image-width
  • border-inline-end
  • border-inline-end-color
  • border-inline-end-style
  • border-inline-end-width
  • border-inline-start
  • border-inline-start-color
  • border-inline-start-style
  • border-inline-start-width
  • border-left
  • border-left-color
  • border-left-style
  • border-left-width
  • border-radius
  • border-right
  • border-right-color
  • border-right-style
  • border-right-width
  • border-spacing
  • border-style
  • border-top
  • border-top-color
  • border-top-left-radius
  • border-top-right-radius
  • border-top-style
  • border-top-width
  • border-width
  • bottom
  • box-shadow
  • box-sizing
  • color
  • direction
  • display
  • font
  • font-family
  • font-size
  • font-size-adjust
  • font-stretch
  • font-style
  • font-variant
  • font-variant-alternates
  • font-variant-caps
  • font-variant-east-asian
  • font-variant-ligatures
  • font-variant-numeric
  • font-variant-position
  • font-weight
  • height
  • left
  • letter-spacing
  • line-height
  • margin
  • margin-block-end
  • margin-block-start
  • margin-bottom
  • margin-inline-end
  • margin-inline-start
  • margin-left
  • margin-right
  • margin-top
  • max-height
  • max-width
  • min-height
  • min-width
  • opacity
  • outline
  • outline-color
  • outline-offset
  • outline-style
  • outline-width
  • overflow
  • overflow-wrap
  • overflow-x
  • overflow-y
  • padding
  • padding-bottom
  • padding-left
  • padding-right
  • padding-top
  • position
  • right
  • text-align
  • text-decoration
  • text-decoration-color
  • text-decoration-line
  • text-decoration-style
  • text-emphasis
  • text-emphasis-color
  • text-emphasis-position
  • text-emphasis-style
  • text-indent
  • text-orientation
  • text-overflow
  • text-shadow
  • text-transform
  • text-underline-position
  • top
  • transform
  • transform-box
  • transform-origin
  • transform-style
  • transition
  • transition-delay
  • transition-duration
  • transition-property
  • transition-timing-function
  • vertical-align
  • white-space
  • width
  • word-break
  • word-spacing
  • word-wrap
  • z-index

TrustedFrameInstance

The TrustedFrameInstance allows you to interact with the Trusted Frame and the credit card form within it. The following functions are available:

clearField( fieldName, callback ) → void

Use this function to clear the contents of a field.

PARAMETERS

Name Type Description
fieldName string The name of the field that you would like to clear. Available field names are:
  • accountName
  • bsb
  • accountNumber
callback callback A callback function to be executed after sending the action message to the Trusted Frame.

EXAMPLE

trustedFrame.clearField( "bsb", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "bsb has been cleared!" );
    }
} );
changePlaceholder( fieldName, placeholder, callback ) → void

Allows you to change the placeholder text of a field input.

PARAMETERS

Name Type Description
fieldName string The name of the field for which you would like to set the placeholder text. Available field names are:
  • accountName
  • bsb
  • accountNumber
placeholder string Your chosen placeholder text.
callback callback A callback function to be executed after sending the action message to the Trusted Frame.

EXAMPLE

trustedFrame.changePlaceholder( "accountName", "John Smith", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "accountName placeholder has been changed!" );
    }
} );
changeStyle( elementName, style, callback ) → void

Apply your choice of supported CSS properties to the chosen Trusted Frame element.

PARAMETERS

Name Type Description
elementName string The name of the element to which you would like to apply the specified CSS properties. Available element names are:
  • body
  • labels
  • accountName
  • bsb
  • accountNumber
style StyleObject Contains CSS properties used to style the target element/s. See StyleObject for more details.
callback callback A callback function to be executed after sending the action message to the Trusted Frame.

EXAMPLE

var style = {
    color: "blue",
    "margin-right": "25px"
};

trustedFrame.changeStyle( "labels", style, function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "labels styling has been changed!" );
    }
} );
setEventHandler( fieldName, event, handler ) → void

Allows you to trigger a handler function when a specified event occurs for a field.

PARAMETERS

Name Type Description
fieldName string The name of the field for which you would like to register the event handler function. Available field names are:
  • accountName
  • bsb
  • accountNumber
event string The event type that should trigger the event handler function. Available event types are:
  • focus
  • change
  • error
  • blur
handler function A function to be executed when an event occurs.

For focus, change and blur events, the argument passed to handler has the following form:

{
    eventType: "focus"
    fieldName: "accountNumber"
}

For the error event, the argument passed to handler has the form:

{
    eventType: "error"
    fieldName: "bsb"
    errorMessages: [ "Required field." ]
}

EXAMPLE

trustedFrame.setEventHandler( "bsb", "error", function( event ) {
    console.log( event.fieldName + ": " + event.errorMessages[0] ); // bsb: Required field.
} );
getEventHandlers() → EventHandlersObject

Returns an EventHandlersObject that contains all of the event handlers registered to the Trusted Frame. The EventHandlersObject has the following form:

{
    accountName: {
        focus: function( event ) { ... },
        blur: function( event ) { ... }
    },
    bsb: {
        error: function( event ) { ... }
    },
    accountNumber : {
        change: function( event ) { ... }
    }
}

Where first-level properties are named after the fields, second-level properties are the events for that field, and the values of these the event handlers that are triggered.

submitForm( callback ) → void

Submits the bank account form within the Trusted Frame. You can provide a callback function which will receive either the field errors (if the form fails validation), or the generated single-use-token.

PARAMETERS

Name Type Description
callback callback A callback function to be executed after receiving the results of the bank account form submission.

When there are no errors, the data parameter of callback has the following form:

{
    singleUseToken: {
        singleUseTokenId: "TOKEN_VALUE"
        accountType: "DIRECT_DEBIT"
        bankAccount: {
            bsb: "xxx-000"
            accountNumber: "xxx007"
            accountName: "Jane Smith"
        }
    }
    token: "TOKEN_VALUE"
}

Note: The token field has been deprecated in favour of using singleUseTokenId.

EXAMPLE

trustedFrame.submitForm( function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "singleUseTokenId is " + data.singleUseToken.singleUseTokenId ); // singleUseTokenId is TOKEN_VALUE
    }
} );
teardown( callback ) → void

Call this function to destroy and remove the Trusted Frame from your webpage. Once a Trusted Frame has been torn down, it can no longer be used. Subsequent calls to other Trusted Frame functions will result in an error message.

PARAMETERS

Name Type Description
callback callback A callback function to be executed after the Trusted Frame has been destroyed.

EXAMPLE

trustedFrame.teardown( function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( "Trusted Frame has been destroyed." );
    }
} );