QuickConnect Technical Implementation Guide

QuickConnect

QuickConnect is a Westpac hosted service that enables your website to offer secure online payments.

The key features of the QuickConnect solution are:

  • Your system displays all the web pages (unlike QuickWeb which requires credit card details to be entered into a Westpac hosted web page).

  • The customer's browser sends the payment details directly to QuickConnect. This means sensitive credit card details never enter your system (unlike QuickGateway which requires credit card details to enter your system before being sent to Westpac).

To make a payment, the customer will visit your website and enter their credit card details into one of your web pages. When the page is submitted, the customer's browser will send the credit card details directly to QuickConnect. QuickConnect will make the payment using Westpac's payment processor, then redirect the customer's browser back to your website to display the receipt page.

Demo Payment Flow

This document describes the QuickConnect solution and explains how it can integrate with your existing website to make payments. 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 your systems with QuickConnect.

How does the payment process work?

The following diagram shows the sequence of events that take place when a customer makes a payment.

Payment process

The steps for the above diagram are as follows:

  1. The customer visits your website. One of your web pages will include a button to begin the payment process.
  2. When the customer clicks the button your system will prepare the 'Payment Details' page. To do this you must first retrieve a security token from QuickConnect. You will then include this security token in a hidden field within the 'Payment Details' page. Technical details for this process will be discussed in Parameters for the direct post.
  3. The customer enters their account information into the 'Payment Details' page.
  4. When the 'Make Payment' button is clicked the customer's browser will post the account details directly to QuickConnect. The account details will not enter your system. This process is discussed in Making a payment.
  5. QuickConnect makes the payment.
  6. QuickConnect redirects the customer's browser back to your website. This process is discussed in Making a payment.
  7. Your website displays the 'Receipt' page to the customer.

Implementation process

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

Step Description/Document Reference
Step 1 Kick-off meeting
Step 2 Displaying the 'Payment Details' page
Step 3 Making a payment
Step 4 Receiving payment details from QuickConnect
Step 5 Testing
Step 6 Sign off
Step 7 Production lodgement
Step 8 Go live
Step 9 Post implementation

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.

Displaying the payment details page

The 'Payment Details' page is a webpage generated by your system. The purpose of the page is to capture your customer's credit card details and submit them securely to QuickConnect.

Credit card payments The 'Payment Details' page for credit cards will include fields for:

  • Cardholder name
  • Credit card number
  • Expiry date
  • CVN

Example 'Payment Details' page

Bank account payments The 'Payment Details' page for bank accounts will include fields for:

  • Account name
  • BSB
  • Account number

Figure 3 Example 'Payment Details' page for bank account

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

Send parameters via secure token request

The secure token request is a message sent directly from your server to QuickConnect. It occurs immediately before you display the 'Payment Details' page (shown earlier in Figure 2 step 2). The purpose of the secure token request is to prevent parameters from being tampered with. Most parameters will be sent to QuickConnect using the secure token request. See Secure token request parameters.

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

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

Parameters for the direct post

The direct post is a message sent directly from the customer's browser to QuickConnect. It occurs after the customer clicks the 'Make Payment' button on the 'Payment Details' page (shown earlier in Figure 2 step 4). The purpose of the message is to send the customer's credit card details to QuickConnect without entering your system.

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

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

See Direct post parameters for the full list of parameters that need to be included on the 'Payment Details' page.

The following sequence diagram shows all the steps required to display the 'Payment Details' page (shown in Figure 2).

Figure 4 Sequence diagram for displaying the 'Payment Details' page

Figure 4 Sequence diagram for displaying the 'Payment Details' page

