QuickVault (QuickConnect Registration) Technical Implementation Guide

QuickVault Connect registration

QuickVault Connect registration is a Westpac hosted service that accepts customer account details and stores them securely inside QuickVault. These account details can then be used by any of your Westpac payment solutions.

Demo Registration Flow

This document describes the QuickVault solution and explains how to register accounts using the QuickConnect registration option. High level requirements as well as detailed step-by-step instructions are included to help with the implementation process.

The intended audience for this document is the software development team responsible for integrating their systems with QuickVault.

What is QuickVault?

QuickVault is a Westpac service that allows you to store a customer's credit card details or bank account details securely outside of your system. This process is commonly referred to as preregistering customer account details with Westpac.

The primary purpose of QuickVault is to help your credit card solution become PCI DSS compliant. The term PCI DSS stands for Payment Card Industry Data Security Standard. It is a security standard that has a number of requirements for processing, transmitting and storing credit card details. QuickVault has attained Level 1 PCI DSS compliance - the highest level achievable. To learn more about PCI DSS visit https://www.pcisecuritystandards.org/security_standards/pci_dss.shtml.

Westpac offers a range of solutions for capturing account details and transmitting account details to QuickVault. The range includes:

  • A variety of web based registration solutions
  • An API registration solution
  • A file based registration solution

This document focuses on a web based registration solution called QuickConnect registration. For information about the other solutions please read the QuickVault Summary Guide.

What is QuickConnect registration?

Connect registration is a Westpac hosted service that accepts customer account details and stores them securely inside QuickVault. These account details can then be used by any of your Westpac payment solutions.

To register an account, the customer will visit your website and enter their account details into one of your webpages. When the 'Save' button is clicked the customer's browser will submit the account details directly to QuickVault. QuickVault will then store the account and redirect the customer's browser back to your website.

Solution overview

Key features of QuickConnect registration:

  • Your system hosts all of the web pages
  • Account details are submitted from the browser directly to QuickVault, meaning sensitive credit card details never enter your system.

How does the registration process work?

The following diagram shows the sequence of events that take place when a customer registers an account.

Registration process

The steps for the above diagram are as follows:

  1. The customer visits your website. One of your webpages will include a button or a link to allow the customer to begin the registration process.

  2. When the customer clicks the button your website will prepare the 'Account Details' page. To do this you must first retrieve a security token from QuickVault. You will then include this security token in a hidden field within the page. Technical details for this process will be discussed in Displaying the 'Account Details' page.

  3. The customer enters their account details into the 'Account Details' page.

  4. When the 'Save' button is clicked the customer's browser will post the account details directly to QuickVault. The account details will not enter your website. This process is discussed in Storing account details in QuickVault.

  5. QuickVault saves the account details.

  6. QuickVault redirects the customer's browser back to your website. This process is discussed in Storing account details in QuickVault.

  7. Your website displays the 'Account Registered' page (or your preferred page) to the customer.

Implementation process

There are a number of tasks involved in the implementation process. Each task is described in detail in the following sections of this document. A summary of the tasks and their corresponding section is listed in the table below.

Step Description
Step 1 Kick-off meeting
Step 2 Identifying the account model
Step 3 Generating the account token
Step 4 Displaying the 'Account Details' page
Step 5 Storing account details in QuickVault
Step 6 Receiving registration details
Step 7 Identifying expiring credit cards
Step 7 Testing
Step 8 Sign off
Step 9 Production lodgement
Step 10 Go live
Step 11 Post implementation

To help with the implementation process, we have included a requirements checklist for you to complete as you work on each task. The purpose of the requirements checklist is to help identify and keep track of your requirements.

If you require further assistance, please contact your Westpac Implementation Manager or your Qvalent implementation manager.

Kick-off meeting

The kick-off meeting is the first meeting between your organisation and Qvalent. This typically consists of a telephone conference with the relevant people from your organisation, Westpac and Qvalent.

The purpose of this meeting is to, introduce the team members from each organisation, discuss the implementation process and discuss your requirements.

Identifying the account model

One of the first tasks in the implementation process is to identify what type of account model you have. The account model identifies the number of accounts a customer is allowed to have. There are two options available. You can choose either:

  1. Single account model
  2. Multiple account model

Single account model

The single account model allows a customer to have one account registered. This account will be used every time the customer makes a payment. The account details can be replaced, but there can never be more than one account active.

The following diagram shows an example of the single account model.

Example of the single account model

In order for your solution to use the single account model all of your customers must be structured this way. If any of your customers have more than one active account you must use the multiple account model instead.

Multiple account model

The multiple account model allows a customer to have more than one account registered at the same time. This allows the customer to use different accounts for different situations.

For example, a customer may have two policies - policy1 and policy2. The customer may wish to pay for policy1 with a Visa credit card then pay for policy2 with an Amex credit card. Using the multiple account model you can register both credit cards in QuickVault. Then later, when it is time to make a payment, the appropriate card can be used.

Example of the multiple account model

Generating the account token

A token is a unique identifier for a particular account. It is a shared identifier, meaning your system and QuickVault will both agree to use this value when referring to the account. At the time of registration QuickVault will store the token alongside the account details. Then at the time of payment your system will provide this token to your Westpac payment solution so it can lookup the corresponding account details.

This section describes the different options available for generating the account token. These options vary based on the customer account model you chose in the previous section.

If you chose the single account model, see Tokens for the single account model. If you chose the multiple account model, see Tokens for the multiple account model.

Tokens for the single account model

In the single account model there are two ways to generate the account token. You can choose either:

  1. Client generated token
  2. QuickVault generated token

Client generated token

A client generated token is a value created by your system. It uniquely identifies a customer's account. For example, the account token may be the customer's reference number or member ID.

At the time of registration your system will provide the token to QuickVault so it can be stored alongside the account details. Then at the time of payment your system will provide the token to your Westpac payment solution so that the corresponding account details can be used.

The diagram below shows the high level steps involved when registering an account.

Registering with a client generated token (for the single account model)

Registering with a client generated token (for the single account model)

