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
• paymentRequestButton

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

EXAMPLE

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

callback( errors ) → void

This callback function will receive a list of errors if the calling function fails, and the function will not be invoked if the calling function is successful.

PARAMETERS

EXAMPLE

let callback = function( errors ) {
    // Perform error handling here
}

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

EXAMPLE

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

init( data ) → void

This is used to initialise the library.

PARAMETERS

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-quickstream-api 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:

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

{
    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"
}

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

[
    {
        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

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

getCardSchemeSurchargeRate( form, supplierBusinessCode, callback ) → void

You can use this function to get the surcharge rate for the credit card number your customer has entered into your credit card form.

PARAMETERS

{
    cardNumber: "111111...111",
    messages: ["Invalid card number."]
}

EXAMPLE

QuickstreamAPI.creditCards.getCardSchemeSurchargeRate( form, "SUPPLIER_CODE", function( errors, data ) {
    if ( errors ) {
        // Handle errors here
    }
    else {
        console.log( data );
        // Example output:
        // { 
        //    "links": [],
        //    "cardScheme": "VISA",
        //    "cardType": "CREDIT",
        //    "surchargePercentage": "0.400"
        // }
    }
} );

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

{
    isValid: true,
}

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

{
    isValid: true,
}

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

{
    isValid: true,
}

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

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

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 card form to your page. Since the 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

{
    trustedFrame: TrustedFrameInstance
}

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.

ConfigObject

IframeObject

StyleableObject

HideableFieldObject

FieldObject

ExpiryMonthFieldObject

ExpiryYearFieldObject

CvnFieldObject

StyleObject

{
    "border-color": "green"
    padding: "5px"
}

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
• changePlaceholder( fieldName, placeholder, callback ) → void
• changeStyle( elementName, style, callback ) → void
• setEventHandler( fieldName, event, handler ) → void
• getEventHandlers() → EventHandlersObject
• submitForm( callback ) → void
• teardown( callback ) → void

clearField( fieldName, callback ) → void

Use this function to clear the contents of a field.

PARAMETERS

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

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

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

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

{
    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

{
    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"
}

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

EXAMPLE

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

Challenge Frame

The Challenge Frame component of QuickstreamAPI.creditCards automatically adds an iFrame containing a 3D Secure challenge to your form.

The Challenge Frame is initialised using a singleUseTokenId that you have posted to the 3D Secure Authentication endpoint and received a transStatus value of C (indicating that you must challenge the cardholder.)

The iFrame content is served by the card issuer, and the content is not customisable. However, you can choose where to display it on your webpage and the size of the window.

HTML structure

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

EXAMPLE

This is an example snippet containing the required attribute.

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

The Challenge Frame works in two modes:

• challengeMode is post (default)
• challengeMode is callback.

When challengeMode is post the container must be a child of a form element. When the cardholder completes the challenge, a hidden input field is appended to the encapsulating form. The hidden input has the name attribute transStatus and the value is either Y (successfully completed the challenge) or N (challenge failed).

<form id="challenge-form">
  <div data-quickstream-api="quickstream-challenge"></div>
</form>

When challengeMode is callback the container does not need to be a child of a form element. You must implement two callback functions:

• onSuccess() - called when cardholder successfully completes the challenge.
• onFaliure() - called when the cardholder fails the challenge.

createChallengeFrame( options, callback ) → ChallengeFrameInstance

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

PARAMETERS

EXAMPLE

let challengeFrame;
let transStatus;
let options = {
  singleUseTokenId: "SINGLE_USE_TOKEN_ID", // this is a required config option
  challengeWindowSize: "02",
  challengeMode: "callback",
  onSuccess: function(){
    // remove the challenge iframe and handle success
    challengeFrame.destroy();
    transStatus= "Y";
  },
  onFailure: function(){
    // remove the challenge iframe and handle failure
    challengeFrame.destroy();
    transStatus= "N";
  }
};

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

ChallengeFrameConfigObject

Used to initialise the Challenge Frame to your webpage.

PARAMETERS

ChallengeFrameInstance

The ChallengeFrameInstance allows you to interact with the Challenge Frame. The following functions are available:

• destroy( callback ) → void

destroy( callback ) → void

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

PARAMETERS

None.

EXAMPLE

challengeFrame.destroy();

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-quickstream-api 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:

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

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

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

{
    isValid: true,
}

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

{
    isValid: true,
}

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

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

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

{
    trustedFrame: TrustedFrameInstance
}

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.

ConfigObject

IframeObject

StyleableObject

FieldObject

StyleObject

{
    "border-color": "green"
    padding: "5px"
}

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
• changePlaceholder( fieldName, placeholder, callback ) → void
• changeStyle( elementName, style, callback ) → void
• setEventHandler( fieldName, event, handler ) → void
• getEventHandlers() → EventHandlersObject
• submitForm( callback ) → void
• teardown( callback ) → void

clearField( fieldName, callback ) → void

Use this function to clear the contents of a field.

PARAMETERS

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

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

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

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

{
    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

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

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

EXAMPLE

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

Payment request button module

QuickstreamAPI provides a Payment Request Button module, which can be accessed via QuickstreamAPI.paymentRequestButton. This module allows you to add an Apple Pay and Google Pay button to your page. When the user clicks this button a payment sheet will popup displaying the total amount to be paid, shipping options and contact information. Once the user approves these details, a single-use-token is returned 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.

Supported platforms

Apple Pay is supported in Safari on iOS 11.3 and later and macOS 10.12.6 and later and Chrome on iOS 16 and later. Google Pay is supported in Chrome 61 and later on Desktop and Android. Apple Pay and Google Pay are not supported outside of these platforms.

Payment Request Button

You can place the Payment Request button anywhere on your page. All you need to do is mark a block element with the attribute data-quickstream-api="paymentRequestButtonContainer" so that the QuickstreamAPI.paymentRequestButton module knows where to append your button.

EXAMPLE

This is an example snippet containing the required attribute.

<div data-quickstream-api="paymentRequestButtonContainer">
  <!-- The Apple Pay or Google Pay button will be inserted in here -->
</div>

createButton( paymentRequestConfig, paymentRequestCallback ) → void

Used to initialise and append the Payment Request button to your webpage.

PARAMETERS

EXAMPLE

var config = {
  supplierBusinessCode: "SUPPLIER_CODE",
  googleMerchantId: "YOUR_GOOGLE_MERCHANT_ID",
  details: {
    total: {
      label: "Your company name",
      amount: {
        value: "10.00",
        currency: "AUD"
      }
    }
  }
};

QuickstreamAPI.paymentRequestButton.createButton(config, function(errors, paymentResponse) {
  if (errors) {
    // Handle errors here
  } else {
    console.log("singleUseTokenId is " + paymentResponse.singleUseTokenId);
    // Take payment then call paymentResponse.complete with the appropriate status
    paymentResponse.complete("success");
  }
});

EXAMPLE WITH SHIPPING

var config = {
  supplierBusinessCode: "SUPPLIER_CODE",
  googleMerchantId: "YOUR_GOOGLE_MERCHANT_ID",
  details: {
    total: {
      label: "Your company name",
      amount: {
        value: "10.00",
        currency: "AUD"
      }
    },
    shippingOptions: [{
      "id": "FreeShip",
      "label": "Free Shipping (5 to 7 days)",
      "amount": {
        value: "0.00",
        currency: "AUD"
      }
    }]
  },
  options: {
    requestShipping: true
  },
  onshippingaddresschange: handleShippingAddressChange,
  onshippingoptionchange: handleShippingAddressChange
};

QuickstreamAPI.paymentRequestButton.createButton(config, function(errors, paymentResponse) {
    if (errors) {
        // Handle errors here
    } else {
        console.log("singleUseTokenId is " + paymentResponse.singleUseTokenId);
        console.log("shippingAddress is " + paymentResponse.shippingAddress);
        // Take payment then call paymentResponse.complete with the appropriate status
        paymentResponse.complete("success");
    }
});

function handleShippingAddressChange(event) {
  // Validate shipping address and calculate new total then
  // call event.updateWith with the new total or an error
  event.updateWith({
    total: {
      label: "Your company name",
      amount: {
        value: newTotal,
        currency: "AUD"
      },
    }
  });
}

PaymentRequestConfigObject

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

PaymentRequestCallback( errors, paymentResponse ) → void

This function will be called when there are errors during initialisation of the module and when the user confirms the payment on the payment sheet.

PaymentRequestDetailsObject

A JavaScript object that encapsulates the details for the transaction. See the tables below for more details on the structure.

PaymentRequestOptionsObject

A JavaScript object that controls what details will be collected on the payment sheet. See the tables below for more details on the structure.

PaymentRequestTotalObject

A JavaScript object that encapsulates an amount and label. See the tables below for more details on the structure.

PaymentRequestAmountObject

A JavaScript object that encapsulates an amount value and currency. See the tables below for more details on the structure.

PaymentRequestShippingOptionObject

A JavaScript object that encapsulates the selected shipping contact information. See the tables below for more details on the structure.

PaymentRequestShippingAddressObject

A JavaScript object that encapsulates the selected shipping contact information. See the tables below for more details on the structure.

PaymentRequestUpdateEvent

A JavaScript object that stores the selected shipping option and shipping address, and a method to update the transaction details. See the tables below for more details on the structure.

PaymentRequestResponseObject

A JavaScript object that stores the singleUseTokenId, selected shipping option and shipping address, and a method to complete the payment sheet. See the tables below for more details on the structure.

PaymentRequestInitialisedObject

A JavaScript object that contains the availabity of each payment method.