The steps for displaying the Payment Details page are as follows:

  1. Click 'Next'

    • On the 'Enter Details' page (see Figure 2) the customer clicks the 'Next' button.
  2. Send request

    • The customer's browser sends a request to your server to display the 'Payment Details' page.
  3. Retrieve data

    • Your server retrieves all the data that is required for the secure token request. It then builds a parameter list that will be sent to QuickConnect as part of the request. For more details see Secure token request parameters.
  4. Request security token

    • Your server makes an outbound HTTPS connection to the QuickConnect server. The parameter list from the previous step is included in the request.
  1. Generate security token & store parameters
    • QuickConnect generates a security token and stores your parameter list. A security token is a randomly generated, base 64 encoded string of characters.
    • For example: token=m378813qtvOtylVTvVvpWA7PT14QHltr-AqX2gZ-RFM
    • A unique security token is created for every request. The token is valid for 1 hour after it is created and can only be used once.
  1. Return security token
    • QuickConnect returns the security token to your server.
  1. Return html for 'Payment Details' page.
    • Your server produces HTML for the 'Payment Details' page and sends it to the customer's browser. The page includes:
    • Input fields for the customer to enter their account details
    • Hidden fields that are required for the direct post to QuickConnect

For more details see Direct post parameters.

Making a payment

This section explains the process for making a payment. It includes information about submitting payment details to QuickConnect as well as suggestions for presenting a results page to your customer.

There are two flows that may occur when a customer submits their payment details. They are:

  1. Typical payment flow
  2. Error flow
  3. Surcharge flow
  4. Duplicate payment flow

Your system must correctly handle both flows.

Typical payment flow

The typical payment flow consists of:

  1. The customer submitting their payment details to QuickConnect.
  2. QuickConnect performing high-level checks on the payment data, then making the payment attempt.
  3. QuickConnect returning the results to your system.
  4. Your system displaying the 'Receipt' page.

The diagram shown in Figure 5 provides a high-level overview of the typical payment flow.

The sequence diagram in Figure 6 shows the individual steps involved.

Figure 5 Making a payment via QuickConnect

Figure 5 Making a payment via QuickConnect with bank account

Figure 6 Sequence diagram for making a payment via QuickConnect

The steps for the above sequence diagram are:

  1. Click 'Make Payment'
    • The customer enters their credit card details into the 'Payment Details' page then clicks 'Save'.
  2. Direct post
    • The customer's browser submits the credit card details directly to QuickConnect.
  3. Verify security token, lookup parameters and make payment.
    • QuickConnect checks the security token to ensure it matches the token generated earlier in Figure 4. It then retrieves the other parameters, validates the data and makes the payment.
  4. Redirect
    • QuickConnect 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&...
    • See Redirect parameters for the full list of parameters.
    • QuickConnect then instructs the customer's browser to redirect to your returnUrl via HTTP get.
  5. Request next page
    • The customer's browser redirects to your server's returnUrl.
  6. Retrieve parameters
    • Your server retrieves the parameters from the request. It then uses this data to build the HTML for the 'Receipt' page.
  7. Return HTML for next page
    • Your server returns the HTML for the 'Receipt' page to the customer's browser.

Error flow

This section explains the sequence of events that take place when QuickConnect identifies a problem with the customer's payment details. There are a number of reasons why the error flow may occur:

  1. The customer has entered invalid credit card details. For example, the credit card number is too short or the expiry date is in the past. See Error descriptions for the list of errors that may be identified.
  2. The customer has entered invalid bank account details. For example, the BSB is not valid. See Error descriptions for the list of errors that may be identified.
  3. The payment includes a surcharge (calculated by QuickConnect) without the acceptSurcharge flag set. See Surcharge flow for information on payments with surcharges.
  4. The payment is suspected to be a duplicate payment. A 'duplicate payment' is a payment that has the same credit card number (for credit card payments) or BSB and account number (for bank account payments) and payment amount as another payment made in the past 24 hours. See Duplicate payment flow for information on handling potential duplicates.

If QuickConnect identifies a problem with the payment data, it will not attempt to make the payment. Instead, it will return an error summary to your system for you to display to the customer. During this process, QuickConnect will:

  • Redirect to your errorUrl
  • Include a parameter called 'action' with a value of 'Error'

When you receive error information from QuickConnect we recommend you redisplay the 'Payment Details' page, present an error message and ask the customer to re-enter their details. As part of this process, you will need to request a new security token.

The diagram in Figure 7 provides a high-level overview of the error flow.

The sequence diagram in Figure 8 shows the individual steps involved.

Figure 7 Error flow

Figure 7 Error flow

