QuickWeb Recurring

QuickWeb Recurring is a set of Westpac hosted payment pages that allow your customers to set up and manage recurring payments online.

Demo Creation Flow Demo Management Flow

This page describes QuickWeb Recurring. Other types of QuickWeb are:

• QuickWeb Standard - Customisable hosted payment pages for payments by credit card and bank account.
• QuickWeb Invoicing - Your customers view and pay for invoices and bills.

What is QuickWeb?

QuickWeb is a set of Westpac hosted payment pages. Your website directs your customer to pay using QuickWeb by credit card or bank account.

See QuickWeb Technical Implementation Guide for more.

What is recurring?

QuickStream has four interfaces to standard recurring payment functions:

1. File interface - Recurring Batch
2. Client (you) facing web interface - QuickStream Portal
3. Customer (your customer) facing web interface - QuickWeb Recurring
4. Administration interface - QuickStream Portal

The recurring payment functions in QuickStream are collectively known as Recurring.

A recurring payment is a payment made in regular instalments according to a predefined schedule. You can define the regular instalment amount and define a schedule. A schedule has:

• a type, which defines when to conclude the schedule, and
• a frequency which defines how often the regular instalment is taken from your customer.

What is QuickWeb Recurring?

Using QuickWeb Recurring, your customers can set up and manage recurring payments online. The extra benefits are that your customers can:

• Create a recurring payment schedule.
• Modify recurring payment schedule type, frequency and amount.
• Stop an active recurring payment.
• Re-start a stopped recurring payment.
• Change the payment account details or use a new credit card or bank account.

The product has two flows:

1. Creation flow.
2. Management flow.

Implementing QuickWeb Recurring

To implement QuickWeb Recurring:

1. Define the customisation options and provide those to your Westpac contact.
2. Build the ability to consume the Cash Applied File in your systems.
3. Define a group email address to send notifications about file processing.
4. Define if you will offer only the Creation flow, Management flow or both.
5. Build the ability to hand your customer over to QuickWeb Recurring.
6. Optionally build the ability to receive your customer back from QuickWeb Recurring.
7. Optionally build the ability to consume a server to server response from QuickWeb Recurring.
8. Perform testing in our Test environment.
9. Provide sign-off on your testing.
10. Transition into your Production environment.
11. Perform live testing in our Production environment.
12. Roll out QuickWeb Recurring into your business processes.

Recurring concepts

See Recurring payment schedules for more information about the concepts of recurring payment schedules.

Creation flow

The creation flow below describes the complete set of payment creation functionality available to QuickWeb Recurring. The creation flow has 7 steps.

1. Handoff
2. Enter Customer Details
3. Enter Schedule Details
4. Enter Banking Details
5. Confirm Payment
6. Receipt
7. Passback

The steps are described below and refer to the payment flow diagram.

Hand off

The payer is handed-off from your website to QuickWeb Recurring in this step. See Handoff your customer to QuickWeb.

Related sections:

• Pre-fill the 'enter customer details' step.
• Pre-fill the 'enter schedule details' step.
• Provide the regular payment amount.
• Managing your security settings.
• Parameters for the Secure token request.
• Parameters for the Form inputs handoff.

Enter customer details

The payer enters their details. You may choose to collect additional address details. Collecting an email address and/or a mobile phone number allows notifications to be sent to payers for payment events. A customer may have one or more recurring payments.

Related sections:

• Pre-fill the 'enter customer details' step.
• Send notifications on management and payment events.
• Management flow.
• Change the look and feel of the pages.
• Pre-fill the Enter customer details step
• Send notifications on management and payment events.

Enter schedule details

The payer chooses their payment schedule details. See Payment schedule types.

Things to note:

• When the first payment date is today, the payment will be made after the Confirm payment step.
• Choosing Stop after a set number of payments displays a field to enter the number of payments.
  • 
• Choosing Stop after a total amount displays a field to enter the total amount of payments.
  • 
• Choosing Continue until date displays a field to enter the schedule end date.
  • 

Related sections:

• Payment schedule types.
• Change the look and feel of the pages.
• Pre-fill the Enter schedule details step.
• Provide the regular payment amount.
• Management flow.
• Restrict the schedule types and frequencies a payer can choose.
• Send notifications on management and payment events.

Enter banking details

The payer will enter their credit card or bank account details. When a surcharge is applicable, the surcharge rates are displayed.

Related sections:

• Change the look and feel of the pages.
• Register the payment account in QuickVault
• Restrict a payer to only credit card payments or bank account payments
• Management flow.
• Send notifications on management and payment events.

Confirm payment

The payer will confirm their payment details. When a surcharge is applicable, the new amount is displayed and the payer must tick a checkbox to continue.

If the payment is identified as a duplicate, the payer must tick a checkbox to continue.

The payer must complete a CAPTCHA challenge before the payment is made.

