QuickVault Web Registration

QuickVault Web registration is a Westpac hosted service that captures 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 web 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 the registration solution called web registration. For information about the other solutions please read the QuickVault Summary Guide.

What is web registration?

Web registration is a Westpac hosted service that captures 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 first log on to your website. Then at the appropriate time, your website will redirect the customer's browser to a QuickVault webpage. The customer will enter their account details and the account will be stored securely within QuickVault. Once registration is complete QuickVault will redirect the customer's browser back to your website.

The key features of web registration are:

• QuickVault produces the webpage that asks for the customer's account details.
• QuickVault's webpages are customised to look like your website, meaning most customers won't notice the transition from your website to QuickVault.
• Account details are submitted 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 wants to register an account.

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 begin the registration process.

2. When the customer clicks the button your website will redirect the browser to QuickVault. This transition is known as the 'handoff'. Technical details for this process will be discussed in Linking from your website to QuickVault.

3. QuickVault displays the 'Account Details' page. This page asks the customer to enter their credit card details or bank account details. The content and branding of this page will be discussed in Branding QuickVault Web - Account Details Page

4. QuickVault stores the account.

5. QuickVault displays the 'Account Registered' page. This page includes a button linking back to your website. Note, it is not mandatory for QuickVault to show the 'Account Registered' page. If you prefer, you can display your own version of the page (or some other page). This option will be discussed further in Branding QuickVault Web - Account Registered Page

   Note

   QuickVault can also provide a registration notification directly to your server at this point. This is known as the server-to-server postback and is discussed further in Receiving registration details. The purpose of this message is to:

   • Let you know the account was successfully registered
   • Provide you with a summary of the account (eg, cardholder name, card scheme)
   • Provide you with the unique token registered against the account

   Your system will then:

   • Find the customer in your system
   • Store the account summary if necessary
   • Store the account token if necessary

6. QuickVault returns the customer back to your website. This is known as the 'passback'. Technical details for this process will be discussed in Linking from QuickVault back to your website.

7. Your website displays the appropriate page to the customer.

Implementation process overview

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 number is listed in the table below.

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.

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.

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 single account model)

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

1. The customer visits your website.
2. When it is time to register an account, your system will handoff to QuickVault. During this step you will provide your account token to QuickVault (via the 'customerReferenceNumber' parameter). This token is a value that uniquely identifies the customer. For example, the customer reference number or member ID. Note, this diagram shows a simplified view of the handoff process. The actual handoff is more complex and involves a number of sub-steps. This will be discussed further below.
3. The customer enters their account details into the QuickVault webpage.
4. QuickVault stores the account token and account details.
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 single account model)

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

1. The customer visits your website.
2. When it is time to register an account, your system will handoff to QuickVault. During this step 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. Note, this diagram shows a simplified view of the handoff process. The actual handoff is more complex and involves a number of sub-steps. This is discussed further below.
3. The customer enters their account details into the QuickVault webpage.
4. QuickVault creates the account token. There are a number of ways this token can be formatted.
5. QuickVault stores the account token and account details.
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.

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

1. The customer visits your website.
2. When it is time to register an account, your system will handoff to QuickVault. During this step your system will provide a customer ID (via the 'customerReferenceNumber' parameter). The customer ID is a value that represents the owner of the account. For example, a customer's reference number or member ID. Technical details for the handoff will be discussed further below.
3. The customer enters their account details into the QuickVault webpage.
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 you may need to store the card scheme if your system is going to calculate a 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.

Branding QuickVault Web

This section describes the QuickVault webpages that are involved in the registration process and explains how we can tailor their appearance and behaviour to meet your needs. This process is referred to as 'branding QuickVault'.

Branding is a task we like to complete in the early stages of the implementation. It allows us to identify your needs and develop a working set of webpages for you to examine in our test environment. This will then allow you to quickly identify any issues and provide us with feedback.

In general it takes 6 weeks to develop a branded set of QuickVault webpages. This will vary depending on your requirements. We also expect there will be 2-3 iterations before the final release.

Defining requirements

There are a number of decisions that need to be made during the branding process. These include:

• The layout of the page
• The size and location of images
• The name and position of buttons and links
• The size and font of the text
• The data you want your customer to enter in QuickVault
• The data you want your customer to enter in your website rather than QuickVault
• Whether there is additional data you want to pass from your website and have QuickVault display
• Whether QuickVault is to display the Account Registered page or your system is to display its own version of the page

There are three ways you can provide us with your branding information:

1. Provide the URL of your existing website for us to copy

   If you would like to have the same look and feel as your existing website, you can provide us with the URL of your website. We will then use your website as our branding guideline for developing your QuickVault pages.