Figure 8 Sequence diagram for the error flow

The steps for the above sequence diagram are:

  1. Click 'Make Payment'

    • The customer enters their credit card details into the 'Payment Details' page then clicks 'Save'. For this particular example assume the customer has entered an invalid credit card number.
  2. Direct post

    • The customer's browser submits the credit card details directly to QuickConnect.
  3. Identify credit card or bank account problem QuickConnect identifies a problem with the credit card or bank account details. The payment is not attempted.

  4. Redirect

    • QuickConnect builds a list of parameters to include in the redirect. These parameters are specific to the error flow. They are included as a list of ampersand-delimited parameters.
    • For example: action=Error&communityCode=ACOMPANY&supplierBusinessCode=ACOMPANY&...
    • See Redirect parameters for the full list of parameters.
    • QuickConnect then instructs the customer's browser to redirect to the errorUrl you provided in the secure token request. Note, if you did not provide an errorUrl, QuickConnect will instead redirect to your returnUrl.
  1. Request next page

    • The customer's browser redirects to your server's errorUrl.
  2. Retrieve data

    • Your server retrieves the error parameters from the request.
  3. Request security token

    • Your server requests a new security token from QuickConnect. Your request will include a new parameter list. See Secure token request parameters for details.
  4. Generate security token & store parameters

    • QuickConnect generates a new security token and stores your parameter list.
  5. Return security token

    • QuickConnect returns the security token to your server.
  6. Return html for 'Payment Details' page

    Your server produces HTML for the 'Payment Details' page and sends it to the customer's browser. The page includes:

    • An error message to explain why the previous account details were rejected
    • Input fields for the customer to re-enter their account details
    • Hidden fields for the direct post to QuickConnect

Surcharge flow

This section explains the sequence of events that take place when QuickConnect is used to calculate and apply credit card surcharges. Please note that this flow is similar to the Duplicate payment flow and you may be required to handle surcharges as well as duplicate payments.

The typical surcharge flow consists of:

  1. The customer submitting their payment details to QuickConnect.
  2. QuickConnect performing high-level checks on the payment data, then calculating the surcharge amount
  3. QuickConnect returning the results to your system
  4. Your system displaying the calculated total, principal and surcharge amounts with an "Accept Surcharge" control.
  5. The customer submitting the confirmation to QuickConnect and QuickConnect attempting the payment.
  6. QuickConnect returning the results to your system.
  7. Your system displaying the 'Receipt' page.

The surcharge flow differs from the Typical payment flow in points 3-5 where an additional confirmation step is required.

In step 3, QuickConnect returns the details of the payment, including the total, principal and surcharge amounts back to your system. It also includes the following additional fields:

  • action = Error
  • errorField = acceptSurcharge
  • errorDescription = You must agree to accept the surcharge amount before continuing
  • actionContextId = A string of characters, for example, z4cbB4K1HKEm1Z_mDRzzg

QuickConnect expects a confirmation of the surcharge amount to be sent back before the payment is attempted. In step 4, you may display an "Accept Surcharge" control to post the required parameters to QuickConnect. The customer will submit the form and post the following parameters to QuickConnect:

  • actionContextId = The action context Id that was returned in the previous step.
  • communityCode = Your QuickStream community code
  • action = QuickConnectPayment
  • acceptSurcharge = true or false

To understand the process better, you can use the test poster to simulate this process. Your test poster is located at https://quickweb.support.qvalent.com/test/YOURCOMMUNITYCODE.

Accept surcharge test poster example

Duplicate payment flow

This section explains the sequence of events that take place when QuickConnect identifies a duplicate payment. Please note that this flow is similar to the Surcharge flow and you may be required to a handle duplicate payments as well as surcharges.

The typical duplicate payment flow consists of:

  1. The customer submitting their payment details to QuickConnect.
  2. QuickConnect performing high-level checks on the payment data, and determining it is a duplicate payment.
  3. QuickConnect returning the results to your system
  4. Your system displaying a Duplicate Payment notice.
  5. The customer submitting the confirmation to QuickConnect and QuickConnect attempting the payment.
  6. QuickConnect returning the results to your system.
  7. Your system displaying the 'Receipt' page.