Related sections:

• Change the look and feel of the pages.
• Duplicate payment checking
• QuickWeb redirects to your receipt page

Receipt

The details of the new schedule created for the customer is displayed. If the first payment date was today, a payment will be attempted. The payer will view the details of the successful or declined payment. The payer can enter an email address to send a receipt via email.

Related sections:

• Change the look and feel of the pages.
• Change the look and feel of the payment receipt.
• Register the payment account in QuickVault.
• Management flow.
• QuickWeb redirects to your receipt page.
• QuickWeb receipt page links to your website.

Passback

Your customer is passed back from QuickWeb Recurring to your website in this step. See Handoff your customer back to your website.

Related sections:

• Parameters in the Passback.
• Managing your security settings.
• Receiving payment details.

Management flow

The management flow below describes the complete set of management functionality available to QuickWeb Recurring. The management flow has 7 steps.

1. Handoff
2. Verify Account
3. View Recurring Payments
4. Manage Recurring Payment
   • Change Banking Details
   • Stop/Start Payment
   • Change Schedule Details

The steps are described below and refer to the payment flow diagram.

Hand off

The payer is handed-off from your website to QuickWeb Recurring in this step. See Handoff your customer to QuickWeb.

Set the allowRecurringManagement parameter to true in the Secure token handoff to access the management flow.

Related sections:

• Bypass the account verification step.
• Managing your security settings.
• Parameters for the Secure token request.

Verify account

The payer must be verified before they can manage recurring payments. There are two pieces of information that must be provided:

• Customer reference number - your unique identifier for a customer. This is provided for new customers via the creation flow, or via Recurring Batch.
• Existing schedule identifier - a unique identifier for a customer's recurring payment schedule. This is provided for customers via the creation flow, or via Recurring Batch.

The payer enters both pieces of information correctly and proceeds to the View Recurring Payments step.

Related sections:

• Verify account step failures.
• Change the look and feel of the pages.
• Bypass the Account Verification step.
• Change the Existing schedule identifier in the account verification to a custom lookup.
• See Recurring Batch for more on uploading customer and schedule information.

View recurring payments

QuickWeb displays the customer number, name and a list of recurring payments. For each recurring payment, QuickWeb displays the following:

• Schedule identifier. This is a unique identifier generated by QuickWeb, or provided by you via Recurring Batch.
• Description. An automatically generated description of the recurring payment. The description changes based on the amount, account and Payment schedule type.
• Status. Either Active, Stopped or Complete. An Active recurring payment will take payments on schedule. Stopped recurring payments are stopped indefinitely, and do not take recurring payments. A Complete recurring payment has finished the payment schedule and cannot be re-started.
• Payment Account. The masked credit card or bank account details.

Select Manage to manage the recurring payment. Select View to show details of a completed recurring payment. Select Finish to start the passback.

Related sections:

• Change the look and feel of the pages.
• Restrict the management options a payer can access.
• Send notifications on management and payment events.
• Session timeouts.

Manage recurring payment

QuickWeb displays details of the selected recurring payment. The payer can choose to:

1. Change banking details.
2. Stop/Start payments.
3. Change the schedule details.
4. Go back to view recurring payments.

Related sections:

• Change the look and feel of the pages.
• Restrict the management options a payer can access.
• Send notifications on management and payment events.

Change banking details

A payer can change to a new credit card or bank account. To change an expiry date or account name, a payer will add a new account. A payer can choose existing accounts. QuickWeb displays QuickVault accounts if QuickVault is enabled for your facility.

Related sections:

• Change the look and feel of the pages.
• Restrict a payer to only credit card payments or bank account payments.
• Send notifications on management and payment events.

Stop/Start payments

A payer can stop an Active recurring payment. Stopping a recurring payment takes effect immediately. A payer can also restart a Stopped recurring payment. The restarted recurring payment will start again on the next calendar day.

Related sections:

• Change the look and feel of the pages.
• Send notifications on management and payment events.
• Recurring concepts.

Change schedule details

A payer can change details of a recurring payment. See Payment Schedule Types for more.

Related sections:

• Change the look and feel of the pages.
• Send notifications on management and payment events.
• Restrict the schedule types and frequencies a payer can choose.
• Recurring concepts.

Customising QuickWeb Recurring

When a test QuickWeb Recurring facility is provided to you, it will have the maximum amount of features the product offers. You can then choose to change or remove some features. This is done during your Westpac implementation project. Customisation options include:

• Change the look and feel of the pages.
• Change the look and feel of the payment receipt.
• Bypass the account verification step.
• Pre-fill the 'enter customer details' step.
• Pre-fill the 'enter schedule details' step.
• Provide the regular payment amount.
• Change the 'existing schedule identifier' in the account verification to a custom lookup (charges may apply).
• Register the payment account in QuickVault.
• Restrict a payer to only credit card payments or bank account payments.
• Restrict the schedule types and frequencies a payer can choose.
• Restrict the management options a payer can access.
• Send notifications on management and payment events.

