QuickVoice Implementation Guide

QuickVoice

QuickVoice is a Westpac service that enables phone payments for your business.

The key features of the solution are:

  • QuickVoice accepts credit card payments via phone.
  • QuickVoice validates payment details by inspecting outstanding invoices or using adhoc check-digit routines.
    • QuickVoice deducts paid amounts from outstanding invoices.
    • QuickVoice validates ad-hoc payments using your check-digit routine.
    • Upload your invoices to QuickVoice for reference during the payment process.
  • Westpac's professional voice artist records your customised phone prompts each month.
  • QuickVoice integrates with QuickStream's suite of receivables products.

How does the payment process work?

The payment process involves the following steps:

  1. Provide the customer with an invoice or bill to pay. This will include details of your phone payment service.
  2. The customer dials your 1300 number to access your phone payment service.
  3. The customer enters their customer reference and/or invoice number.
  4. The customer enters their credit card details, reviews, and confirms the payment.
  5. If the customer needs help with the system, we can provide pre-recorded help dialogue. QuickVoice can also forward to your 1800 help desk number.
  6. If you have uploaded an invoice file, QuickVoice will deduct the paid amount. You choose if full payment is required, or partial payments are allowed.
  7. QuickVoice takes the the payment.
  8. QuickVoice can send a payment notification to your web server.
  9. At the end of the day, QuickVoice provides all payments made to you as a CSV, or in your desired report format.

Implementation process

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

Steps Description/Documentation Reference
Step 1 Kick-off Meeting
Step 3 Branding QuickVoice
Step 4 Receiving payment details
Step 5 Testing
Step 6 Sign off
Step 7 Production lodgement
Step 8 Go live
Step 10 Post implementation

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

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

Kick-off meeting

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

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

Branding QuickVoice

During your QuickVoice implementation you will be asked to customise the prompts that your customer will hear.

QuickVoice base prompts

Once you have determined your phone prompts, change the QuickVoice Base Prompts document.

Download the QuickVoice Base Prompts.

You can then send it to us:

  • Highlight any modified prompts in red.
  • It is important to detail special word and acronym pronunciations.
  • Westpac submits the prompts for recording on the 20th day of each month. If the 20th day is a weekend or public holiday, Westpac submits the prompts on the next business day.
  • Sometimes it is necessary to expedite the recording process. In some cases, Westpac can arrange an unscheduled session to record your prompts.
  • Approximately one fortnight after submission the prompts will be available for review. Westpac provides you with a phone number to use on our test payment server.
  • Once tested and approved, the prompts are then submitted for activation on the live payment server.

QuickVoice prompt flowchart

The following flowchart depicts the basic voice prompts played during a typical card payment. The entities and arrows highlighted in green follow a successful transaction scenario. This flowchart is not comprehensive. It is intended to depict the typical prompt flow for QuickVoice.

Download the Flowchart.

QuickVoice Prompt Flowchart

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 configure your server 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 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 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
  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.

QuickStream Portal allows you to manage your allowed domains.

View your connection details

Connection details are required to interact with QuickStream in each environment.

  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.

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 server to server notification attempts are:

  • 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: QuickVoice sign off

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

Our QuickVoice 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

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.

Transaction settlement

See Transaction processing and settlement.

Response codes

See Transaction Response Codes.

Requirements checklist

Download the Checklist.

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

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