The duplicate payment flow differs from the Typical payment flow in points 3-5 where an additional confirmation step is required.

In step 3, QuickConnect returns the details of the payment back to your system. It also includes the following additional fields:

  • action = Error
  • errorField = ignoreDuplicate
  • errorDescription = You must agree to process the duplicate payment before continuing
  • actionContextId = A string of characters, for example, Qb3is8yHS8ehkS9hjks_sh22Sc

QuickConnect expects a confirmation of the duplicate payment to be sent back before the payment is attempted. In step 4, you may display an "Ignore Duplicate Payment" control to post the required parameters to QuickConnect. The customer will submit the form and post the following parameters to QuickConnect:

  • actionContextId = The action context Id that was returned in the previous step.
  • communityCode = Your QuickStream community code
  • action = QuickConnectPayment
  • ignoreDuplicate = true or false

To understand the process better, you can use the test poster to simulate this process. Your test poster is located at https://quickweb.support.qvalent.com/test/YOURCOMMUNITYCODE.

Ignore duplicate test poster example

Receiving payment details

There are 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.

This is done via a HTTPS POST to your server. The payment details are posted 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 server 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 QuickStream 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.

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 content type the payment details are posted in. 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:

Parameter Name Description
sourceCode The payment channel used to make the transaction. The values are net, adhoc and phone.
receiptNumber The unique receipt number generated by QuickWeb. This value can be used later to locate this payment in QuickStream Portal.
communityCode Your community code. Provided in communityCode during the handoff. See View your connection details in QuickStream Portal.
supplierBusinessCode Your supplier business code. Provided in supplierBusinessCode during handoff. See View your connection details in QuickStream Portal.
paymentReference Provided in paymentReference during the handoff or entered by the payer.
customerReferenceNumber A customer-level reference. Provided in supplierBusinessCode during the handoff or entered by the payer.
paymentAmount The payment amount including surcharges.
surchargeAmount The surcharge amount.
cardScheme The card scheme. One of:
  • VISA
  • MASTERCARD
  • AMEX
  • DINERS
  • UNIONPAY
  • JCB
settlementDate The settlement date of the payment. See Transaction settlement.
createdDateTime The date and time of the transaction on the QuickWeb server in Sydney. Format: dd MMM yyyy HH:mm:ss.
responseCode The two digit response code. See Response Codes.
responseDescription The description of the response code. See Response Codes.
summaryCode The one digit summary code. See Response Codes.
successFlag true when the transaction was successful, otherwise false.
Custom fields Any custom parameters that you included in the handoff will be sent back to you.

That is, any parameters prefixed with custom will be included in this notification.

For example:
customTitle,
customPayeeName

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>

Cash Applied File

See Cash applied file.

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

Download cash applied files from QuickStream Portal.

Manage your security settings

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

Manage your IP whitelist

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

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

QuickStream Portal allows you to manage your allowed IP addresses.

Manage your domain whitelist

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

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

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

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

QuickStream Portal allows you to manage your allowed domains.

View your connection details

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

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

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

Manage server to server notifications

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

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

Manage server to server notifications in QuickStream Portal.

Destination URL

This option can be used for:

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

Notification format

Choose HTTPS POST or XML.

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

Automatic retry of failed notifications

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

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

For example the following setting produces a schedule:

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

This setup will send the following server to server notifications:

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

Troubleshooting security settings

QuickStream Portal's Activity Log shows:

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

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

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

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

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

Testing

See Testing.

Test account numbers

See Test card and bank account numbers.

Test URLs and IP addresses

See Test URLs and IP addresses.

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.

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.

Secure token request parameters

The following table lists the parameters that can be passed from your server to QuickConnect during the secure token request. This task is shown in Figure 4 step 4.

The parameters must be passed to CommunityTokenRequestServlet. See the full URL for the test environment. See the full URL for the production environment.

Mandatory parameters

Parameter Name Description
username Your username. This value will be provided to you.
password Your password. This value will be provided to you.
supplierBusinessCode Your QuickStream supplier business code. This will be provided to you.
principalAmount The amount the customer is going to pay less surcharges. This value excludes any GST or surcharge amount.