Each of these items is explained in the sections below.

Change the look and feel of the pages

The QuickWeb Recurring pages have a default Westpac brand. You may change this to look like your customer-facing website. To accomplish this, provide one or more of the following to your Westpac contact:

• A URL to the brand website.
• Provide style guide and brand documentation.
• Change the look and feel of the QuickWeb Click-through.

Applies to the creation flow and management flow.

Download QuickWeb click-through

Download the QuickWeb click-through, brand the web pages and provide them back to your Westpac contact.

Download Click-through

Change the look and feel of the payment receipt

The payment receipt has a default Westpac brand. It includes recurring payment and immediate payment information. You may change this to look like existing payment receipts, and show less information.

Applies to the creation flow only.

Bypass the account verification step

You can partially or fully bypass the account verification step as follows:

• Provide customerReferenceNumber in a Secure Token Request to remove the Customer Reference Number field from the Account Verification step.
• Provide secondaryIdentifier in a Secure Token Request to remove the Existing Schedule Identifier field from the Account Verification step.
• Provide both customerReferenceNumber and secondaryIdentifier in a Secure Token Request to skip the page entirely.

The payer will be taken to the View Recurring Payments step. Refer to Parameters for the Secure Token Request.

Applies to the management flow only.

Pre-fill the enter customer details step

To pre-fill the mandatory customer details, provide the following parameters in a Secure Token Request:

• customerReferenceNumber
• receiptEmailAddress
• phoneNumber

See Parameters for secure token request.

To skip this step when the mandatory fields are provided in a Secure Token Request, raise this with your Westpac contact.

Applies to the creation flow only.

Pre-fill the enter schedule details step

To pre-fill the mandatory schedule details, provide the following parameters in a Secure Token Request:

• recurringScheduleCode
• recurringScheduleFirstDate
• recurringScheduleFrequency
• recurringSchedule

See Parameters for secure token request.

To skip this step when the mandatory fields are provided in a Secure Token Request, raise this with your Westpac contact.

Applies to the creation flow only.

Provide the regular payment amount

To provide the regular payment amount, provide the principalAmount parameter in a Secure Token Request. The payer will not enter this amount. Surcharges are calculated on top of this amount.

See Parameters for secure token request.

Applies to the creation flow only.

Change the existing schedule identifier in the account verification to a custom lookup

The account verification step requires two pieces of information to verify a payer:

• A customer reference number
• A secondary reference number

The customer reference number uniquely identifies your customer. It is provided via new schedules during the creation flow or Recurring Batch. Recurring payments are allocated to a customer.

The secondary reference number defaults to an Existing Schedule Code. You may wish to change this to another piece of information. You must provide this value for your customer in the Customer upload request file or during the creation flow. Discuss this option with your Westpac contact. Charges may apply.

Applies to the management flow only.

Register the payment account in QuickVault

QuickWeb Recurring registers any account used for a new recurring schedule in QuickVault when it is enabled for your facility. The preregistrationCode is provided in the passback and Customer snapshot file. It may also be reported in the daily registered accounts report.

See QuickVault Summary and related docs for more on QuickVault.

Applies to the creation flow and management flow.

Restrict a payer to only credit card payments or bank account payments

You can instruct QuickWeb Recurring to restrict a payer to only credit card payments or bank account payments. To do this, provide the accountType parameter in a Secure Token Request.

Applies to the creation flow and management flow.

Restrict the schedule types and frequencies a payer can choose

You can instruct QuickWeb Recurring to restrict a payer to a particular frequency for new recurring payments. To do this, provide the recurringScheduleFrequency parameter in a Secure Token Request during the creation flow.

To restrict the list available to a subset of the available frequencies, raise this with your Westpac contact.

Applies to the creation flow and management flow.

Restrict the management options a payer can access

To restrict the available options a payer can access in the management flow, define this with your Westpac contact.

Applies to the management flow only.

Send notifications on management and payment events

QuickStream can send notifications about payment events to your customers on your behalf. These notifications can be sent as an email or an SMS message.

Find out more.

Applies to the creation flow and management flow.

Duplicate payment checking

QuickWeb performs duplicate transaction checks in order to reduce the instances of accidental double payment.

What is a duplicate?

A transaction is considered a duplicate if there is a previous transaction that matches all these criteria:

• has the same credit card number (but not necessarily expiry date) or bank account BSB and account number
• is for the same merchant
• is for the same amount
• is approved or currently processing
• is not a QuickBatch transaction (but could be QuickVoice, QuickConnect, etc)
• is for the current settlement date

What is displayed to the cardholder?

The card holder is warned of the duplicate and must tick a box in order to continue processing.