The steps for registering an account with a client generated token are as follows:

  1. The customer visits your website.
  2. Before you display the 'Account Details' page your system will provide the account token to QuickVault (via the 'customerReferenceNumber' parameter). The account token is a value that uniquely identifies the customer. For example, the customer reference number or member ID. Technical details for this process will be discussed further below.
  3. The customer enters their account details into the 'Account Details' page then clicks 'Save'. The account details are posted directly to QuickVault.
  4. QuickVault stores the account token (from step 2) alongside the account details (from step 3).
  5. QuickVault sends the account token and a registration summary to your system. This is done via a server-to-server postback. The registration summary includes account details and a response code to indicate whether the account was successfully registered.
  6. Your system will retrieve the account token and response code from the registration summary. If the response code indicates the account was successfully registered you will:
    • Use the account token to locate the customer in your system.
    • Update the customer's details to indicate the account has been registered in QuickVault.
    • Store some of the account details if necessary. For example, you should consider storing the card scheme if your system is going to calculate the credit card surcharge.

Registration is now complete. When it is time to make a payment, your system will provide the account token to your Westpac payment solution.

QuickVault generated token

A QuickVault generated token is a value that is created by QuickVault at the time of registration. It uniquely identifies a particular account. We recommend using this type of token rather than a client generated token if:

  • Your system doesn't have a unique ID currently stored against each account, or
  • Your system does have a unique ID, but it can only be provided at the time of registration - it cannot be provided at the time of payment. For example, you cannot change the software that is responsible for the payment process.

QuickVault can format the token in a number of ways. During the implementation process you will select your preferred format. This will be discussed in more detail in Formats for the QuickVault generated token.

Once the token is generated QuickVault will store it alongside the account details. A copy of the token will also be given to your system to store. Then at the time of payment your system will provide the token to your Westpac payment solution so that the corresponding account details can be used.

The diagram below shows the process for registering an account using a QuickVault generated token.

Registering with a QuickVault generated token (for the single account model)

Registering with a QuickVault generated token (for the multiple account model)

The steps for registering an account with a QuickVault generated token are as follows:

  1. The customer visits your website.
  2. Before you display the 'Account Details' page your system will provide a transaction ID to QuickVault (via the 'customerReferenceNumber' parameter). The transaction ID is a value that will allow you to match the response later in step 7. It is not the account token. QuickVault will not require this value in the payment process. The transaction ID may be any unique value, however we recommend providing a customer reference number if you can. This process will be discussed further below.
  3. The customer enters their account details into the 'Account Details' page then clicks 'Save'. The account details are posted directly to QuickVault.
  4. QuickVault creates the account token. There are a number of ways this token can be formatted.
  5. QuickVault stores the account token (from step 4) alongside the account details (from step 3).
  6. QuickVault sends a registration notification to your system. The notification includes the transaction ID from step 2, a response code to indicate whether the account was successfully registered and the account token generated by QuickVault.
  7. Your system retrieves the transaction ID and response code from the registration notification. If the response code indicates the account was successfully registered you will:
    • Use the transaction ID to locate the customer's account in your system.
    • Store the account token
    • Store some of the account details if necessary. For example, the card scheme (if your system is going to calculate the credit card surcharge).

Registration is now complete. When it is time to make a payment, your system will provide this account token to your Westpac payment solution.

Tokens for the multiple account model

In the multiple account model there are two ways to generate the account token. You can choose either:

  1. QuickVault generated token
  2. Custom solution

QuickVault generated token

A QuickVault generated token is a value that is created by QuickVault at the time of registration. It uniquely identifies a particular account. We recommend using this type of token rather than a client generated token if:

  • Your system doesn't have a unique ID currently stored against each account, or
  • Your system does have a unique ID, but it can only be provided at the time of registration - it cannot be provided at the time of payment. For example, you cannot change the software that is responsible for the payment process.

QuickVault can format the token in a number of ways. During the implementation process you will select your preferred format. This will be discussed in more detail in Formats for the QuickVault generated token.

Once the token is generated QuickVault will store it alongside the account details. A copy of the token will also be given to your system to store. Then at the time of payment your system will provide the token to your Westpac payment solution so that the corresponding account details can be used.

The diagram below shows the process for registering an account using a QuickVault generated token.

Registering with a QuickVault generated token (for the multiple account model)

Registering with a QuickVault generated token (for the multiple account model)

The steps for registering an account with this type of token are as follows:

  1. The customer visits your website.
  2. Before you display the 'Account Details' page your system will provide the customer's ID to QuickVault (via the 'customerReferenceNumber' parameter). The customer ID is a value that uniquely identifies the customer. For example, the customer's reference number or member ID. Note, this value does not uniquely identify the account, as there may be multiple accounts with the same customer ID. Technical details for this process will be discussed further below.
  3. The customer enters their account details into the 'Account Details' page then clicks 'Save'. The account details are posted directly to QuickVault.
  4. QuickVault creates an account token. There are a number of ways the token can be formatted.
  5. QuickVault stores the account token, account details and customer ID.
  6. QuickVault sends a registration notification to your system. The notification includes the customer ID, a response code to indicate whether the account was successfully registered and the account token that was generated by QuickVault.
  7. Your system will retrieve the response code from the registration summary. If the response code indicates the account was successfully registered you will:
    • Store the account token
    • Store some of the account details if necessary. For example the card scheme (if your system is going to calculate the credit card surcharge).

Registration is now complete. When it is time to make a payment there are two options:

  • Your system can provide a particular account token to your Westpac payment solution.
  • If you are using QuickTerminal to make payments, a staff member can enter a customer ID to search for all the accounts associated with that customer, then select the appropriate account to use.

Custom solution

If you are unable to use the previous solution or you would prefer to generate your own token Westpac can work with you to create a custom solution. The custom solution will behave similarly to the 'Client generated token' solution described earlier in Client generated token for the single account model.

The difference however is that your system will provide an account level identifier rather than a customer level identifier as the token. For example, the token may be the account ID or policy ID. You will provide this value as the Customer Reference Number to QuickVault.

For more information about this option please talk to your Qvalent implementation manager.

Formats for the QuickVault generated token

