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.
name
attribute from your input elements so that you don't inadvertently submit sensitive credit card information to your own server.
<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
Where Note: The |
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
|
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.
|
|
callback |
callback | The callback function that is executed after receiving the response from the REST request. When there are no errors, the
|
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.
|
|
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
If the customer has entered invalid credit card details, the
|
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.
|
|
callback |
callback | The callback function that is executed after validation is performed. The
Where |
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.
|
|
callback |
callback | The callback function that is executed after validation is performed. The
Where |
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.
|
|
callback |
callback | The callback function that is executed after validation is performed. The
Where |
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.
name
attribute from your input elements so that you don't inadvertently submit sensitive credit card information to your own server.
<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
Where Note: The |
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.
|
|
callback |
callback | The callback function that is executed after validation is performed. The
Where |
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.
|
|
callback |
callback | The callback function that is executed after validation is performed. The
Where |
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"/>