Can I disable the duplicate check?

Not directly. The duplicate check may be removed if required. Charges may apply.

Verify account step failures

The account verification step requires two pieces of information to verify a payer:

• A customer reference number
• A secondary reference number

If the payer enters either piece of information incorrectly they will see an error.

If the payer enters either piece of information incorrectly 20 times, their IP address will be blacklisted by the system.

When an IP address is blacklisted, the IP address is blocked from all Qvalent services.

To have an IP address removed, a contact from your company must report this to the QuickStream Technical Support team. A member of the QuickStream Technical Support team must be able to identify you as a user of QuickStream Portal or an approved contact with the team. To update your approved contacts that are not also users in QuickStream Portal, contact the QuickStream Technical Support team when your solution goes live.

Session timeouts

QuickWeb's session lasts for 15 minutes. After 10 minutes of inactivity, QuickWeb displays a pop-up. The pop-up warns the user that their session is about to expire.

This can occur on any page in both the creation flow and the management flow.

When a user selects:

• End Session, QuickWeb initiates the passback to cancelUrl.
• Continue, QuickWeb extends the users' session for another 15 minutes.

The pop-up displays for 5 minutes of inactivity. If after 15 minutes of inactivity, the user takes an action such as clicking the buttons in the popup or refreshing the page, QuickWeb redirect the user to the Session Timeout page.

This page can be branded if required.

Handoff your customer to QuickWeb

To handoff your customer from your website to QuickWeb, choose one of the following options:

1. Secure token handoff
2. Form inputs handoff

Both options require you to send parameters to QuickWeb that identify you to QuickWeb and serve up your payment pages.

Secure token handoff

The secure token request is Westpac's recommended method for sending parameters. It allows the parameters to be sent directly from your server to QuickWeb. This prevents the customer from being able to tamper with the parameters before they are sent to QuickWeb.

In order to perform a secure token request you will require:

• a dynamic backend which can send a HTTPS POST directly to the QuickWeb server.
• the ability to make an outbound HTTPS connection to QuickWeb through your proxy and firewall.
• your allowed IP addresses whitelisted in QuickStream Portal.
• your credentials from QuickStream Portal.

The secure token handoff has two steps:

1. Secure token request. Your server requests a Security Token from QuickWeb.
2. Handoff. Your website uses the Secure Token to hand off your customer to QuickWeb.

Example secure token request

POST /CommunityTokenRequestServlet HTTP/1.1
Host: ws.qvalent.com
Accept: text/plain
Content-Type: application/x-www-form-urlencoded

cancelUrl=https%3A%2F%2Fyoursite.com.au%2Fcancelled
&connectionType=QUICKWEB
&currencyCode=AUD
&errorEmailToAddress=errors%40yoursite.com.au
&password=<YOUR_FACILITY_PASSWORD>
&product=RECURRING
&returnUrl=https%3A%2F%2Fyoursite.com.au%2Fthankyou
&serverReturnUrl=https%3A%2F%2Fyoursite.com.au%2FreceiveRequest
&supplierBusinessCode=<YOUR_SUPPLIER_BUSINESS_CODE>
&username=<YOUR_FACILITY_USERNAME>

Example response

token=OicksakIMkD3OiZpyE7MadwJkZSrSqgjviXCEomVD3ZzEmZ6Vlxecg

Example handoff

<form action="https://quickweb.westpac.com.au/OnlinePaymentServlet3" method="POST">
    <input type="hidden" name="token" value="OicksakIMkD3OiZpyE7MadwJkZSrSqgjviXCEomVD3ZzEmZ6Vlxecg"/>
    <input type="hidden" name="communityCode" value="<YOUR_COMMUNITY_CODE>"/>
    <input type="submit" value="Make Payment"/>
</form>

QuickWeb validates the IP address of a secure token request. White list your allowed IP addresses in QuickStream Portal.

Along with the security benefits, using the secure token handoff you can:

• Access the management flow.
• Pre-fill the Enter customer details step.
• Pre-fill the Enter schedule details step.
• Provide the regular payment amount.
• Bypass the account verification step.
• Change the Existing schedule identifier in the account verification to a custom lookup.
• Register the payment account in QuickVault.
• Restrict a payer to only credit card payments or bank account payments.
• Provide additional custom parameters for reporting.
• Receive a server to server payment notification.

Parameters for secure token request

Sign in to QuickStream Portal to get these values in each environment. See View your connection details.

Parameters for handoff

Form inputs handoff

The form inputs handoff is the second option for sending parameters to QuickWeb. It involves all the parameters being sent directly from the customer's browser to QuickWeb. It is an easier method to implement, however, it does allow the customer to tamper with the parameters before they are sent to QuickWeb. Westpac, therefore, recommends using the secure token handoff method instead.

Form handoff example