The amount is in dollars and cents. For example: 1015.00 (for one thousand and fifteen dollars)
returnUrl Note: We recommend you use a HTTPS URL for this parameter.
The URL you would like QuickConnect to redirect to after the payment is complete. This is typically your receipt page.

Any parameters included in the URL will be provided back to you.

Example: https://www.yoursite.com.au/receipt?Name=John&Age=21
connectionType QUICKCONNECT
product QUICKWEB

Optional parameters

Parameter Name Description
customerReferenceNumber A value that uniquely identifies your customer. For example, a customer reference number, member ID, family code or BPAY number. This value will be provided back to you later. It can then be used to help you reconcile the payment in your backend system.
paymentReference A value that uniquely identifies the payment. For example, an invoice number, fine code or transaction reference.

This value will be provided back to you later. It can then be used to help you reconcile the payment in your backend system.
currencyCode The currency code. This will determine which currency to use when making the payment.

Specify either AUD or NZD.

If this parameter is not provided, QuickConnect will default to AUD.
serverReturnUrl Note: You must use a HTTPS URL for this parameter.
The URL you would like QuickConnect to send the payment notification to (ie, the server-to-server post back).
Example: https://www.yoursite.com.au/processPayment
errorEmailToAddress The email address you would like QuickConnect to send an email to if we cannot deliver the payment notification to your server (eg, your web site is down).

Example: payments@yoursite.com.au

This parameter is only relevant if you wish to receive the payment notification. See Server to server notification for details.
errorUrl Note: We recommend you use a HTTPS URL for this parameter.
The URL that QuickConnect will redirect to if an error occurs. For example, if invalid credit card details are provided or the payment has been found to be a duplicate.

If an errorUrl is not included, QuickConnect will redirect to the returnUrl instead.
registerPaymentAccount This parameter is only applicable to your facility when QuickVault is enabled. One of:
  • true
  • false
This will register the account in QuickVault after a successful payment.

Custom parameters

If you would like to provide additional information to QuickConnect you can do this by using a custom parameter. Multiple custom parameters can be passed to QuickConnect.

Parameter Name Description
custom<Custom name>

Example:
customTitle,
customPayeeName
QuickConnect can pass this data back to you.

The parameter name must start with the word 'custom' and be followed by a word beginning with a capital letter. Maximum 100 characters per parameter.

Sample code for the secure token request

Java

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

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

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

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

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

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

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

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

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

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

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

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

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

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

C#

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

PHP

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

Python 3.x


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

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

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

class TokenRequest:

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

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

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

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

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

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

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

print(token)

Direct post parameters

The following table lists the parameters that can be included in the direct post from the 'Payment Details' page to QuickConnect. The HTML for the page is produced in Figure 4 step 7. Parameters are included as either input fields or hidden fields.

The direct post to QuickConnect is shown in Figure 6 step 2. Parameters are posted directly to OnlinePaymentServlet3. The full URL for the test environment is shown in Test URLs and IP addresses. The full URL for the production environment is shown in Production URLs and IP addresses.

Mandatory parameters

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

Parameter Name Description
communityCode Your QuickStream community code. This value will be provided to you.
token The security token is given to you by QuickConnect in Figure 4 step 6.

QuickConnect will use this token to lookup the parameters that were stored during the secure token request (see Figure 4 step 5).

Additional mandatory parameters

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

Parameter Name Description
cardholderName The cardholder name as it appears on the customer's credit card. When accountType is CREDIT_CARD only.
creditCardNumber The credit card number. When accountType is CREDIT_CARD only.
expiryDateMonth The month the credit card expires.

Format: MM

For example: 01 (for January). When accountType is CREDIT_CARD only.
expiryDateYear The year the credit card expires.

Format: YY