This section is relevant if you are using a QuickVault generated token in your solution. QuickVault can format the token in a number of ways. You can choose one of the following options:

  1. Check digit format
  2. Numeric account format
  3. Alphanumeric account format
  4. Community code format

Check digit format

The check digit format uses a random number combined with a check digit. The check digit is the last digit in the token. It will be calculated using the Luhn algorithm (MOD10V1 formula).

The maximum length of the token is 17 digits.

For example:

  • The first account may be assigned a token with the value 1001234564.
  • The second account may be assigned a token with the value 1001234608.
  • And so on.

Numeric account format

The numeric account format uses a random number followed by the last 4 digits of the account.

For a credit card the token will consist of a random number followed by the last 4 digits of the credit card number. For a bank account the token will consist of a random number followed by the last 4 digits of the bank account number.

The maximum length of the token is 17 digits.

Alphanumeric account format

The alphanumeric account format uses a random alphanumeric value followed by the last 4 digits of the account.

For a credit card the token will consist of a random alphanumeric value followed by the last 4 digits of the credit card number. For a bank account the token will consist of a random alphanumeric value followed by the last 4 digits of the bank account number.

The maximum length of the token is 17 characters.

Community code format

The community code format uses your Westpac short community code followed by a random numeric value. Your Westpac short community code will be a value that is 1-4 characters long. Every token will begin with this value.

The maximum length of the token is 17 characters.

For example, if we assume your Westpac community short code is ABCD:

  • The first account may be assigned a token with the value ABCD100354.
  • The second account may be assigned a token with the value ABCD100361.
  • And so on.

Displaying the 'Account Details' page

The 'Account Details' page is a webpage generated by your system. The purpose of the page is to capture your customer's account details and submit them securely to QuickVault. The page can be used to register either credit card accounts or bank accounts.

For a credit card registration the page will include fields for:

  • Card holder name
  • Credit card number
  • Expiry date

Credit card registration

For a bank account registration the page will include fields for:

  • Account name
  • BSB
  • Account number

Bank account registration

There are a number of steps involved in displaying the 'Account Details' page. The QuickConnect registration solution requires parameters to be sent to QuickVault in two separate calls. There are:

  • Parameters for the secure token handoff
  • Parameters for the direct post

Secure token handoff

The secure token handoff is a message sent directly from your server to QuickVault. It occurs immediately before you display the 'Account Details' page. The purpose of the secure token handoff is to prevent parameters from being tampered with before being sent to QuickVault. Most parameters will be sent to QuickVault using the secure token handoff. See Parameters for the secure token handoff for the full list of parameters.

In order to use the secure token handoff your website must have:

  • A dynamic backend which can send a HTTPS POST directly to the QuickVault server
  • The ability to make an outbound HTTPS connection to QuickVault through your proxy and firewall

Direct post

The direct post is a message sent directly from the customer's browser to QuickVault. It occurs after the customer clicks the 'Save' button on the 'Account Details' page. The purpose of the message is to send the customer's account details to QuickVault without entering your system.

There are a number of parameters included in the direct post. They relate to either:

  • Input fields shown on the 'Account Details' page (for example the card holder name, credit card number and expiry date)
  • Hidden fields included within the 'Account Details' page (for example the secure token)

See Parameters for the direct post for the full list of parameters that need to be included on the 'Account Details' page.

The following sequence diagram shows all the steps required to display the 'Account Details' page.

Sequence diagram for displaying the 'Account Details' page

The steps for displaying the 'Account Details' page are as follows:

  1. Click 'Register account' On the 'Customer Details' page the customer clicks the 'Register account' button.

  2. Send request The customer's browser sends a request to your server to display the 'Account Details' page.

  3. Retrieve data Your server retrieves all the data that is required for the secure token handoff. It then builds a parameter list that will be sent to QuickVault as part of the request. For more details see Parameters for the secure token handoff.

  4. Request security token Your server makes an outbound HTTPS connection to the QuickVault server. The parameter list from the previous step is included in the request.

  5. Generate security token & store parameters QuickVault generates a security token and stores your parameter list. A security token is a randomly generated, base 64 encoded string of characters. For example:

token=m378813qtvOtylVTvVvpWA7PT14QHltr-AqX2gZ-RFM

A unique security token is created for every request. The token is valid for 1 hour after it is
created and can only be used once.
  1. Return security token QuickVault returns the security token to your sever.

  2. Return html for 'Account Details' page

Your server produces html for the 'Account Details' page and sends it to the customer's browser.

The page includes:

  • Input fields for the customer to enter their account details
  • Hidden fields that are required for the direct post to QuickVault

For more details see Parameters for the direct post.

Storing account details in QuickVault

This section explains the process for storing account details in QuickVault. It includes details about:

  • Submitting the account details to QuickVault
  • Displaying the 'Account Registered' page to your customer

The diagram below provides a high level overview of the process.

Storing account details in QuickVault

The sequence diagram below shows the individual steps involved.

Sequence diagram for storing account details in QuickVault

The steps for the above sequence diagram are:

  1. Enter details and click 'Save'
    The customer enters their account details into the 'Account Details' page then clicks 'Save'.
  2. Direct post
    The customer's browser submits the account details directly to QuickVault.
  3. Verify security token, lookup parameters and store account details
    QuickVault checks the security token to make sure it matches the security token it generated earlier. It then retrieves the other parameters and stores the account.
  4. Redirect
    QuickVault builds a list of parameters to include in the redirect. They are included as a list of ampersand delimited parameters. For example:
    communityCode=ACOMPANY&supplierBusinessCode=ACOMPANY&...
    For the full list of parameters see Parameters for the redirect.
    QuickVault then instructs the customer's browser to redirect to your returnUrl via HTTP get.
  5. Request next page
    The customer's browser redirects to your server's returnUrl.
  6. Retrieve parameters
    Your server retrieves the parameters from the request. It then uses this data to build the html for the 'Account Registered' page (or a different page if you prefer).
  7. Return html for next page
    Your server returns the html for the 'Account Registered' page to the customer's browser.

Receiving registration details

QuickStream provides two ways to receive registration details:

  1. Server to server notification
  2. Registered accounts report