2. Provide a branding guide for us to use

   If your business has a branding guide or a style guide for website development and you would like us to follow that guide, send us a copy of your branding guide. We will then use this as our branding guideline for developing your QuickVault pages.

3. Provide a branded version of the QuickVault click-through

QuickVault webpages

This section describes the QuickVault webpages that are involved when registering a credit card or bank account. Sample screenshots have been included to help describe each page. These are example screenshots only, as part of the branding process we can change the look and feel of the page, the data we show to the customer and the data we request from the customer.

The basic QuickVault webpages are:

1. Account Details page
2. Account Registered page

Account details page

This is the first page QuickVault will display to the customer.

Account Details Page - Credit Cards

The fields for the 'Account Details' page are described in the following table:

Additional information:

• The 'Cancel' button will take the customer back to your website.
• The 'Save' button will instruct QuickVault to attempt the registration.
• If the registration is unsuccessful an error message will be displayed.
• If the registration is successful the Account Registered page will be displayed. You can choose to have QuickVault display this page or you can display your own version of the page.
• QuickVault can provide your server with a registration summary at this point. See Server to server notification.

Account registered page

This page is shown after the credit card is registered. You can choose to have QuickVault display the page or if you prefer you can display your own version of this page.

Account Registered Page - Credit Cards

The data on this page is described in the following table:

Additional information:

• The 'Finish' button will take the customer back to your website.

QuickVault webpages for bank accounts

This section describes the webpages responsible for bank account registrations. Similar to credit card registrations, these pages can be branded to match your existing website.

There are 2 QuickVault webpages that take part in the registration process. They are:

1. Account Details page
2. Account Registered page

Account details page

This is the first page displayed to the customer when registering a bank account.

Account Details Page - Bank Accounts

The fields for the 'Account Details' page are described in the following table:

Additional information:

• A Direct Debit Request (DDR) Service Agreement is required for bank account registrations. It is written by your organisation and outlines the terms and conditions for making direct debit payments.
• The customer must agree to the terms and conditions before saving their account details. This is done by ticking the checkbox that is positioned under the service agreement.
• The 'Cancel' button will take the customer back to your website.
• The 'Save' button will instruct QuickVault to attempt the registration.
• If the registration is unsuccessful an error message will appear.
• If the registration is successful the Account Registered page will be displayed. You can choose to have QuickVault display this page or you can display your own version of the page.
• QuickVault can provide your server with a registration summary at this point. This feature is discussed in Receiving registration details from QuickVault.

Account registered page

This page is shown after the bank account is registered. You can choose to have QuickVault display the page or if you prefer you can display your own version of this page.

Account Registered Page - Bank Accounts

The data on this page is described in the following table:

Additional information:

• The 'Finish' button will take the customer back to your website.

QuickVault test poster

The test poster is a webpage that allows you to easily access the QuickVault registration pages in our test environment. The test poster is for the test environment only. It will not exist in the live production environment. The purpose of this webpage is to simulate the handoff from your website to QuickVault. This means you can review the branded QuickVault pages before you implement your handoff.

The following screenshot is an example of a test poster.

QuickVault Web Test Poster

The test poster is divided into two sections:

• The top section lists the parameters we expect your server to pass to QuickVault in the first part of the handoff (ie the secure token request. See Linking from your website to QuickVault).

  When the 'Generate Token' button is clicked the webpage will generate a session token and place it in the 'token' field (shown in the bottom section).

• The bottom section lists the parameters we expect the customer's browser to pass to QuickVault in the second part of the handoff (i.e. the browser redirect. See Linking from your website to QuickVault). After you click the 'Submit' button the QuickVault 'Account Details' page will appear.

  Note, this is an example test poster only. The list of parameters in your test poster may vary depending on your requirements.

Linking from your website to QuickVault

The purpose of this section is to explain in detail how to link your website to QuickVault. This process is known as the 'handoff'. A high level description of the handoff can be seen in How does the regstration process work.

As part of the handoff your system will send a list of parameters to QuickVault. This is done via a secure token request.

Sending parameters via secure token request

The secure token request allows parameters to be sent directly from your server to QuickVault. This prevents parameters from being tampered with before being sent to QuickVault.

In order to use the secure token request 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

The parameters for this handoff are listed in Handoff parameters.

To help explain the handoff two diagrams have been included:

The first shows the handoff from your customer's point of view.

The second is a sequence diagram showing each of the technical steps involved in the handoff process.

The steps for the handoff are as follows:

