Skip to main content

Custom Form using QuickStream-API.js

QuickStream-API.js is a JavaScript library containing helper functions for collecting card and bank account 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.

Use Custom Form to seamlessly integrate card or bank account forms directly onto your website.

Custom Form does not use an iframe, and so it gives you full control over the look and feel of your payment flow. If you need faster and easier integration, try Trusted Frame.

View the full QuickStream-API.js JavaScript SDK reference and follow the tutorials.

See the Pen Westpac QuickStream REST API - Custom Form Default by Westpac QuickStream (@quickstream) on CodePen.

Custom Form for Credit Cards

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:

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

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.

supplierBusinessCode string The supplier business code that uniquely identifies the supplier business in the QuickStream system that you wish to retrieve the card scheme surcharge rate for.
callback callback The callback function that is executed after validation is performed.

If successful, the data parameter of callback has the Card Surcharge Model.

If the customer has entered invalid credit card details, the data parameter of callback has the following form:

{
    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

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"/>

Custom Form for Bank Accounts

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:

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"/>
Westpac Privacy Statement

Privacy Statement (for individuals whose personal information may be collected - in this clause referred to as "you"). All personal information we collect about you is collected, used and disclosed by us in accordance with our Privacy Statement which is available at Privacy Statement or by calling us through your relationship manager or Westpac representative. Our Privacy Statement also provides information about how you can access and correct your personal information and make a complaint. You do not have to provide us with any personal information but, if you don't, we may not be able to process an application or a request for a product or service.