Server to server notification

This option is also known as the server-to-server postback. It allows you to receive registration summary details immediately after each registration is made. This is done via a HTTPS POST from QuickStream to your server. QuickStream can post the details as form parameters or as XML.

To receive a server to server notification

  1. Your website must provide the serverReturnUrl parameter in a secure token handoff, or configure your sever to server notifications in QuickStream Portal.
  2. Configure the domain whitelist in QuickStream Portal.
  3. Have a valid SSL certificate issued by a trusted certificate authority. Sending the notification over SSL ensures that the encrypted notification cannot be read by a malicious third-party. As your SSL certificate was issued by a trusted certificate authority, it also guarantees that QuickWeb is connecting to your webserver (and not another fraudulent server as in the case of DNS attacks).
  4. Have a dynamic backend which can receive and parse HTTPS requests with parameters or can parse XML.

A server to server notification is sent immediately after a successful registration attempt.

When you receive a server to server notification, your system must:

  1. Check that the IP address matches the expected QuickStream IP address.
    • If they do not match you will return a status of 403 Forbidden.
    • See IP addresses in Test and in Production.
  2. Check that the Basic Auth username and password in the Authorization header match your credentials in QuickStream.
    • If they do not match you will return a status of 403 Forbidden.
  3. Extract the details.
    • The way you do this will depend on the way QuickStream has posted the details. You will either extract the details from the form parameters or extract the details from the XML.
  4. Check to make sure you have not already processed a notification.
    • To do this you will compare the preregistrationCode and customerReferenceNumber to the record you have already processed.
  5. Save the registration details to your database.
  6. Your server returns a status of 200 OK.
    • Note, if an error occurred and you were unable to save the details, your server will instead return a status of 500 Internal Server Error.

Note:

  • If you are sending an account token preregistrationCode to make a payment, save a copy of the account token in your database or update that it was successfully registered.
  • If your system will calculate a card surcharge during payment, you may need to store the card scheme in your database now. This is only necessary if you intend to apply different surcharges to different card schemes.
  • If your system is going to report expiring cards you will need to store the card expiry date.

Example server to server notification consumption in Java

public class NotificationConsumer extends HttpServlet 
{
    ...
    @Override
    protected void doPost( final HttpServletRequest request, 
                           final HttpServletResponse response ) throws IOException
    {
        try 
        {
            if( !request.getRemoteAddr().equals( QUICKSTREAM_IP_ADDRESS ) ) {
                response.sendError( HttpServletResponse.SC_FORBIDDEN );
                return;
            }
            final String authorization = request.getHeader( "Authorization" );
            if( authorization == null )
            {
                response.sendError( HttpServletResponse.SC_UNAUTHORIZED );
                return;
            }
            String base64Credentials = authorization.substring( "Basic".length() ).trim();
            String credentials = new String( Base64.getDecoder().decode( base64Credentials ), Charset.forName( "UTF-8" ) );
            final String[] values = credentials.split(":",2);
            if( !QUICKSTREAM_USERNAME.equals( values[0] ) || !QUICKSTREAM_PASSWORD.equals( values[1] ) )  {
                response.sendError( HttpServletResponse.SC_FORBIDDEN );
                return;
            }
            response.setStatus( HttpServletResponse.SC_OK );
            for( final String name : request.getParameterMap().keySet() ) {
                for( final String value : request.getParameterMap().get( name ) ) {
                    // Consume
                }
            }
        }
        catch( final Exception e  ) {
            response.sendError( HttpServletResponse.SC_INTERNAL_SERVER_ERROR );
        }
        return;
    }
}

Example server to server notification consumption in PHP

<?php
    header( "Content-Type: text/plain" );
    if ( $_SERVER["REMOTE_ADDR"] != QUICKSTREAM_IP_ADDRESS ) {
        header("HTTP/1.1 403 FORBIDDEN");
        return;
    }
    if ( !isset($_SERVER['PHP_AUTH_USER'] ) || !isset( $_SERVER['PHP_AUTH_PW'] ) ) {
        header("HTTP/1.1 401 UNAUTHORIZED");
        return;
    }
    if ( $_SERVER['PHP_AUTH_USER'] != QUICKSTREAM_USERNAME || $_SERVER['PHP_AUTH_PW'] != QUICKSTREAM_PASSWORD ){
        header("HTTP/1.1 403 FORBIDDEN");
        return;
    }
    if( $_SERVER["REQUEST_METHOD"] === "POST" ) {
        try {
            foreach( $_POST as $key => $value ) {
                // consume
            }
            header("HTTP/1.1 200 OK");
        } catch (Exception $e) {
            header("HTTP/1.1 500 INTERNAL SERVER ERROR");
        }
    }
    return;
?>

Parameters in the server to server notification

These parameters are present in the server to server notification:

Parameter Name Description
product This will be hardcoded to QUICKVAULT.
communityCode Your QuickStream community code. You will be notified of your community code during the implementation.
Note, this is the same value that you will pass to QuickVault during the handoff.
supplierBusinessCode Your QuickStream supplier business code. This value will be provided to you during the implementation.
Note, this is the same value that you will pass to QuickVault during the handoff.
connectionType QUICKWEB or QUICKCONNECT
customerReferenceNumber The same customerReferenceNumber value you provided in the handoff.
cardholderName The cardholder name entered by the customer.
For example: John Smith
maskedCardNumber The masked card number. For example: 456471...004
expiryDateMonth The expiry month entered by the customer.
Format: MM
For example: 01
expiryDateYear The expiry year entered by the customer.
Format: YYYY
For example: 2017
cardScheme The type of credit card the customer registered.
QuickVault will return one of the following values: VISA, MASTERCARD, AMEX, DINERS, UNIONPAY, JCB
bsb The BSB number entered by the customer. For security reasons the number will be masked.
For example: xxx-000
accountNumber The account number entered by the customer. For security reasons the number will be masked. For example: xxxxxx678
accountName The account name entered by the customer.
preregistrationCode The account token.
Custom fields Any custom parameters you included in the handoff will be sent back to you.
That is, any parameters prefixed with custom will be included in the postback.
For example: customTitle,
customAddress