<form action="https://quickweb.westpac.com.au/OnlinePaymentServlet3" method="POST">
    <input type="hidden" name="product" value="RECURRING"/>
    <input type="hidden" name="communityCode" value="<YOUR_COMMUNITY_CODE>"/>
    <input type="hidden" name="supplierBusinessCode" value="<YOUR_SUPPLIER_BUSINESS_CODE>"/>
    <input type="hidden" name="currencyCode" value="AUD"/>
    <input type="hidden" name="returnUrl" value="https://yoursite.com.au/thankyou"/>
    <input type="hidden" name="cancelUrl" value="https://yoursite.com.au/cancelled"/>
    <input type="submit" value="Make Payment"/>
</form>

When using a form inputs handoff your customer must proceed through the account verification step.

Parameters for form inputs handoff

Sign in to QuickStream Portal to get these values in each environment. See View your connection details.

Handoff your customer back to your website

This processing is referred to as the passback. The passback involves redirecting your customer to the URL you have specified in the returnUrl or cancelUrl parameters. This redirect has parameters that you can use to display information back to your customer on your website. The redirect is a HTTP GET by default. Raise with your Westpac contact if this should be a HTTP POST to your website.

Before implementing the pass back you must decide when you would like the customer to return to your website after a payment attempt:

• QuickWeb receipt page links to your website specified in returnUrl.
• QuickWeb redirects to your website for you to show the receipt page specified in returnUrl.

These options are discussed in the sections below.

QuickWeb receipt page links to your website

In this option QuickWeb will display its own receipt page to the customer. The receipt page includes a button that links back to your website. The passback occurs when the customer clicks the button.

QuickWeb redirects to your receipt page

In this option QuickWeb will return the customer to your website immediately after the payment is made. That is, your customer will see the Confirm Payment page and when QuickWeb processes the payment, it will redirect the customer to returnUrl. The QuickWeb receipt page is not displayed.

Your website will then show a receipt page to the customer. QuickWeb will include a number of parameters in the redirect. They will be included as a list of ampersand delimited parameters.

The parameters that QuickWeb will return are listed in Parameters returned in passback.

Payer cancels the payment process

When a payer cancels out of the payment process (usually via a Cancel button), QuickWeb will redirect back to your website. Provide the URL in the cancelUrl parameter.

The redirect will include parameters. The receipt number will not be included as no payment was attempted. See Parameters returned in passback.

Parameters returned in passback

Most of the parameters below are returned in the passback from the creation flow. The passback from the management flow includes only a subset of the passback parameters:

• communityCode
• supplierBusinessCode
• customerReferenceNumber
• hmac

For example

GET /thankyou?
communityCode=<YOUR_COMMUNITY_CODE>&amp;
supplierBusinessCode=<YOUR_SUPPLIER_CODE>&amp;
surchargeAmount=0.64&amp;
paymentAmount=32.72&amp;
customerReferenceNumber=123456789&amp;
receiptNumber=1199701986&amp;
responseCode=QS&amp;
responseDescription=Approved+or+completed+successfully&amp;
summaryCode=0&amp;
createdDateTime=23+Jan+2017+13%3A00%3A09&amp;
settlementDate=20170123&amp;
recurringScheduleCode=37659575&amp;
recurringScheduleFirstDate=20170123&amp;
recurringScheduleFrequency=MONTHLY&amp;
recurringSchedule=STOP_AFTER_SET_NUMBER_OF_PAYMENTS&amp;
recurringScheduleTotalAmount=320.80&amp;
recurringScheduleNumberOfPayments=10&amp;
cardholderName=John+Smith&amp;
maskedCardNumber=424242...242&amp;
cardScheme=VISA&amp;
expiryDateMonth=04&amp;
expiryDateYear=2020&amp;
preregistrationCode=YOURCOMPANY77331557&amp;
hmac=ed61ae6d3f8fecc848b5b666a90a059ec7508248761d5b0b63295881d701782f HTTP/1.1
Host: yoursite.com.au

Validating the HMAC

The HMAC is included in the parameters returned in the passback. Use this to validate the parameters in the passback were not tampered.

The parameters in the passback are signed using the HMAC_SHA256 algorithm. Your secure token request password is used as the secret in the HMAC_SHA256 calculation. Find the password by viewing your connection details in QuickStream Portal.

To validate the hmac parameter:

1. Remove hmac from the list of parameters returned and order the parameters ASCIIbetically by name.
2. URL encode each parameter with UTF-8 character encoding.
3. Join the parameter names and values with = and each pair with & (as per a query string).
4. Generate the HMAC from this string using secure token request password.
5. Hexadecimal encode the resulting string.
6. Compare the HMAC string you generated to the hmac parameter in the passback.

HMAC validation example

This example illustrates a simple validation of the hmac parameter in the passback.