For example: 18 (for the year 2018). When accountType is CREDIT_CARD only.
cvn The card verification number (CVN). This is also known as the card verification value (CVV). When accountType is CREDIT_CARD only.
accountName The account name associated with the customer's bank account. When accountType is DIRECT_DEBIT_NZ or DIRECT_DEBIT only.
accountNumber The credit card number associated with the customer's bank account. When accountType is DIRECT_DEBIT_NZ or DIRECT_DEBIT only.
bsb The BSB associated with the customer's bank account. When accountType is DIRECT_DEBIT only.
bankCode The bank code associated with the customer's bank account. When accountType is DIRECT_DEBIT_NZ only.
branchCode The branch code associated with the customer's bank account. When accountType is DIRECT_DEBIT_NZ only.
accountSuffix The account suffix associated with the customer's bank account. When accountType is DIRECT_DEBIT_NZ only.
accountType The type of payment the customer is going to make.

Specify either: DIRECT_DEBIT (to restrict to Australian bank account payments), DIRECT_DEBIT_NZ (to restrict to New Zealand bank account payments) or CREDIT_CARD (to restrict to credit card payments). Do not send this parameter if your payer can choose either in your solution.
ignoreDuplicate If this parameter is set to 'true' QuickConnect will not perform a 'duplicate payment check'.

A duplicate payment is an identical payment that has already been made that day. If a duplicate payment is found, QuickConnect usually rejects the current payment request.

Please note that an error will occur and the payment will not proceed if ignoreDuplicate is not set to 'true'.
acceptSurcharge If this parameter is set to 'true' QuickConnect will process the payment. You must accept the surcharge to continue with the payment.

Please note that an error will occur and the payment will not proceed if acceptSurcharge is not set to 'true'.
actionContextId This parameter is required for the Surcharge flow and the Duplicate payment flow. You must provide the value of actionContextId that was returned to you by QuickConnect to accept surcharge or ignore a duplicate payment.

Custom parameters

If you would like to provide additional information to QuickConnect you can do this by using a custom parameter. Multiple custom parameters can be passed to QuickConnect.

Parameter Name Description
custom<Custom name>

Example:
customTitle,
customPayeeName
QuickConnect can display this data on the screen and/or pass it back to you in the payment notification.

The parameter name must start with 'custom' followed by an uppercase letter.

Redirect parameters

This section lists the parameters QuickConnect may return in the redirect. There are two flows that can occur. QuickConnect will return either:

  1. Parameters for the typical payment flow
  2. Parameters for the error flow

Parameters for the typical payment flow

The following table shows the parameters that QuickConnect will return in the typical payment flow. Your system can then display this information on your 'Receipt' page (see Figure 6 step 7). Do not store this data in your system - it is for display purposes only.

The summaryCode parameter will indicate whether or not the payment was successful. For failed payments you may wish to provide a 'Try again' button to take the customer back to the 'Payment Details' page.

For more information, see Typical payment flow.

Mandatory parameters

Parameter Name Description
communityCode Your QuickStream community code. You will be notified of your community code during the implementation.
supplierBusinessCode Your QuickStream supplier business code. This value will be provided to you during the implementation.
paymentAmount The total payment amount that QuickStream used when it attempted the transaction. It included the principalAmount plus any surcharge amount that needed to be paid via surchargeAmount.

The amount is in dollars and cents.

For example: 1001.15(for one thousand and one dollars and fifteen cents).
surchargeAmount The surcharge amount applied to the transaction. This value is included in the paymentAmount field. The amount is in dollars and cents.

For example: 1.15 (for one dollar and fifteen cents).
receiptNumber The unique receipt number generated by QuickStream. The value can be used later to locate this payment in QuickStream Portal.
responseCode The two digit response code.

For example: 41.
See Response Codes for a list of response codes that may be returned.
responseDescription The description of the response code.

For example: Lost card.
See Response Codes for details.
summaryCode The one digit summary code.

For example: 1.
See Response Codes for the list of summary codes.
createdDateTime The date and time of the transaction on the QuickStream server in Sydney.

Format: DD MMM YYYY hh:mm

For example: 20 Jun 2012 15:04
settlementDate The settlement date of the payment. Transactions after 6pm Sydney time will settle on the following banking day.

Format: YYYYMMDD

For example: 20120620 (for 20th June 2012)
cardholderName The card holder name entered by the customer.