If you choose to receive the data as XML, the parameters listed in the table above will instead be built into an xml document. This document will be passed to your server in the body of the request. The request will have a content-type of application/xml.

An example XML document is shown below.

<PaymentResponse>
<product>QUICKVAULT</product>
<communityCode>ACOMPANY</communityCode>
<supplierBusinessCode>ACOMPANY</supplierBusinessCode>
<connectionType>QUICKCONNECT</connectionType>
<customerReferenceNumber>123456</customerReferenceNumber>
<cardScheme>VISA</cardScheme>
<cardholderName>John Smith</cardholderName>
<maskedCardNumber>411111xxxxxxx111</maskedCardNumber>
<expiryDateMonth>02</expiryDateMonth>
<expiryDateYear>2017</expiryDateYear>
<preregistrationCode>0012004441513456</preregistrationCode>
<customTitle>Mr</customTitle>
</PaymentResponse>

Registered accounts report

At the end of each day QuickVault can provide you with a Registered Accounts Report. The report lists all the accounts that have been registered throughout the day. It can be provided for any of the registration solutions, however it is mainly used for Web registration, QuickConnect registration and Portal registration.

QuickVault will generate the report at 12am each night. You can then upload the report into your system and reconcile the data against notifications you received earlier in the day.

QuickVault offers a standard file format. See Registered accounts report.

Manage your security settings

QuickStream Portal is your administration interface for QuickStream. You can manage the following security settings:

Manage your IP whitelist

The IP address whitelist holds the allowed IP addresses for secure token requests. Requests made from IP addresses that are not in this whitelist will be rejected, and will not receive a security token.

  1. Sign into QuickStream Portal
  2. Click Administration -> Facility Settings -> Manage IP Address Whitelist
  3. Select Add IP Address to whitelist a new IP address, or select the edit or delete icons to manage existing entries.

QuickStream Portal allows you to manage your allowed IP addresses.

Manage your domain whitelist

The domain whitelist holds the allowed domains or URLs for sending server to server notifications. Server to server notifications to URLs that are not in this whitelist will be rejected, and will not receive a server to server notification.

  1. Sign into QuickStream Portal
  2. Click Administration -> Facility Settings -> Manage Domain Whitelist
  3. Select Add Domain to whitelist a new domain or specific URL, or select the edit or delete icons to manage existing entries.

You can whitelist your entire domain, or a specific URL. For example,

  • To receive server to server notifications from any URL on your website, whitelist yoursite.com.au.
  • To receive server to server notifications at a specific URL on your website, whitelist yoursite.com.au/payments.

QuickStream Portal allows you to manage your allowed domains.

View your connection details

Connection details are required to interact with QuickStream in each environment. These connection details refer to values you must pass for the Secure Token Handoff.

  1. Sign into QuickStream Portal
  2. Click Administration -> Facility Settings -> View Connection Details
  3. Select Secure Token Request to view connection details for the Secure Token Request.

QuickStream Portal allows you to view your connection details and configuration.

Manage server to server notifications

Server to server notifications are submitted directly to your system. A HTTP POST with form data or XML sent from QuickStream after a successful registration attempt.

  1. Sign into QuickStream Portal
  2. Click Administration -> Facility Settings -> Manage Server to Server Notification

Manage server to server notifications in QuickStream Portal.

Destination URL

This option can be used for:

You can override this by passing serverReturnUrl in a Secure Token Handoff for the above products except the QuickTerminal and QuickVoice products.

Notification format

Choose HTTPS POST or XML.

Control Description
HTTPS POST The server to server notification will be sent as HTTPS POST form parameters.
XML The server to server notification will be sent as HTTPS POST with XML as the request body.

Automatic retry of failed notifications

Configure the number of times you wish QuickStream to re-send failed notifications. A failed notification is one where a server cannot be reached, or a server responds with a HTTP status code other than 200 OK.

Control Description
If the original attempt fails Choose the time until the system retries the first time.
If this second attempt fails, retry Choose number of times the system should retry after the second attempt.
at intervals of Choose the interval between each subsequent retry.
If all attempts fail, send an email to Enter the email address the system will notify when a server to server notification cannot be sent. You can override this by passing errorEmailToAddress in a Secure Token Handoff.

For example the following setting produces a schedule:

Setting Value
If the original attempt fails Retry 1 minute after the original attempt
If this second attempt fails, retry 3 more times
at intervals of 10 mins
If all attempts fail, send an email to john@yoursite.com.au

This setup will send the following server to server notifications:

  1. Credit card payment made at 12:00 PM
  2. Server to server notification sent at 12:00 PM and failed.
  3. Server to server notification retried at 12:01 PM and failed.
  4. Server to server notification retried at 12:11 PM and failed.
  5. Server to server notification retried at 12:21 PM and failed.
  6. Server to server notification retried at 12:31 PM and failed.
  7. Stop retrying and send an email to john@yoursite.com.au.

Troubleshooting security settings

QuickStream Portal's Activity Log shows:

Types of entries you may see for unsuccessful secure token requests are:

  • A Secure Token Request was received from an IP address that is not in the IP Address Whitelist for this facility.

Types of entries you may see for unsuccessful server to server notification attempts are:

  • Server to server postback to URL X failed as no username or password is configured for this facility.
  • Server to server postback URL X using HTTP, but should be HTTPS.
  • The URL X is not listed as an allowed end point to post response information to.
  • The URL X is invalid and cannot be used as an end point to post response information to.
  • Received HTTP N instead of HTTP 200 from endpoint X.

QuickStream Portal allows you debug connection problems through the Activity Log.

Identifying expiring cards

QuickVault's Expiring Cards Report provides you with a list of credit cards that are due to expire. QuickVault will generate the report at the start of each month. You can then upload the report into your system and notify your customers about their expiring credit cards.

QuickVault offers a CSV file format containing the expiring card details and account token. See Expiring cards report.

Testing

See Testing.

Test URLs and IP addresses

See Test URLs and IP addresses.

Test account numbers

See Test card and bank account numbers.

Sign off