Step 1: Get the list of parameters returned in the passback.

Step 2: Remove hmac and order the parameters ASCIIbetically by name.

Step 3: URL encode each parameter with UTF-8 character encoding

Ensure the encoded characters are lowercase and not uppercase (for example, %3A not %3a.)

Step 4: Join the parameter names and values with = and each pair with &.

communityCode=COMCODE&customParam=this+is+a+custom+param+with+special+characters+%26&principalAmount=10.00&supplierBusinessCode=SUPP

Step 5: Generate the HMAC from this string using secure token password.

public static String hash( final String password, final String queryString )
{
    final Mac mac = Mac.getInstance( "HmacSHA256" );
    mac.init( new SecretKeySpec( password.getBytes( "UTF-8" ), "HmacSHA256" ) );
    return Hex.encodeHexString( mac.doFinal( queryString.getBytes() ) );
}

Finally, compare the HMAC string you generated to the hmac parameter in the passback. If the strings do not match, there has likely been tampering of the parameters and their values and should not be considered accurate.

Receiving payment details

QuickWeb provides two ways to receive payment details:

1. Server to server notification
2. Cash Applied File

Server to server notification

This option is also known as the server-to-server postback. It allows you to receive payment summary details after each credit card payment is made and recurring payment schedule is created via the creation flow. This is done via a HTTPS POST from QuickWeb to your server. QuickWeb can post the payment details as form parameters or as XML.

QuickWeb sends separate server to server notifications for successful payments and recurring payment creation.

A server to server notification is not sent for the management flow. You can receive a Customer snapshot file daily to update the state of recurring payments in your system.

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 white list 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 after a successful credit card payment attempt or recurring payment schedule is created via the creation flow.

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 payment summary details.
   • The way you do this will depend on the way QuickWeb has posted the payment 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 for this payment.
   • To do this you will compare the receiptNumber to the receipt numbers you have already processed.
5. Save the payment 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 payment details, your server will instead return a status of 500 Internal Server Error.

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 response

POST /payments HTTP/1.1
Host: yoursite.com.au
Content-Type: application/xml

<PaymentResponse>
    <sourceCode>Net</sourceCode>
    <receiptNumber>1003548481</receiptNumber>
    <communityCode><YOUR_COMMUNITY_CODE></communityCode>
    <supplierBusinessCode><YOUR_SUPPLIER_CODE></supplierBusinessCode>
    <customerReferenceNumber>CUSTOMER1</customerReferenceNumber>
    <paymentReference>PAYMENT1</paymentReference>
    <paymentAmount>624.00</paymentAmount>
    <surchargeAmount>24.00</surchargeAmount>
    <cardScheme>VISA</cardScheme>
    <settlementDate>20170110</settlementDate>
    <createdDateTime>10 Jan 2017 01:11:31</createdDateTime>
    <responseCode>00</responseCode>
    <responseDescription>Approved or completed successfully</responseDescription>
    <summaryCode>0</summaryCode>
    <successFlag>true</successFlag>
</PaymentResponse>

These parameters relate to a recurring payment schedule.

An example XML response for a new recurring payment

POST /payments HTTP/1.1
Host: yoursite.com.au
Content-Type: application/xml

<PaymentResponse>
    <connectionType>QUICKWEB</connectionType>
    <product>RECURRING</product>
    <communityCode><YOUR_COMMUNITY_CODE></communityCode>
    <supplierBusinessCode><YOUR_SUPPLIER_CODE></supplierBusinessCode>
    <customerReferenceNumber>123456789</customerReferenceNumber>
    <recurringScheduleCode>37659576</recurringScheduleCode>
    <recurringScheduleFirstDate>20170123</recurringScheduleFirstDate>
    <recurringScheduleNumberOfPayments>4</recurringScheduleNumberOfPayments>
    <recurringScheduleTotalAmount>100.00</recurringScheduleTotalAmount>
    <recurringScheduleFrequency>WEEKLY</recurringScheduleFrequency>
    <recurringSchedule>STOP_AFTER_SET_AMOUNT</recurringSchedule>
    <paymentAmount>32.72</paymentAmount>
    <surchargeAmount>0.64</surchargeAmount>
    <cardScheme>VISA</cardScheme>
    <cardholderName>John Smith</cardholderName>
    <maskedCardNumber>424242...242</maskedCardNumber>
    <expiryDateMonth>01</expiryDateMonth>
    <expiryDateYear>2020</expiryDateYear>
</PaymentResponse>

Cash Applied File

The purpose of the report is to provide you with a detailed list of all the QuickWeb transactions for that day. You can then load the report into your system and use it to help reconcile your bank statements.

Note:

• It will only include transactions that occur before the 6pm cut off. Any transactions that occur after the cut off will be included in the next file.
• QuickStream generates the Cash Applied File at 8pm (Sydney time) each banking day.
• You can choose to include all the payments in one single file or split the payments into multiple files based on the business group they belong to.
• You can choose to include only the successful transactions or both the successful and rejected transactions.