For example: John Smith
maskedCardNumber The credit card number the customer entered. For security reasons part of this number will be masked.

For example: 456471xxxxxxx004
expiryDateMonth The month that the customer entered into the expiry date field.

Format: MM

For example: 01 (for January)
expiryDateYear The year that the customer entered into the expiry date field.

Format: YYYY

For example: 2016
cardScheme The type of credit card the customer used to make the payment. QuickStream will return one of the following values:
  • VISA
  • MASTERCARD
  • AMEX
  • DINERS
  • JCB
  • UNIONPAY
accountName The account name that the customer entered on the 'Payment Details' page.

For example: John Smith
accountNumber The account number that the customer entered on the 'Payment Details' page. For security reasons part of this number will be masked.

For example: xxxxxx789
bsb The BSB that the customer entered on the 'Payment Details' page. For security reasons part of this number will be masked.

For example: xxx-000
hmac A HMAC_SHA256 signed string of the parameters in the passback. Use this to validate that the parameters in the passback were not tampered. See Validating the HMAC.

Optional parameters

Parameter Name Description
customerReferenceNumber This will be included if you provided the customerReferenceNumber parameter in the secure token request.
paymentReference This will be included if you provided the paymentReference parameter in the secure token request.

Custom parameters

Parameter Name Description
custom<Custom name>

Example:
customTitle,
customPayeeName
Any custom parameters you include in the secure token request will be provided back to you. That is, any parameters prefixed with 'custom' will be included in the redirect.

Parameters for the error flow

The following table lists the parameters that QuickConnect will return during the error flow. Your system can then display the error information on your 'Payment Details' page (see Figure 8 step 10).

For more information see Error flow.

Mandatory parameters

Parameter Name Description
action 'Error'
communityCode This is the same value that you passed to QuickConnect in the secure token request.
supplierBusinessCode This is the same value that you passed to QuickConnect in the secure token request.
paymentAmount This is the total amount that will be charged to your customers credit card. It is the principalAmount passed in the secure token request plus (when applicable) the surchargeAmount calculated by QuickStream.
errorDescription A description of the error. See Error descriptions for the list of errors that may be provided by QuickStream.
For example: Card type not accepted
errorField The name of the parameter that generated the error.
For example: creditCardNumber.
This parameter can be provided more than once. See Error descriptions for the list of errors that may be provided by QuickStream.

Optional parameters

Parameter Name Description
surchargeAmount This is the surcharge amount calculated by QuickStream based on the surcharge percentage configured for a particular card scheme. This field is only applicable when QuickStream has calculated a surcharge, otherwise it will be omitted.
customerReferenceNumber This will be included if you provided the customerReferenceNumber parameter in the secure token request. See Secure token request parameter for details.
paymentReference This will be included if you provided the paymentReference parameter in the secure token request. See Secure token request parameter for details.
actionContextId This parameter is required for the Surcharge flow and the Duplicate payment flow. You must provide this value to accept surcharge or ignore a duplicate payment.

Error descriptions

This table lists the values that QuickConnect may return for the errorField and errorDescription parameters. These are returned as part of the error flow (see Figure 8 step 4).

Error Field Error Description
acceptSurcharge 'You must agree to accept the surcharge amount before continuing.5'
ignoreDuplicate 'You must agree to process the duplicate payment before continuing.'
cardholderName 'The value contains illegal characters. Please use only English letters and symbols.'
creditCardNumber 'A value is required for this field.'
creditCardNumber 'The value you have entered is too short. Please enter at least 13 characters.'
creditCardNumber 'The value you have entered is too long. Please enter at most 16 characters.'
creditCardNumber 'Invalid card number.'
creditCardNumber 'Card type not accepted.'
expiryDateMonth 'A value is required for this field.'
expiryDateMonth 'The value you have entered is too short. Please enter at least 4 characters.'
expiryDateMonth 'The value you have entered is too long. Please enter at most 4 characters.'
expiryDateYear 'A value is required for this field.'
expiryDateYear 'The value you have entered is too short. Please enter at least 4 characters.'
expiryDateYear 'The value you have entered is too long. Please enter at most 4 characters.'
expiryDateYear 'Expiry date must be in the future.'
cvn 'A value is required for this field.'
cvn 'The value you have entered is too short. Please enter at least 3 characters.'
cvn 'The value you have entered is too long. Please enter at most 4 characters.'
cvn 'Invalid number.'
cvn 'Invalid value for card type.'
bsb 'A value is required for this field'
bsb 'Invalid BSB'
bsb 'BSB is not valid for direct debit'
bsb 'Not a valid settlement account BSB'
accountNumber 'A value is required for this field'
accountNumber 'Invalid Account Number'
accountName 'A value is required for this field'
accountName 'The value you have entered is too long. Please enter at most 200 characters.'
accountName 'The value contains illegal characters. Please use only English letters and symbols.'
acceptDDR 'You must accept the Direct Debit Request before continuing'