After you have completed your user acceptance testing you must send a 'sign off' email to your Qvalent implementation manager. The email will state that you have successfully tested all aspects of the solution and you are ready for it to be moved into production. A sample email is included below.

To: Qvalent implementation manager

Cc: Westpac implementation manager

Subject: QuickVault batch registration sign off

We have successfully completed user acceptance testing. Our tests covered all areas of the solution.

Our credit card registration tests covered:

  • Registering an account for a particular customer
  • Replacing that registered account with a new account
  • Attempting to register an account with invalid details
  • Attempting to register an account that is already registered
  • Making payments using registered accounts

Our bank account tests covered:

  • Registering an account for a particular customer
  • Replacing that registered account with a new account
  • Attempting to register an account with invalid details
  • Attempting to register an account that is already registered
  • Making payments using registered accounts

Our QuickStream admin tests covered:

  • Creating staff users
  • Assigning roles to users
  • Searching for accounts

We are satisfied with the results of these tests and we are ready for the solution to be moved into production.

Regards,

Allan Smith

Production lodgement

See Production lodgement.

Production URLs and IP addresses

See Production URLs and IP addresses.

Go live

Once production lodgement is complete and you are satisfied with the results of your low value tests in production you are ready to go live. The term "go live" represents the date you will make the solution available to your customers.

At this stage of the implementation process there are only a few tasks left to complete. They are:

  • Before the go live date, communicate with your customers to inform them about the new payment process.

  • On the go live date, update the appropriate page (or pages) on your website to make the new solution available to your customers.

After you go live, Qvalent and Westpac will closely monitor the solution. This is known as the "monitoring phase" and lasts for two weeks. During this time, if you have any questions or concerns about the solution you should communicate directly with your Qvalent implementation manager.

Post implementation

Once the two week monitoring phase is over the implementation process is officially complete. Your Qvalent implementation manager will hand the solution over to the Qvalent helpdesk. The helpdesk will be responsible for day to day monitoring of the solution and resolving any issues that occur.

If you have any questions or concerns about the solution at this point contact the helpdesk: QuickStream Technical Support.

Security

QuickVault has attained Level 1 PCI DSS compliance. To ensure QuickVault maintains this high level of security the following must be adhered to.

Trusting the QuickVault server

When your server exchanges information with QuickVault over HTTPS it must trust the root level certificate. That is, your server must trust the certificate issued by Verisign - not the certificate issued to Qvalent. The Qvalent certificate will expire and need replacing each year. However the Verisign certificate will have a much longer life (i.e. expire in 2028).

If your server trusts the Qvalent certificate directly your QuickVault implementation will cease to operate when a replacement certificate is installed.

Whitelisting the QuickVault server

Your server should only accept registration notifications from QuickVault. Your implementation manager will provide you with the list of valid QuickVault IP addresses. We recommend whitelisting these addresses. Then, when you receive a registration notification you should ensure the source IP address matches one of the whitelisted IP addresses.

Transport Layer Security (TLS)

QuickVault requires Secure Token Requests and web browser access made using the encryption standard known as TLSv1.2. QuickVault rejects requests made using TLSv1, or TLSv1.1.

If you receive an error that resembles the error message below, then the underlying TLS connection was not successful. Your systems need adjustments or upgrades to work properly with this service.

TLSv1 is not strong encryption, please use TLSv1.2 instead.

HTTP 429 Too Many Requests

You may receive a HTTP 429 Too Many Requests response code when you have sent too many requests in a given amount of time.

If you send more than 10 simultaneous requests, you may receive a HTTP 429 Too Many Requests response code.

You should wait for 20 seconds and resend the request.

Parameters for the secure token request

The following table lists the parameters that can be passed from your server to QuickVault during the secure token request. This task is shown Displaying the 'Account Details' page.

The parameters must be passed to CommunityTokenRequestServlet. The full URL for the test environment is included in Test URLs and IP addresses. The full URL for the production environment is included in Production URLs and IP addresses.

Mandatory parameters

Parameter Name Description
username Your username. This value will be provided to you by your implementation manager.
password Your password. This value will be provided to you by your implementation manager.
supplierBusinessCode Your QuickVault supplier business code. This value will be provided to you by your implementation manager.
customerReferenceNumber For the single account model:
  • If you are using a client generated token populate this field with a value that uniquely identifies your customer. For example, a customer reference number or member ID.
  • If you are using a QuickVault generated token populate this field with a transaction ID. We recommend providing a unique customer reference number if you can, but you can use another unique value if you prefer.
For the multiple account model:
  • If you are using a QuickVault generated token populate this field with the customer's unique identifier.
  • If you are using a custom solution populate this field with a value that uniquely identifies the account (for example, account ID or policy ID). Please talk to your implementation manager for details.
connectionType QUICKCONNECT
product QUICKVAULT
returnUrl The URL you would like QuickVault to redirect to after the account is registered. Any parameters included in the URL will be provided back to you. Example:http://www.yoursite.com.au/accountRegistered?Name=John&Age=21

Optional parameters

Parameter Name Description
errorUrl The URL you would like QuickVault to redirect to after a user error during account registration. Any parameters included in the URL will be provided back to you. Example: http://www.yoursite.com.au/enterAccount?Name=John&Age=21
serverReturnUrl The URL you would like QuickVault to send the registration notification to (ie, the server-to-server postback). Example: https://www.yoursite.com.au/registrationNotification
errorEmailToAddress The email address you would like QuickVault to send an email to if we cannot deliver the registration notification to your server (eg, your website is down). Example: registrations@yoursite.com.au. This parameter is only relevant if you wish to receive the registration notification.

Custom parameters

Parameter Name Description
custom<custom name>
For example
customTitle
customAge
QuickVault can pass this data back to you. The parameter name must start with 'custom'. Maximum 100 characters per parameter.

Sample code for the secure token request

Java

package com.qvalent.demo;
import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.InetSocketAddress;
import java.net.Proxy;
import java.net.URL;
import java.net.URLDecoder;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
import javax.net.ssl.HttpsURLConnection;