File format

The standard CSV format is a "comma separated value" file that we have created for our customers. The file consists of one header row followed by multiple detail rows.

There are two types of rows in the Cash Applied File:

The header row contains the field names.

For example

"Settlement Date","Receipt Number","Supplier Business Code","Reference Number", ...etc...

The detail row contains the details for a particular transaction.

For example

"4-Jun-2016","186658002","123456","1200001", ...etc...

The transaction row contains details of your customer's credit card payment or refund. A credit card payment is represented with a positive amount in the Payment Amount column. A credit card refund is represented with a negative amount in the Payment Amount column.

You can choose to have only successful transactions included in the file, or if you prefer you can have both successful and rejected transactions in the file.

Note: in addition to the above data we can also include your custom parameters. That is, any custom parameter you send to QuickStream during the secure token request can be provided in a separate column in this file. If you would like to make use of this feature please advise your implementation manager.

Sample file

Credit card payments only example

"Settlement Date","Receipt Number","Supplier Business Code","Reference Number","Payment Amount","Surcharge Amount","Response Code","Response Description","Summary Code","Soft Decline Code","Retry Attempt Number","Card Scheme","Card Holder Name","Masked Card Number","Created Date Time","Source Product","Parent Receipt Number"
"10-Sep-2012","1003548481","YOURCOMPANY","12345678","34.28","32.95","1.33","00","Approved or completed successfully","0","0","0","VISA","John Smith","456471xxxxxxx004","10-Sep-2012 13:29","RECURRING",""

Bank account payments only example

This example shows a bank account payment within a file that may also have credit card payments.

"Settlement Date","Receipt Number","Supplier Business Code","Payment Reference","Payment Amount","Surcharge Amount","Response Code","Response Description","Summary Code","Soft Decline Code","Retry Attempt Number","Card Scheme","Card or Account Holder Name","Masked Card Number","BSB Number","Account Number","Created Date Time","Source Product","Parent Receipt Number"
"06-Aug-2014 00:00","1176949511","YOURCOMPANY","12345678","100.00","100.00","0.00","G","WBC Exception Processing released successfully","0","0","0","","John Smith","","032-002","123465","06-Aug-2014 01:11","RECURRING",""

Retrieving a Cash Applied File

The file may be retrieved using iLink or available for download in QuickStream Portal.

• iLink is a service that allows you to securely send files to and receive files. You can do this manually or via straight through connectivity that uses SFTP, HTTPS or SOAP.
• QuickStream Portal is the administrative interface for QuickStream products, such as QuickWeb and QuickConnect.

See iLink Documentation for more information.

To download a Cash Applied File from QuickStream Portal:

1. Sign into QuickStream Portal
   • Test: https://quickstream.support.qvalent.com/quickportal
   • Production: https://quickstream.westpac.com.au/quickportal
2. Click Administration -> Transactions and Reports -> Facility Reports
3. Your report will appear on this page.
   • Select the download icon to retrieve a Cash Applied File.
   • Use the date filters to find older files.

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 white list

The IP address white list holds the allowed IP addresses for secure token requests. Requests made from IP addresses that are not in this white list 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 White List
3. Select Add IP Address to white list a new IP address, or select the edit or delete icons to manage existing entries.

Manage your domain white list

The domain white list holds the allowed domains or URLs for sending server to server notifications. Server to server notifications to URLs that are not in this white list 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 White List
3. Select Add Domain to white list a new domain or specific URL, or select the edit or delete icons to manage existing entries.

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

• To receive server to server notifications from any URL on your website, white list yoursite.com.au.
• To receive server to server notifications at a specific URL on your website, white list 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 credit card payment 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 White-list 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.

Handling declined payments

Your customer's financial institution may decline transactions. A declined transaction will receive a Summary Code and a Response Code. Find the full list of Response Codes at Response Codes.

Each response code may describe a hard decline or a soft decline.

• A hard decline indicates the transaction will not likely be successful if retried. For example, Response Code 14 - Invalid Card Number may not be successful if retried.
• A soft decline indicates the transaction can possibly be retried and by successful. For example, Response Code 51 - Not sufficient funds could be retried at a later day.

Response codes indicating a soft decline

Some response codes may indicate a soft decline. A soft declined transaction may indicate the transaction can be retried successfully at a later date.

See Response Codes for details.

Manually retrying payments

QuickStream Portal has a function to list any recurring payments that were soft declined and can be retired.

1. Sign into QuickStream Portal
   • Test: https://quickstream.support.qvalent.com/quickportal
   • Production: https://quickstream.westpac.com.au/quickportal