Validating the HMAC

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

The parameters in the redirect 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.

Parameter Name Parameter Value
communityCode COMCODE
supplierBusinessCode SUPP
principalAmount 10.00
customParam this is a custom param with special characters &
hmac dce3bc3945ca4d33151fb4c6a69971d86c35556cc2becafb3cb451f080af3d49

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

Parameter Name Parameter Value
communityCode COMCODE
customParam this is a custom param with special characters &
principalAmount 10.00
supplierBusinessCode SUPP

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.)

Parameter Name Parameter Value
communityCode COMCODE
customParam this+is+a+custom+param+with+special+characters+%26
principalAmount 10.00
supplierBusinessCode SUPP

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.

Soft descriptors for Aggregators

Soft-descriptors are informational fields that Aggregators must collect for each transaction. Other merchants cannot use these fields. These merchant descriptor fields allow some control over the cardholder narrative for each transaction. The Secure Token Request includes new fields to provide these soft-descriptors.

Read more about Soft descriptors for Aggregators.

Secure token request fields

These fields are sent in a Secure Token Request.

Parameter Name Length Required Description (for a Payment)
merchantName 22 Yes This field is only relevant for credit card payments for Aggregators.
Must be in the format AggregatorName*SubMerchantName.
For example:
  • AggregatorName is Jane's Transactions, abbreviated to JAT.
  • SubMerchantName name is Jill's Bikes.
  • The value of this field may be JAT*JillsBikes.
AggregatorName can be either in full or abbreviated and must be 3 characters.
Westpac may suggest a three character aggregator name during your implementation.
merchantStreetAddress 48 Yes This field is only relevant for credit card payments for Aggregators.
The street address of the sub-merchant's trading address.
It is a scheme requirement to populate the street address as part of the payment. Westpac does not hold the street address information for sub-merchants and it will not appear on the cardholder's or merchant's statement.
Must contain the street address lines only:
  • Include the city or suburb in Merchant Location.
  • Include the state in Merchant State.
  • Include the country in Merchant Country.
  • Include the post code in Merchant Post Code.
merchantLocation 13 Yes This field is only relevant for credit card payments for Aggregators.
The city or suburb of the sub-merchant's trading address.
merchantState 3 Yes This field is only relevant for credit card payments for Aggregators.
The state of the sub-merchant's trading address. One of:
  • NSW
  • ACT
  • VIC
  • QLD
  • NT
  • SA
  • WA
  • TAS
Merchant Country 2 Yes This field is only relevant for credit card payments for Aggregators.
Must be set to AU.
The sub-merchant must be registered in Australia and have a presence and process payments within Australia.
merchantPostCode 4 Yes This field is only relevant for credit card payments for Aggregators.
The postal code of the sub-merchant's trading address.
subMerchantId 15 Yes This field is only relevant for credit card payments for Aggregators.
A unique identifier for your sub-merchant. The aggregator allocates the sub-merchant identifier. Westpac does not allocate this value.

Passback and payment notification

No additional fields are provided in the passback to your website or payment notification to your server.

3D Secure Card Payments

Use QuickConnect 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 QuickConnect for more.

Payment procedure

See Transaction processing and settlement.

Transaction settlement

See Transaction processing and settlement.

Response codes

See Transaction Response Codes.