1. Click 'Register account'

   After your website displays the 'Customer Details' page the customer clicks the 'Register account' button. The handoff begins here.

2. Send request

   The customer's browser sends a request to your server to initiate the handoff.

3. Retrieve data

   Your server retrieves all the data that needs to be passed to QuickVault. It then builds a parameter list that will be sent to QuickVault as part of the secure token request. For more detail see Parameters for the secure token request.

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 unique security token is created for every request. For example:

   token=m378813qtvOtylVTvVvpWA7PT14QHltr-AqX2gZ-RFM

   The security token is valid for 1 hour after it is created and can only be used once.

   Do not confuse this security token with the account token described in [Generating the account token](#generating-the-account-token). Although they have similar names these tokens play different roles in the registration process.

6. Return security token

   QuickVault returns the security token to your sever.

7. Redirect

   Your server tells the customer's browser to redirect to QuickVault. A list of parameters is included in the redirect. For details see Passback parameters.

8. Request 'Account Details' page

   The customer's browser redirects to QuickVault. The list of parameters from the previous step is included in the redirect.

9. Verify security token & lookup parameters

   QuickVault checks the security token to make sure it hasn't been tampered with. It then uses this token to lookup the parameters that your server passed to QuickVault during the token request (see steps 4 and 5). The token is then destroyed.

10. Return html for 'Account Details' page

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

The handoff ends here.

Linking from QuickVault back to your website

This section explains how the customer can return to your website after registering an account with QuickVault. This process is known as the 'passback'. A high level description of the passback can be seen in How does the registration process work?.

There are two ways the customer can return to your website. Once the account is registered you can have either a:

• QuickVault webpage with a link to your website
• QuickVault redirect immediately to your website

QuickVault webpage with a link to your website

With this option, QuickVault will display an 'Account Registered' page after the account is registered. This page tells the customer the account has been successfully registered and includes a button that links back to your website. The passback occurs when the customer clicks that button.

The diagram below is an example of what QuickVault will display to the customer.

The sequence diagram below shows the technical steps that take place during the passback.

The steps for the above sequence diagram are:

1. Click 'Save'

   The customer enters their account details into the 'Account Details' page then clicks 'Save'.

2. Send request

   The customer's browser sends the request to QuickVault.

3. Store account details

   QuickVault stores the customer's account details.

4. Return html for 'Account Registered' page

   QuickVault builds the html for the 'Account Registered' page. The page includes a button that links back to your website. The button will link to the returnUrl you provided in the handoff (see Linking from QuickVault back to your website for details about the handoff). QuickVault returns the html to the customer's browser.

5. Click 'Finish'

   The customer views QuickVault's 'Account Registered' page. When they have finished reading the details they click the 'Finish' button. The passback begins here.

6. Request next page

   The customer's browser asks your server for the next page.

7. Return html for next page

   Your server returns the html for the next page. The passback ends here.

QuickVault redirect immediately to your website

With this option, QuickVault will return the customer to your website immediately after the account is registered. Your website will then show its own 'Account Registered' page (or your preferred page). QuickVault will include a number of parameters in the redirect. They will be included as a list of ampersand delimited parameters.

The parameters that QuickVault will return in the passback are listed in Passback parameters.

The diagram below is an example of what QuickVault will display to the customer if you choose this option.

The sequence diagram below shows the technical steps that take place during the passback.

The steps for the above sequence diagram are:

1. Click 'Save'

   The customer enters their account details into the 'Account Details' page then clicks 'Save'.

2. Send request

   The customer's browser sends the request to QuickVault to register the account.

3. Store account details

   QuickVault stores the account details.

4. Redirect

   The passback begins here.

   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 Passback parameters.

   QuickVault then instructs the customer's browser to redirect to the returnUrl (a value provided earlier in the handoff). Our default method for sending data is via HTTP get. If you prefer a HTTP post please advise your implementation manager.

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.

The passback ends here.

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:

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:

• Whitelist the IP addresses for the Secure Token Requests
• Whitelist the domain addresses for the Server to server notification
• View your connection details, including your credentials for authentication with QuickStream.

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
   • Test: https://quickstream.support.qvalent.com/quickportal
   • Production: https://quickstream.westpac.com.au/quickportal
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.

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
   • Test: https://quickstream.support.qvalent.com/quickportal
   • Production: https://quickstream.westpac.com.au/quickportal
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.

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
   • Test: https://quickstream.support.qvalent.com/quickportal
   • Production: https://quickstream.westpac.com.au/quickportal
2. Click Administration -> Facility Settings -> View Connection Details
3. Select Secure Token Request to view connection details for the Secure Token Request.

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
   • Test: https://quickstream.support.qvalent.com/quickportal
   • Production: https://quickstream.westpac.com.au/quickportal
2. Click Administration -> Facility Settings -> Manage Server to Server Notification

Destination URL

This option can be used for:

• QuickWeb
• QuickWeb Recurring
• QuickWeb Invoicing
• QuickConnect
• QuickVault Web
• QuickVault Connect
• QuickTerminal
• QuickVoice

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.

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.

For example the following setting produces a schedule:

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:

• Unsuccessful secure token request attempts.

• Unsuccessful server to server notification sending attempts.

• Sign into QuickStream Portal

  • Test: https://quickstream.support.qvalent.com/quickportal
  • Production: https://quickstream.westpac.com.au/quickportal

• Click Administration -> Activity Log

• Select the date you wish to view logs for.

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.

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

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

Our connectivity tests covered:

• Sending Registration Request Files to QuickVault using iLink
• Retrieving Registration Response Files from iLink or QuickStream Portal.
• Uploading the Registration Response File into our system

Our QuickStream admin tests covered:

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

The QuickStream suite of products complies with Level 1 of the Payment Card Industry Data Security Standard (PCI DSS). The PCI DSS is a multifaceted security standard that includes requirements for

• security management
• policies
• procedures
• network architecture
• software design
• critical protective measures.

For more information on PCI DSS see PCI Data Security Standards.

To ensure QuickStream maintains this high level of security there are a number of security requirements that must be adhered to. These are listed below.

No client specific dynamic content

QuickStream hosted solution (e.g. QuickWeb) payment pages will not contain any client specified dynamic content. This means that you cannot provide javascript or flash components to be used in these solutions. In particular no site measurement javascript or links will be added to any QuickStream page.

QuickStream pages contain sensitive data such as credit card details. The restrictions mentioned above help prevent attacks such as cross site scripting (XSS).

No remote assets

QuickStream hosted solution (e.g. QuickWeb) payment pages will not fetch content from any third party server. All branding resources such as images and stylesheets will be stored on and served from QuickStream servers.

Cookies are required

QuickStream requires session cookies to be enabled in your customer's browser. Session cookies are only used to maintain state while accessing QuickStream. No permanent information is stored on the client's computer once the browser is closed.

Trusting the QuickStream server

When your server exchanges information with QuickStream over HTTPS it must trust the root level certificate. That is, your server must trust the certificate issued by Verisign - not the certificated 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 QuickStream implementation will cease to operate when a replacement certificate is installed.

Excessive failures - IP blacklisting

To prevent fraud, Qvalent will monitor IP addresses and transactions. If any suspicious behaviour is detected we will blacklist the IP address to prevent it from accessing QuickStream again.

Captcha

QuickStream hosted solutions (e.g. QuickWeb) uses Captcha image protection to prevent hackers from using the website to validate stolen credit card details. The term CAPTCHA stands for "Completely Automated Public Turing test to tell Computers and Humans Apart". The Captcha program randomly generates a distorted "word" that humans can read but computer programs can't.

For more information about Captcha see http://www.captcha.net/.

Web analytics

QuickWeb processes payments using the most up to date security best practices. Analytics sends usage data from hosted payment pages via the web browser to a third party system which cannot be guaranteed as secure and may comprise the sensitive data of your customers.

Due to this, hosted payment page solutions (e.g. QuickWeb and QuickVault Web) do not support incorporating analytics code or tools where data is gathered in the customer's browser.

Transport layer security (TLS)

QuickWeb, QuickConnect and QuickVault require Secure Token Handoff and web browser access made using the encryption standard known as TLSv1.2. QuickWeb, QuickConnect and QuickVault rejects request 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.

Standard network ports for HTTP transmissions

QuickStream sends Payment and Registration Notifications (aka Server to Server Responses) via HTTP on standard ports. These are ports 80 and 443. Other network ports are not available to send Payment and Registration Notifications to your server.

Handoff parameters

This section lists the parameters you can pass to QuickVault during the handoff. Parameters are sent to QuickVault in two separate calls. There are:

1. Parameters for the secure token request
2. Parameters for the redirect

Parameters for the secure token request

The following table lists the parameters that can be passed to QuickVault during the secure token request. See Linking from QuickVault back to your website.

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.

Parameters for the redirect

The following table lists the parameters that must be included in the redirect to QuickVault. See Linking from QuickVault back to your website.

You must pass these parameters 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.

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)

Passback parameters

The following table lists the parameters that QuickVault will return in the passback. You can then present this data to your customer. For more details about the passback see Linking from QuickVault back to your website.

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.