2. Click Transactions and Reports -> Retry Failed Payments
3. Choose a payment to retry. Either select the receipt number or an option from the context menu to proceed.

Automatically retrying payments

QuickStream Portal allows you to set up a schedule to automatically retry any soft declined payments.

1. Sign into QuickStream Portal
   • Test: https://quickstream.support.qvalent.com/quickportal
   • Production: https://quickstream.westpac.com.au/quickportal
2. Click Administration -> Facility Settings -> Automatic Retry of Failed Payments
3. Choose to automatically retry recurring payments.
   • Select the 1^st, 2^nd and 3^rd failed attempt options to automatically retry 4, 6 or 8 days after each attempt.

Customer snapshot file

You may wish to reconcile the customer details in QuickStream with the details stored in your system. This is helpful when changes are made to customer details, recurring payments or their accounts by other QuickStream products. For example, if you have QuickTerminal Recurring or QuickWeb Recurring then new schedules and accounts may have been created for your customers during a day. QuickStream can send a Customer Snapshot File. This file contains all the details of your customers, their accounts and their recurring payments in QuickStream. This file is sent daily at 01:00 AEST, and contains a full listing of our customer database.

This is an optional feature and you must request this during your Westpac implementation project with your Qvalent resource.

File format

The Customer Snapshot File is a comma-separated value (CSV) file. The following table describes the fields in the file format. This file can be used to keep your systems in sync with QuickStream as changes are made to your customer's set up.

Detail record

Each record describes information about your customer with their accounts and associated payment schedules. Each line has customer and account information. Applicable accounts will also have payment schedule information.

Sample file

This sample file lists one customer with one account and a weekly payment schedule.

Customer Number,Customer Name,Customer Status,Email Address,Phone number,Address Line 1,Address Line 2,Address Line 3,Address Line 4,City,State,Post Code,Country,Notification Medium,AccountID,Account Token,Account Status,Account Name,Masked CC Number,Expiry Date,BSB,Masked Account Number,Plan ID,Payment Status,Description,Frequency,Next Payment Date,Payment Amount
"JOHNSMITH","John B. Smith","ENABLE","jsmith@customer.com","+61421559774","Unit 11","Level 31","Sunset Blvd","Sydney","NSW","2000","EMAIL""JOHNSMITH","123456781","","ENABLE","John Smith","424242xxx242","012019","","","123456781","ENABLE","","WEEKLY","01 Jan 2016","50.00"

Testing

The testing process is also known as User Acceptance Testing or UAT. The purpose of UAT is to test the entire solution as thoroughly as possible. The tests are carried out by the relevant participants from your business. We recommend you create a test plan which details the scenarios your verification team need to cover during their testing.

Our Recurring tests covered:

• Approved transactions
• Declined transactions
• Invalid payment details (eg, invalid credit card number)
• Duplicate payments

Our reporting tests covered:

• Retrieving reports (either via iLink or QuickStream Portal)
• Uploading reports into our system

Our QuickStream Portal administration tests covered:

• Creating users
• Assigning roles to users
• Searching for payments
• Refunding and voiding payments
• Search for customers
• Creating customers
• Modifying customers
• Adding recurring payments to customers
• Modifying recurring payments
• Stopping recurring payments

To support the testing process a test environment is provided. This environment is also known as the 'support environment' or 'support'. It simulates the banking system, allowing you to test credit card payments without affecting any live bank accounts.

The test environment will remain in place after you go live. This will enable you to test any future changes before they are released into production. The test environment is provided on a best-efforts basis. It will occasionally be unavailable due to upgrades to our base products. Please factor this into your testing time lines and raise any concerns you have with your implementation manager.

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 sign off email is included below.

To: Qvalent_implementation_manager

Cc: Westpac_implementation_manager

Subject: Sign off

We have successfully completed user acceptance testing. Our tests covered all areas of the solution. They included payments, reporting and QuickStream Portal admin tasks.

Our payment tests covered:

• Approved transactions
• Declined transactions
• Invalid payment details
• Duplicate payments

Our reporting tests covered:

• Retrieving the daily payment report
• Uploading the payment report into our system

Our QuickStream Portal admin tests covered:

• Creating users
• Assigning roles to users
• Searching for payments
• Refunding payments
• Resending receipts

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

Regards, John Smith

Production lodgement

See Production lodgement.

Production URLs and IP addresses

See Production URLs and IP addresses.

3D Secure Card Payments

Use QuickWeb to accept card payments verified using 3D Secure. 3D Secure is an additional layer of authentication that protects you from liability for fraudulent card payments. Unlike regular card payments, 3D Secure requires cardholders to complete an additional verification step with the card-issuer.

3D Secure is also known as Mastercard SecureCode and Verified by Visa.

See 3D Secure Card Payments for QuickWeb for more.

Transaction settlement

See Transaction processing and settlement.

Response codes

See Transaction Response Codes.