public class TokenRequestExample
{
    // This is the HTTP proxy configuration section.
    // To use basic authentication, other options
    // will have to be specified. This example
    // uses Windows domain-based NTLM authentication.
    // To use a direct connection, set USING_PROXY to false.
    private static final String HTTP_PROXY_URL_STRING =
        "proxy.yourdomain.com.au";
    private static final int HTTP_PROXY_PORT = 8080;
    private static final boolean USING_PROXY = true;
    private static final String TOKEN_REQEST_URL_STRING =
        "https://<environment_url>/CommunityTokenRequestServlet";

    // Here we are initialising a java.net.URL object.
    private static final URL TOKEN_REQUEST_URL =
        new URL( TOKEN_REQEST_URL_STRING );

    public static void main( final String[] args ) throws Exception
    {

        // Add username, password and customer reference number parameters
        // to the request.
        final Map<String, String> params =
            new HashMap<String, String>();
        params.put( "username", "username" );
        params.put( "password", "password" );
        params.put( "customerReferenceNumber", "CUSTOMER1" );
        final String content = getQuery( params );

        // Control block to use either proxy or direct connection.
        final HttpsUrlCOnnection connection;
        if( USING_PROXY )
        {
            final Proxy proxy = new Proxy( Proxy.Type.HTTP,
                                               new InetSocketAddress(
                                                   HTTP_PROXY_URL_STRING,
                                                   HTTP_PROXY_PORT ) );
            connection = (HttpsURLConnection)TOKEN_REQUEST_URL.openConnection( proxy );
        }
        else
        {
            connection = (HttpsURLConnection)TOKEN_REQUEST_URL.openConnection();
        }

        // Token request should be a HTTP POST for enhanced security.
        connection.setRequestMethod( "POST" );

        // The parameters are sent using url form encoding.
        connection.setRequestProperty(
            "Content-Type",
            "application/x-www-form-urlencoded" );

        // Add the content length and language.
        connection.setRequestProperty(
            "Content-Length",
            Integer.toString( content.length() ) );
        connection.setRequestProperty(
            "Content-Language",
            "en-au" );

        // We're going to write out post data and get the response (token),
        // so set both output and input.
        connection.setDoOutput( true );
        connection.setDoInput( true );
        // Set up a writer to write the http post data out.
        final BufferedWriter writer =
           new BufferedWriter(
               new OutputStreamWriter( connection.getOutputStream() ) );
        writer.write( content );
        writer.close(); // This will send the content.

        // Set up a reader to get the token result back from
        // the connection. Build it all up into one string.
        final BufferedReader reader =
           new BufferedReader(
               new InputStreamReader( connection.getInputStream() ) );
        String response = "";
        String buff;
        while( ( buff = reader.readLine() ) != null )
        {
            response += buff;
        }
        reader.close();

        // Print the full response.
        System.out.println( "Response: " + response );

        // Print the token, which will occur after "token="
        // and should be the only response parameter parameter.
        final String token =
            URLDecoder.decode(
                response.substring(
                    response.indexOf( "=" ) + 1 ) ,
                "UTF-8" );
        System.out.println( "Token: " + token );
    }

    // Helper method to construct a URL encoded query from
    // a map of string => string.
    private static String getQuery( final Map<String, String> params )
    throws Exception
    {
        String result = "";
        boolean first = true;
        for( final RequestParameter requestParameter : RequestParameter.values() )
        {
            if( first )
            {
                first = false;
            }
            else
            {
                result += "&";
            }
            result += URLEncoder.encode( requestParameter.getLabel(), "UTF-8" );
            result += "=";
            result += URLEncoder.encode(
                params.get( requestParameter.getLabel() ) == null ?
                "" :
                params.get( requestParameter.getLabel() ),
                "UTF-8" );
        }
        return result;
    }
}

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;
using System.Net;
using System.Web;
using System.Collections;
namespace TokenRequestExample
{
    class TokenRequestExample
    {
        static void Main(string[] args)
        {
            byte[] byteArray;
            Stream webpageStream;
            StreamReader webpageReader;
            String webpageContent;
            Hashtable parameters = new Hashtable();
            parameters.Add("username", "username");
            parameters.Add("password", "password");
            parameters.Add("customerReferenceNumber", "CUSTOMER1");
            HttpUtility.UrlEncode("");
            String postData = "";
            Boolean first = true;
            foreach( String key in parameters.Keys )
            {
                if(first)
                {
                    first = false;
                }
                else
                {
                    postData += "&";
                }
                postData += key + "=" + HttpUtility.UrlEncode(parameters[key].ToString());
            }
            String URL = "https://<environment_url>/CommunityTokenRequestServlet";
            byteArray = Encoding.UTF8.GetBytes(postData);
            WebRequest request = WebRequest.Create(URL);
            WebProxy proxy = new WebProxy("proxy.yourdomain.com.au", 8080);
            proxy.UseDefaultCredentials = true;
            proxy.BypassProxyOnLocal = true;
            request.Proxy = proxy;
            request.Method = "POST";
            request.ContentType = "application/x-www-form-urlencoded";
            request.ContentLength = byteArray.Length;
            webpageStream = request.GetRequestStream();
            webpageStream.Write(byteArray, 0, byteArray.Length);
            webpageStream.Close();
            webpageReader = new StreamReader(request.GetResponse().GetResponseStream());
            webpageContent = webpageReader.ReadToEnd();
            Console.WriteLine(webpageContent);
            Console.ReadKey(true);
        }
    }
}

PHP

<?php
    $postFields = array( "username" => "username",
                         "password" => "password",
                         "customerReferenceNumber" => "CUSTOMER1" );
    $postFieldsString = http_build_query( $postFields );
    $curlHandle = curl_init();
    curl_setopt( $curlHandle, CURLOPT_URL, "https://<environment_url>/CommunityTokenRequestServlet" );
    if( array_key_exists( "user", $_POST ) &&
        array_key_exists( "pwd", $_POST ) )
    {
        curl_setopt( $curlHandle, CURLOPT_PROXY, "proxy.yourdomain.com.au:8080" );
        curl_setopt( $curlHandle, CURLOPT_PROXYUSERPWD, $_POST["user"].":".$_POST["pwd"] );
    }
    curl_setopt( $curlHandle, CURLOPT_POST, count( $postFields ) );
    curl_setopt( $curlHandle, CURLOPT_POSTFIELDS, $postFieldsString );
    curl_setopt( $curlHandle, CURLOPT_RETURNTRANSFER, 1 );
    curl_setopt( $curlHandle, CURLOPT_CAINFO, "PCA-3G5.pem" );
    curl_setopt( $curlHandle, CURLINFO_HEADER_OUT, 1 );
    $result = curl_exec( $curlHandle );
?>
<html>
    <head>
    </head>
    <body>
        <p> Header: <?php echo curl_getinfo( $curlHandle, CURLINFO_HEADER_OUT ); ?> </p>
        <?php
            if( curl_errno( $curlHandle ) )
            {
        ?>
                <p> Error: <?php echo curl_error( $curlHandle ); ?> </p>
        <?php
            }
            else
            {
        ?>
                <p> Token: <?php echo $result; ?> </p>
        <?php
            }
        ?>
    </body>
</html>
<?php   
    curl_close( $curlHandle );
?>

Python 3.x


import urllib.request as request
import urllib.parse as parse

USERNAME = ""
PASSWORD = ""
CD_CRN = ""

URL = "https://quickstream.support.qvalent.com/CommunityTokenRequestServlet"

class TokenRequest:

    def __init__(self, url):
        self.url = url
        self.params = {}

    def addParameter(self, key, value):
        self.params[key] = value

    def addParameters(self, dictKeyValues):
        for key in dictKeyValues:
            self.addParameter(key, dictKeyValues[key])

    def performRequest(self):
        details = parse.urlencode(self.params).encode("UTF-8")
        response = request.urlopen(self.url, details)
        return response

    def getToken(self):
        response = self.performRequest().read()
        response = response.decode("UTF-8")
        return response.split("=")[1]

# If you do not have a proxy then delete these
# next four lines.
proxyaddress = 'username:password@proxy.yourdomain.com.au:8080'
proxy = request.ProxyHandler({'https': proxyaddress})
opener = request.build_opener(proxy)
request.install_opener(opener)
#---------------------------------------------

req = TokenRequest(URL)
req.addParameter("username", USERNAME)
req.addParameter("password", PASSWORD)
req.addParameter("cd_crn", CD_CRN)
token = req.getToken()

print(token)

Parameters for the direct post

The following table lists the parameters that can be included in the direct post from the 'Account Details' page to QuickVault.

The HTML for the page is produced in Displaying the 'Account Details' page. Parameters are included as either input fields or hidden fields.

The direct post to QuickVault is shown in Parameters for the direct post. Parameters are posted directly to OnlinePaymentServlet3.

The full URL for the test environment is included in Test URLs and IP addresses. The full URL for the production environment is included in Production URLs and IP addresses.

Mandatory parameters

These are to be included as hidden input fields on the 'Account Details' page.

Parameter Name Description
token The security token given to you by QuickVault. QuickVault will use this token to lookup the parameters that were stored during the secure token request.
communityCode Your QuickVault community code. This value will be provided to you by your implementation manager.

Optional parameters

Parameter Name Description
accountType To be provided if the supplierBusinessCode supports both credit card and bank account registrations. Set to either CREDIT_CARD or DIRECT_DEBIT.

Additional mandatory parameters for credit card registrations only

These are to be included as input fields on the 'Account Details' page.

Parameter Name Description
cardholderName The card holder name entered by the customer.
creditCardNumber The credit card number entered by the customer.
expiryDateMonth The month of the card expiry as entered by the customer in the MM format. e.g. 01 (for January)
expiryDateYear The year of the card expiry as entered by the customer in the yy format. e.g. 17 (for the year 2017)

Additional mandatory parameters for bank account registrations only

These are to be included as input fields on the 'Account Details' page.

Parameter Name Description
accountName The account name entered by the customer.
bsb The BSB entered by the customer.
accountNumber The account number entered by the customer.

Parameters for the redirect

The following table lists the parameters QuickVault will return in the redirect See Displaying the Account Registered page. You can display this data on your 'Account Registered' page.

Mandatory parameters

Parameter Name Description
communityCode Your QuickVault community code. You will be notified of your community code during the implementation.
supplierBusinessCode Your QuickVault supplier business code. This value will be provided to you during the implementation.
action One of the following values will be returned:
  • Registered (if the account was successfully registered)
  • Error (if an error occurred)
customerReferenceNumber The customerReferenceNumber you provided during the secure token request.

Additional mandatory parameters - for credit card registrations only

Parameter Name Description
cardholderName The card holder name entered by the customer. For example: John Smith
maskedCardNumber The credit card number the customer entered. For security reasons part of this number will be masked. For example: 45647...004
expiryDateMonth The month of the card expiry as entered by the customer in the MM format. e.g. 01 (for January)
expiryDateYear The year of the card expiry as entered by the customer in the yy format. e.g. 17 (for the year 2017)
cardScheme The type of credit card the customer registered. QuickVault will return one of the following values:
  • VISA
  • MASTERCARD
  • AMEX
  • DINERS
  • JCB
  • UNIONPAY

Additional mandatory parameters - for bank account registrations only

Parameter Name Description
bsb The BSB entered by the customer. For security reasons this number will be masked. For example: xxx-000
accountNumber The account number entered by the customer. For security reasons this number will be masked. For example: xxxxxx678
accountName The account name entered by the customer.

Optional parameters

Parameter Name Description
preregistrationCode If your solution uses client generated tokens, this parameter will not be included. If your solution uses QuickVault generated tokens, this will be populated with the account token that QuickVault created at the time of registration.

Custom parameters

Parameter Name Description
Custom fields Any custom parameters that you included in the handoff will be provided back to you. That is, any parameters prefixed with custom will be included in the redirect.
For example
customTitle
customAge

Requirements checklist

Download the Checklist.

The purpose of this section is to help identify your requirements. Use the checklist as follows:

  1. Download the requirements checklist and rename it with your company name.
  2. Complete as much of the checklist as you can before your first meeting with Westpac.
  3. Use the checklist to understand the steps required to implement this product.