QuickGateway

The QuickGateway solution allows customers to process cards using an Application Programming Interface (API). This API is network based and does not necessarily require any software installed on the customer's site. All communications between the customer's system and API will take place in a secure manner.

The API will offer the customer a range of card processing features including:

• Capture - debit funds from a nominated card
• Refund - credit funds to a nominated card
• Pre-authorisations - reserve funds from a nominated card and capture later
• Query - query the result of a previously attempted transaction
• Echo - check the status of the API service

The API supports multiple connectivity options (Internet, Leased Line) and technologies (HTTPS POST, Java, SOAP, ASP, .NET) so there is a solution to suit any customer. All major card types such as Visa, Mastercard, Amex, JCB, Diners and Union Pay may be processed through QuickGateway.

This document describes the solution offered to meet the business needs of customers requiring on-line card processing through a software API in Australia and New Zealand. This is provided as part of the QuickStream product suite and is called QuickGateway.

The actual concept of the API is simple. The Customer System will send an API Request to QuickGateway, containing the transaction details and will receive back an API Response containing details on whether the transaction was successful or not.

Getting started

To integrate QuickGateway:

1. Read Implementing the QuickGateway API. This section provides a step-by-step guide to implementing the QuickGateway API.
2. Become familiar with the Application Programming Interface. This section is where most of the technical specification of the QuickGateway API is included along with tips on how to develop your client software. There are also details on our web-based screens for administration and reconciliation processes.
3. Find an Integration Guide for your application technology.
4. Read Transaction Settlement and Response Codes. This contains information about card transaction settlement and a full list of possible response codes.
5. Whitelist the IP address that QuickGateway will see your requests from.
6. Download your Client Certificate and Client Software and set a business email address that QuickStream will send notifications to when your certificate is about to expire.
7. View the available values for customer.merchantId in Connection Details.
8. Write your application to handle errors. See Troubleshooting and Dealing with QI Responses.

We have tried to include as much detail as possible for customers wishing to implement the Westpac QuickGateway API solution so you have all the information you need at your fingertips. Due to its contents, it can be quite daunting at first read, however not all sections are relevant to all customers.

We recommend that the document is examined by your IT staff with at first a quick skim through and then start working through the steps documented in Implementing the QuickGateway API in order to implement the solution. If you have any questions that cannot be answered from the document, please direct these to your Westpac implementation contacts.

Is it secure?

For a solution of this nature, security is critical. Westpac must be absolutely confident that they are receiving a card processing request from an authorised source. To ensure the source of the request is valid, the following measures will be adopted:

• The Customer must be registered before card processing will begin. Part of this registration will be to issue the customer with a username and password. This username/password combination must be passed in with every request.
• Qvalent will only accept requests from certain pre-configured IP addresses.
• For high volume customers Qvalent will recommend that a leased line (i.e. Frame Relay) be installed between the customer's site and Qvalent's data centre.
• For added security a card verification number (CVN) can be supplied with the QuickGateway API call.
• All transaction data will be communicated via HTTPS with 128-bit encryption. The connectivity options are as follows:
• Leased line. Dedicated link between the customer's site and Westpac's card server. In this scenario, no data would be transmitted over the Internet. Username / password are still mandatory. SSL certificates are not mandatory but recommended in case of failure of leased line requiring a failover to the Internet.
• Internet. SSL client certificate exchange with username / password over HTTPS. With client certificates, Westpac can be assured of the source of the request. We will supply Test and Production 128-bit SSL client certificates for your use.

Where a customer system interfaces with the QuickGateway API, the customer system will establish a trust relationship with the QuickGateway Server. The QuickGateway Server holds an SSL certificate issued by Verisign to Qvalent. This is different to the SSL client certificate issued by Qvalent and supplied to you. The latter is provided to be installed on your system, whereas the former should not. Customers must trust the root level certificate (ie that issued by Verisign) and not the certificate issued to Qvalent. The certificates issued to Qvalent expire and are replaced each year, whereas the Verisign root certificates have a much longer life (ie expiry in 2028). Any customers that trust the certificate issued to Qvalent directly will cease to operate as replacement certificates are installed and therefore this must be avoided.

All attempts to use the card service are logged. This includes Internet connections, API calls and the success or failure of those calls. Logs will be written to permanent storage. Logging will include the IP address of the caller and all the information sent and received to that destination.

Credit card details are protected as follows:

• Credit card numbers and expiry dates are stored in encrypted form in the database. Credit card numbers are recorded in truncated form in system logs (ie first few and last few digits only)
• Card verification number (CVN) is not stored in the database nor in system logs. The value is passed on as is to the banking network and only a record of whether a value was provided or not is retained.

QuickGateway requires API requests made using the encryption standard known as TLS 1.2. QuickGateway rejects API requests made using TLS 1, or TLS 1.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 with this service. TLSv1 is not strong encryption, please use TLSv1.2 instead.

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

Refunds are restricted to only be allowed against previous captures so there is no risk of fraudulent activity within your business.

Implementing the QuickGateway API

This section describes the process of implementing QuickGateway.

API client integration

Client software packages are available to download through QuickStream Portal. See Integration Guides.

Testing

For any customer wishing to implement the QuickGateway API, we provide a test environment that is accessible via the internet. This environment is able to simulate a live gateway but may be used without any risk of transactions actually being processed through the banking system.

The typical steps that might be involved in testing are as follows:

1. You will be provided with this document to provide background information about the API.
2. One of our staff will be nominated to help you through the testing and we will put them in contact with you. They will create a test merchant for use in our test environment and provide the username, password and merchant ID to use. In order to set this up correctly, we will need to know some details, such as what your accepted card types are and the IP address of your test server(s). We will ask these questions as part of the setup process.
3. You must use an SSL certificate to connect to QuickGateway. This allows our server to verify that the transaction requests are coming from an authorised source. We will provide a test SSL certificate for your use during testing. We will provide a production SSL certificate once testing is complete.
4. The URL you will use to connect depends on the programming environment you intend to use: a. If you are using an HTTPS Post to connect to the API, the URL is https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver. b. If you are using SOAP to connect to the API, the URL is https://ccap.client.support.qvalent.com/webservice/CardsAPIDocumentLiteral.
5. You should then attempt to connect to our API using your chosen mechanism. You may receive a "QU" for Unknown Customer IP Address response if you have not provided us with your current IP address. You may try further transactions (again, if using Java the CreditCardAPITester application may be used for this) and should now receive other responses.
6. You should now develop your client application using your chosen programming environment to access the API. As stated earlier, it is important to move as soon as possible to SSL certificate testing if you are intending to conduct API calls over the internet.

You may request a web user/password to QuickStream Portal.

Testing exception handling

You may use our test environment, to perform unit and acceptance testing of your application. The most critical element of your testing should be to test your application's exception handling as documented in in Testing Exception Handling.

The test environment assists you in performing these testing by providing a way of simulating transaction responses, as per the list in Test account numbers and Response codes.

Please note: the response codes operate differently for the New Zealand gateway. More details will be provided during the implementation for customers wishing to accept transactions in NZ Dollars.

Other key tests

It is also critical that you ensure that your front-end application prevents duplicate payments. See Preventing Duplicate Payments for recommendations on how this may be performed.

Test environment availability

We will endeavour to ensure that the test environment is available as often as possible, during business hours and after hours. However, the environment is unavailable from time-to-time for upgrade purposes. If you believe that the test environment may be unavailable, you may contact your support contacts to see when the service will be restored.

Also, if you are planning significant test periods or load testing, please contact your support contacts to ensure that the test environment will be available during these periods.

Production migration

The migration to Production will be planned in conjunction with you to ensure that it is as seamless as possible.

Migration

Before commencing the migration to Production, the following must occur:

• Connectivity to be setup, either over the internet or leased line. If using the internet, we will provide your Production SSL Certificate to you via a secure means.
• Your production Merchant IDs are to be provided ie. Visa/Mastercard/UnionPay (to be arranged by Westpac Implementation Manager) plus Amex and Diners if accepted.
• You should indicate if you expect any transaction limits to be applied or if refunds will be possible with/without reference to a capture.
• You should provide administration user details if required in Production ie Username, email address, access required (card payments, refunds and/or searches)

Typically production migration involves:

1. We will configure your merchant details in Production and setup your Production merchant account.
2. We will provide the Production URL, username, password and merchant as well as web user/passwords for online facilities. The Production URL is the same as what is used in testing with ".support" removed. For example, https://ccapi.client.qvalent.com/... instead of https://ccapi.client.support.qvalent.com/...
3. In order to ensure that the banking side is correctly configured prior to live testing, we will initiate a low-value capture transaction (ie less than $2.00) through each merchant facility to confirm that the transaction is accepted. The following day, the Westpac Implementation Manager will confirm that the transactions have appeared correctly on the bank statements. Following confirmation, we will reverse the transactions through a refund transaction and confirm that this has been registered on the bank statement.
4. Following successful connectivity testing, we will reconfigure your account to be completely live. It is recommended that you perform a production test for each accepted card scheme (eg Visa/Mastercard, Amex and Diners) to confirm that the setup is complete before commencing full live usage. This would include reconciling the transactions on your bank statement as correct.

QuickGateway production TLS certificate security

The QuickGateway production TLS certificate that you downloaded from QuickStream must be kept secure. This certificate identifies you to Westpac. Without this certificate you will not be able to transact. Do not share this certificate with any other parties. If this certificate is lost, stolen or compromised in any manner contact the QuickStream help desk immediately. The QuickStream Technical Support team will revoke your current certificate and allow you to download a new one.

Support

During the testing phase, all support will be provided by the person nominated to assist during this phase. However, after migrating to Production, support will be provided via a more formal process. Prior to contacting support, we recommend that some basic troubleshooting is performed:

• Check the most recent 10 transactions or query QuickStream Portal to determine if the issue is an isolated, transient issue or a more serious outage.
• Check if there are any scheduled or unscheduled outages noted on the Qvalent website. You may subscribe to receive notifications of scheduled maintenance changes. If the troubleshooting does not resolve a production issue, contact support.
• For urgent issues where you are unable to process transactions through the API for a sustained period, contact QuickStream Technical Support. They will ensure you are able to get in contact with the appropriate person to resolve the issue as soon as possible.
• For less urgent issues, including reconciliation issues, that may be handled during normal business hours, contact QuickStream Technical Support.

API

The QuickGateway API provides a real-time, synchronous interface to execute card transactions. That is, only one method call is needed to request processing against a card. This method will complete in a synchronous manner. This removes the complexities of issuing a request then having to process a separate response message sometime in the future. In this model, a customer will issue the card request, then receive the results of the request back in the same call, all in real-time.

The following figure illustrates the steps in a Request-Response interaction between a customer and the API:

This transaction contains the following steps:

1. Customer initiates a HTTPS connection to the provided API URL.
2. The Customer uses a POST operation to send the API request through the HTTPS connection.
3. The Customer waits for a response to return through the HTTPS connection.
4. The API server verifies the digital 'signature', merchant username / password and IP address of the originating request. If all these are valid, the server verifies the other card request parameters.
5. The API server contacts the issuing bank and requests authorisation for the card transaction.
6. The API server returns the Response to the Customer through the HTTPS connection established in step 1.
7. The Customer reads the Response and returns it to the process that initiated the API request.
8. The Customer closes the HTTPS connection established in step 1.

This process is then repeated for further Request/Response cycles to process additional cards.

Connecting to the API

Qvalent provides software packages for some technologies to assist you in the task of connecting to the API. This software provides an object in the relevant programming language which performs all the communication with the Westpac API server. Software packages are available for the following technologies:

• Java
• Microsoft Component Object Model (COM) and Active Server Pages (ASP)
• Microsoft .NET
• PHP

These software packages include additional documentation on how to install and use the API software in your application.

If your application does not use one of the supported technologies, you can develop your own connectivity using either SOAP or HTTPS POSTs. You can also choose this option if you do not wish to install extra software on your servers. More details about how to do this are provided in the document entitled "Custom Integration" which can be provided on request.

Regardless of the method you use to connect to the API, the parameters you send and receive are the same. These parameters are described in the following section.

API request model

To make a request to process a card, the body of the message would include the following fields:

Only use standard ASCII characters in your parameter values. Do not use any of the following special characters in your parameter values:

• Ampersand & - ASCII character number 38
• Plus sign + - ASCII character number 43
• Percentage sign % - ASCII character number 37

API response model

In addition to the standard HTTPS response code (i.e. 200, 404), after processing the following will be sent back to the Customer:

HTTPS POST example

Request example

A HTTPS transmission of the API may include the following MIME and HTTPS headers:

    POST /post/CreditCardAPIReceiver HTTP/1.1
    Content-type: application/x-www-form-urlencoded
    Content-length: 328
    Host: ccapi.client.support.qvalent.com:443

    order.type=refund&customer.username=COMPANYA&customer.password=insurance&customer.merchant=companya&card.PAN=4242424242424242&card.CVN=564&card.expiryYear=10&card.expiryMonth=06&order.amount=3400&customer.orderNumber=AB1322-refund&card.currency=AUD&order.ECI=IVR&customer.originalOrderNumber=AB1322&order.priority=1&message.end=

Response example

    response.summaryCode=0
    response.responseCode=00
    response.text=Transaction processed successfully
    response.RRN=13238
    response.settlementDate=20050103
    response.previousTxn=0
    response.referenceNo=12922
    response.orderNumber=1234567
    response.cardSchemeName=VISA
    response.creditGroup=VI/BC/MC
    response.transactionDate=03-JAN-2005 13:24:41
    response.end

Order types

This section describes how to perform transactions of the various order types.

Capture orders

A capture represents a purchase transaction by a card-holder. To perform a simple capture, provide the following parameters:

• order.type= capture
• card.PAN, card.expiryYear, card.expiryMonth, card.CVN - card details
• customer.username, customer.password, customer.merchant - as provided by Westpac
• order.amount - amount being debited to the card-holder's account
• customer.orderNumber - unique txn reference for the capture
• order.ECI - defined by how you received the card-holder's details
• card.currency - provided if you have multiple currencies available
• message.end - to indicate the end of the request

Refund orders

The way that refunds are handled depends on the configuration of a specific merchant. The options are:

Option 1 - Adhoc refunds

Merchant is configured to allow Refunds without reference to a Capture. In this case, the originalOrderNumber parameter does not require population and is ignored. This option is provided for merchants where option 2 or 3 is not appropriate and also for backward compatibility.

Option 2 - Refund against capture using customer.originalOrderNumber

Merchant is configured to only allow Refunds with a reference to the original Capture. In this case, the originalOrderNumber parameter must be populated otherwise the call will fail. If the originalOrderNumber is populated, the order number will be checked to ensure that it was an approved Capture. Finally, the refund will be checked to determine if the amount is less than the original capture less other approved refunds against the same capture. If all of these checks are passed, the transaction will be processed as per normal. If any of the checks fail, a QV response will be returned with response text differing based on which condition failed.

This option is recommended if appropriate to provide a higher level of security against fraudulent transactions.

Although all parameters should be supplied as per normal, the following includes an explanation of the key API parameters required for a refund against an original capture:

• order.type=refund
• card.PAN, card.expiryYear, card.expiryMonth - if supplied they must match the details given on the original capture. If they are not supplied then the values given in the original capture will be reused.
• order.amount - amount being refunded, must not exceed amount originally captured
• customer.orderNumber - new, unique transaction reference for the refund
• customer.originalOrderNumber - order number of original capture

Option 3 - Refund against capture using customer.originalReferenceNo

Merchant is configured to only allow Refunds with a reference to the original Capture and wish to refund payments made via other QuickStream product channels (for example, QuickWeb, QuickVoice or QuickBatch).

The 3^rd option is similar to the second option, except that the response.referenceNo field from the original capture is included in the request:

• order.type=refund
• card.PAN, card.expiryYear, card.expiryMonth - if supplied they must match the details given on the original capture. If they are not supplied then the values given in the original capture will be reused.
• order.amount - amount being refunded, must not exceed amount originally captured
• customer.orderNumber - new, unique txn reference for the refund
• customer.originalReferenceNo - response.referenceNo of original capture

Query orders

In order to execute a 'query', the request must include:

• order.type=query
• your identification details (customer.username, customer.password & customer.merchant)
• customer.orderNumber of order you are querying

For most transactions, the response will include the previously returned response code. However, if this was previously a summary code of 2 (i.e. Transaction Erred), the API will again query the banking network to determine an updated response code for the transaction if available.

When executing a Query order, it is important to note that it is possible that the response code may indicate a failure with the query itself rather than the original transaction itself. For example, the original transaction may have been successful but the subsequent query fails due to a network issue. For this reason, the previousTxn field should be checked after receiving a query response. If:

• previousTxn = 1, the query has returned a response related to the original transaction and may be used.
• previousTxn = 0, the response is related to the query operation itself and typically indicates a failure in this query for some reason as further indicated in the response code. The response for the original transaction is not included in this response in this circumstance.

One special case for queries is that a QG is returned if the order number supplied is unknown. This may occur if your system has attempted a transaction that failed prior to being attempted in QuickGateway (eg network issues between your server and QuickGateway).

Echo orders

The Echo order type allows your application to interrogate the status of the QuickGateway server. You only need to include order.type=echo in your request. A response code of 00 will be returned if the QuickGateway server is accessible. This is essentially a network test from your server to QuickStream. However, this does not confirm that your merchant account or the payment gateway is available.

API request

Electronic Commerce Indicator

The Electronic Commerce Indicator (ECI) is used by acquirers/issuers to determine the type of transaction being processed. The ECI value should represent the source of the transaction request. That is, the environment that the cardholder used to provide the payment card details to the merchant. It is important that merchants set the correct ECI value during transaction processing to ensure that appropriate merchant service rates are received.

• ¹ Recurring payments are processed at fixed, regular intervals not to exceed one year between transactions. Please consult your implementation engineer before attempting to use this value.
• ² An instalment payment is part of a series of payments for a single purchase of goods or services. Please consult your implementation engineer before attempting to use this value.
• ³ The numeric ECI values are only available when the transaction is contains the 3D Secure order.xid and order.cavv fields. Depending on your 3D Secure MPI software, you may need to convert the Mastercard ECI values to the Visa ECI values depicted above. Please consult your implementation engineer before attempting to use ECI 5, 6 or 7.

Limits

In order to restrict the amount of transactions, minimum and maximum limits may be configured on request for your merchant. If a transaction request falls outside of these limits, a 'QD' response will be returned.

For example, a $10,000 maximum transaction limit may be configured for your merchant to reduce the risk associated with transactions conducted through the gateway.

Preventing duplicate payments

When implementing the API, it is your responsibility to ensure that your application prevents customers from performing duplicate payments. However, this section is provided as a guide to best practices to avoid duplicate payments.

Firstly, the most common causes of customers performing duplicate payments via ecommerce applications are:

• Customer double-clicks on Make Payment button on web application and the payment is executed twice.
• Customer does not wait sufficient time for the transaction response to be returned and they retry the transaction.
• Due to a system or network issue, the customer does not receive a response from your system and they retry the transaction.

In each case, safeguards can be put in place which virtually eliminate duplicate payments.

With the API, it is important to remember that the customer.orderNumber must be unique for each distinct transaction attempt. This means that if a transaction is retried with the identical customer.orderNumber, it will only be processed once (see PreviousTxn for more details on previousTxn field in the response). However, if transactions are submitted with the same details except with a different customer.orderNumber, they will both be processed.

The following recommendations should be considered in your application to prevent duplicate payments:

• If providing a web or screen interface, ensure that the Make Payment button can only be clicked once and double-clicking will not attempt two transactions.
• Prior to executing an API transaction, commit this to permanent storage in your system in a pending state. When the response is returned, update the details with the response. If there is a network failure mid-transaction or your application crashes, you may then later use the Query operation to determine the success or otherwise of the first attempt.
• Once a customer has confirmed that they wish to pay, check if you have any approved, pending or incomplete (eg summary code of 2) transactions for the same customer number, card number and amount within a recent time period (eg 24 hours). If you do find a match, inform the customer of the situation (eg "Possible duplicate payment attempt. Please check your statement and confirm whether transaction has been processed before retrying.") but optionally give them the opportunity to proceed with executing the payment if they wish.

API response

System times

All times are based on time. This is either Australian Eastern Standard Time (AEST) or Australian East Daylight Time (AEDT) depending on the time of year.

Settlement date

The settlement date represents the date that the transaction will be settled by the acquiring bank. The settlement date cut-off for card transactions processed through an Australian merchant facility is 18:00 Sydney Time. If you process transactions after this time, the settlement date will be the following day. For example, if you process a transaction at 7pm on 24 Jan 2006, the settlement date will be 25 Jan 2006 (represented as 20060125 in the response).

Furthermore, the settlement date does not necessarily mean that the funds will be credited on the settlement date returned. Again, this is up to the relevant acquiring bank (see Table 3.3 for a list). However, for reconciliation purposes, all successful transactions through a given acquirer that return the same settlement date will be credited together on the same day.

Westpac credits your account the same day, except on weekends and public holidays when the settlement is delayed until the next banking day. The amount credited is the total of approved transactions. Any merchant service fees will be deducted as separate transactions per your service agreement.

American Express and Diners Club may credit your account a number of days later and may be a net amount (ie approved transactions less the merchant service fees), depending on your contract with them. Although Westpac facilitates the processing of the transaction, we do not control settlement for these schemes and therefore any queries should be made to American Express and Diners Club directly.

The settlement date will be returned for all approved transactions. It will often be returned for declined transactions but not all declined transactions. It will be returned only if the transaction is stored in the QuickStream database, but not transactions rejected prior to this (for example: QJ - Incorrect Customer Password). For customers receiving a transaction log, the settlement date may be used to reconcile the log with your own records.

PreviousTxn

The previousTxn field returned in the response indicates whether the response is based on a previous response for a transaction with the same order number or is a new transaction response. This field will assist the client application in determining if a transaction has been duplicated. On receiving a response for a transaction expected to be attempted for the first time, your application should check that previousTxn=0 and handle the exception if this is not the case.

For example, a Capture is performed with orderNumber=1234 and receives a responseCode=03 (also previousTxn=0). If a transaction is attempted with the same orderNumber (ie 1234), then the same responseCode (ie 03) will be returned and previousTxn=1. The transaction will not be processed again.

Although it can produce the same result, it is better to perform a Query operation than to re-attempt the Capture/Refund if a transaction is suspected to have been processed previously. Please refer to 0 for details on Query orders and how the previousTxn field is used in these cases. Also, refer to 3.3.3.4 for more details on error handling.

Error handling

The API will inform the customer's system of any errors that occurred during the processing of the card request. Error information will be returned in summary form in the response.summaryCode and a detailed description of the error in the response.responseCode and response.text.

Where a response is received, the response.summaryCode may be used to determine the appropriate system behaviour. Recommended system actions based on these responses is included in the following table.

Table 3.2 - Suggested error handling

Summary code 2 - transaction erred

When implementing the API, the summary response of 2 causes the most concern to our customers. In an ideal world, all transactions would simply succeed or fail. Unfortunately, the complexity of card transactions and the interaction with acquiring and issuing financial institutions means it is possible in rare circumstances for a transaction to return with an unknown status. For example, a transaction may be received and processed by a financial institution but a system or network error may occur such that a response it not returned. Given that we do not know the status but it may have been successfully approved and the card debited, we must return the "Transaction Erred" status. The outage with the financial institution may last for some time and therefore the exception handling process must handle this rare but possible situation.

The recommended action is as follows:

1. Perform a Query order via the API against the original orderNumber and wait for the response. The QuickStream system will return the most up-to-date response of the original transaction attempt. This may be different to the response originally received.
2. If the summaryCode from the Query is 0, 1 or 3 and previousTxn = 1 then the transaction may be handled as if the response was received on the first attempt. If previousTxn = 0, the response is not related to the original transaction but instead relates to the actual Query order. A special case is if a QG (Unknown Customer Order Number) response is received, then the transaction is not known to QuickStream and therefore may be retried under the original or new orderNumber.
3. If the status of the transaction cannot be determined through a single Query, the transaction should be marked as held within the client system. As the transaction may have been potentially processed, it is not recommended that the capture/refund be retried under a new customer order number. Your application should indicate to the end user that the status of the transaction is unknown and that they should contact your customer service personnel during applicable hours or provide a receipt number and contact the end user if the transaction is subsequently found to fail.
4. If the summaryCode remains at a 2 after initial Query attempts, we recommend re-querying after 6:30pm to try to automatically determine the status. Westpac have processes in place to try to update Erred transactions with the final status and will endeavour to have statuses updated by 6:30pm. This means that in many cases, the status will be available automatically if re-queries are attempted after this time.
5. If the summaryCode remains at a 2, we recommend re-querying at the same time on the following day as it may take up to 48 hours for the final status of transactions to be updated under some circumstances.
6. For transactions that remain unresolved, customer service would then try to resolve the situation by first using QuickStream Portal to query the transaction status. If this does not resolve the issue, the exception details should be communicated to Westpac CustomerCare for resolution. This would require details on the original transaction (particularly the customer.orderNumber, time and amount), responses and exception handling actions attempted thus far.

Some customers, with a need for minimal customer impact of outages, have implemented additional business logic that tries to protect the end customer from such issues. As this may be useful in your implementation, a typical process is as follows:

• If an API call returns a summaryCode of 0, 1 or 3 then the customer application handles this as per normal.
• If an API call returns a summaryCode of 2 then the customer application handles this by returning a receipt number to the end customer and then tries to determine the transaction result in the background. This ensures that the end customer is not impacted by an outage period. If the transaction subsequently fails, this will require handling through an internal customer care process and may require contact with the end customer.

Error-handling pseudocode

The following pseudocode provides an example of how your code may be structured in order to perform the recommended error-handling logic.

// Initial transaction attempt
ccResponse = ccRequest.processRequest( capture/refund, other API parameters )

if ccResponse.summaryCode != 2 and ccResponse.previousTxn != 1
    // This is the normal condition - transaction attempt is complete
    Store transaction response and handle response

else if ccResponse.previousTxn = 1
    // Transaction has been previously attempted - order number should not be reused
    Handle this exception
else {

    // Transaction attempt is incomplete - try to re-query
    Wait x seconds
    ccResponse = ccRequest.processRequest( query, other API parameters )

    if ccResponse.summaryCode != 2 and ccResponse.previousTxn = 1
        // Query has determined final status so no more queries required
        Store transaction response and handle response

    else if ccResponse.responseCode = 'QG' (unknown order number)
        // Transaction has not been previously attempted
        Indicate to retry transaction using original (or new) order number

    else
        // Transaction queries have not determined the final status
        Set transaction status to incomplete and query again later or followup manually

}

Timeouts

In the case of a timeout error, no summary code or response code may be received. This may occur due to a communications failure between the customer and Westpac. If the customer is unsure if Westpac received the transaction, then it should be handled in the same way as a Summary Code 2.

If repeated timeout errors are received, contact Westpac CustomerCare for resolution.

Card scheme vs credit group

In order to aid reconciliation, the API response includes details on the cardScheme and creditGroup. The differences between these two fields may be explained in the following.

Every transaction will be using a card from a particular card scheme, such as Amex or Visa. However, the creditGroup indicates which transactions will be grouped together in a single credit to the customer's bank account. This occurs for Visa and Mastercard transactions where Westpac will group all such transactions into a single credit. However, Amex and Diners will be credited separately.

The following table summarises the relationship:

Table 3.3 - Card scheme, credit group and acquiring bank relationships

RRN

The Retrieval Reference Number (RRN) is returned from the banking network and may differ in its implementation for each financial institution and card scheme. As such, it is not guaranteed to be unique and may be null in some cases. The RRN should not be used as a unique reference and, as it may be null, cannot be used as a receipt number. If you wish to report a "receipt number" to your customers, the recommended alternative is to use the orderNumber included in the request or the response.referenceNo.

This section describes how to perform pre-authorisation transactions, and how to reverse previous transactions. If you are not already familiar with the terms "pre-authorisation" and "reversal" and how they apply to your business, then you do not need to read this section.

Pre-Authorisations

Most of the transactions you perform using the QuickGateway API will be capture transactions. These transactions are equivalent to a purchase using an EFTPOS device (i.e. someone in a shop purchasing something and paying by card).

Behind the scenes, a capture is made up of two parts: a pre-authorisation, and a clearance. The pre-authorisation is the message that is sent to the issuing bank to check whether the transaction can be processed (i.e. the card number is correct, and the account has enough funds etc). Once the pre-authorisation transaction is approved, the clearance is sent and at the end of the day, the transaction will appear on the card holder's statement. The pre-authorisation can be thought of as "reserving" the funds, and the clearance can be thought of as the message that causes the actual transaction to take place.

Capture transactions consist of these two parts, and they happen seamlessly to the API user. However, the API allows customers to split the process into its two separate components when this is required by a customer's business model. This is the purpose of the "preauth" and "captureWithoutAuth" transactions. The preauth transaction reserves the funds, and the "captureWithoutAuth" transaction adds the transaction to the list of clearances that will occur at the end of the day.

This functionality is not required by most customers and is only made available on request. Customers not setup for these transactions will receive a QC - Invalid Order Type response if they attempt to use them.

An example usage would be if a company had separate order processing and shipping systems. The order processing system could first check the available funds using the "preauth" transaction, and then send the order to the shipping system. When the goods are ready to be shipped, the order processing system would send the captureWithoutAuth transaction to complete the purchase. Separating these two functions allows for the case where the goods are out of stock, or discontinued, since no money has been taken from the card holder's account.

An important consideration is the length of time that a pre-authorisation will last. This time depends solely on the issuing bank and cannot be controlled by Westpac. Most issuers will keep the funds reserved for at least three days. You should certainly not assume that you can safely perform a preauth then perform the captureWithoutAuth 4 weeks later. If this short lifetime of pre-authorisations does not fit your business model, you should reconsider your proposed usage of pre-authorisations.

Each pre-authorisation is given an identifier by the issuing bank so that the clearance can be matched to the reserved funds. This identifier is returned in the response.authId field from the preauth transaction response. It must be passed in the "order.authId" field in the captureWithoutAuth transaction request. Every captureWithoutAuth must have either an order.authId or a customer.originalOrderNumber, otherwise, it will be rejected.

Remember:

1. You must perform a captureWithoutAuth transaction to complete the purchase. If you do not, the funds will not appear in your account.
2. You cannot perform a captureWithoutAuth without a corresponding preauth.
3. Pre-authorisations do not last for very long (typically around 3 days).
4. The preauth and captureWithoutAuth transactions must have unique order numbers in the customer.orderNumber parameter.

Performing pre-auth transactions

To perform a "preauth" transaction, use the following request parameters:

• order.type = preauth
• order.authType = INITIAL or blank.
• customer.orderNumber - unique transaction reference for the pre-authorisation
• All other fields as normal. See API Request.

Example preauth request

order.type=preauth
order.authType=INITIAL
customer.orderNumber=TEST321
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
card.PAN=5163200000000008
card.expiryMonth=01
card.expiryYear=22
order.amount=100

Example response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902050
response.orderNumber=TEST321
response.RRN=701902050
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:04:08
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.authId=BLW736
response.traceCode=752474
response.end

To perform a "captureWithoutAuth" transaction, use the following request parameters:

• order.type = captureWithoutAuth
• card.PAN, card.expiryYear, card.expiryMonth - not present. You are not required to store card details.
• customer.orderNumber - new, unique transaction reference for the captureWithoutAuth (i.e. a different value from the order number used for the original pre-authorisation)
• order.authId - not present
• order.amount - the amount to charge the card-holder
• customer.originalOrderNumber - order number of original preauth transaction
• All other fields as normal. See API Request.

Performing an incremental auth (aka top-up)

To perform an incremental auth (also known as a pre-auth top-up), use the following request parameters:

• order.type = preauth
• order.authType = INCREMENTAL
• order.amount = The amount to top-up the pre-auth.
• order.originalOrderNumber = The value sent in the customer.orderNumber field of the initial successful pre-auth.
• All other fields as normal. See API Request.

Example INCREMENTAL preauth request

order.type=preauth
order.authType=INCREMENTAL
customer.orderNumber=TEST-TOPUP
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
card.PAN=5163200000000008
card.expiryMonth=01
card.expiryYear=22
order.amount=100
customer.originalOrderNumber=TEST321

Example successful response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902051
response.orderNumber=TEST-TOPUP
response.RRN=701902051
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:07:35
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.authId=BLW737
response.traceCode=752477
response.end

Performing a pre-auth extension

To perform a pre-auth extension, use the following request parameters:

• order.type = preauth
• order.authType = EXTENSION
• order.amount = Must be 0.
• order.originalOrderNumber = The value sent in the customer.orderNumber field of the initial successful pre-auth.
• All other fields as normal. See API Request.

Example EXTENSION preauth request

order.type=preauth
order.authType=EXTENSION
customer.orderNumber=TEST-EXTEND
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
card.PAN=5163200000000008
card.expiryMonth=01
card.expiryYear=22
order.amount=0
customer.originalOrderNumber=TEST321

Example successful response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902052
response.orderNumber=TEST-EXTEND
response.RRN=701902052
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:11:02
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.authId=BLW738
response.traceCode=752480
response.end

Performing a pre-auth reauthorisation

To perform a pre-auth reauthorisation, use the following request parameters:

• order.type = preauth
• order.authType = REAUTHORISATION
• order.amount = The full amount to reauthorise.
• order.originalOrderNumber = The value sent in the customer.orderNumber field of the initial successful pre-auth.
• All other fields as normal. See API Request.

Example REAUTHORISATION preauth request

order.type=preauth
order.authType=REAUTHORISATION
customer.orderNumber=TEST-REAUTHORISATION
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
card.PAN=4564710000000004
card.expiryMonth=02
card.expiryYear=19
order.amount=100
customer.originalOrderNumber=TEST321

Example successful response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902052
response.orderNumber=TEST-REAUTHORISATION
response.RRN=701902052
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:11:02
response.cardSchemeName=VISA
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.authId=BLW738
response.traceCode=752480
response.end

Example captureWithoutAuth of a REAUTHORISATION preauth request

order.type=captureWithoutAuth
customer.orderNumber=TEST-REAUTHORISATION-CAPTURE
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
card.PAN=4564710000000004
card.expiryMonth=02
card.expiryYear=19
order.amount=100
customer.originalOrderNumber=TEST-REAUTHORISATION

Performing a partial pre-auth cancellation

You should perform a partial cancellation of a pre-auth when the amount you plan to charge the cardholder has reduced. To perform a partial pre-auth cancellation:

• order.type = preauthCancellation
• order.cancellationType = PARTIAL
• order.amount = The amount to reduce the outstanding balance of the pre-auth.
• order.originalOrderNumber = The value sent in the customer.orderNumber field of the initial successful pre-auth.
• All other fields as normal. See API Request.

Example PARTIAL preauthCancellation request

order.type=preauthCancellation
order.authType=PARTIAL
customer.orderNumber=TEST-CANCEL
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
order.amount=1500
customer.originalOrderNumber=TEST321

Example successful response

response.summaryCode=0
response.responseCode=00
response.text=Approved or completed successfully
response.referenceNo=701902052
response.orderNumber=TEST-CANCEL
response.RRN=701902052
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:11:02
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=752480
response.end

Performing a full pre-auth cancellation

You should perform a full cancellation of a pre-auth when you no longer plan to charge the cardholder at all. To perform a full pre-auth cancellation:

• order.type = preauthCancellation
• order.cancellationType = FULL
• order.amount = The outstanding balance of the pre-auth.
• order.originalOrderNumber = The value sent in the customer.orderNumber field of the initial successful pre-auth.
• All other fields as normal. See API Request.

Example FULL preauthCancellation request

order.type=preauthCancellation
order.authType=FULL
customer.orderNumber=TEST-CANCEL
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
order.amount=1500
customer.originalOrderNumber=TEST321

Example successful response

response.summaryCode=0
response.responseCode=00
response.text=Approved or completed successfully
response.referenceNo=701902052
response.orderNumber=TEST-CANCEL
response.RRN=701902052
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:11:02
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=752480
response.end

Performing an account verification

To perform an account verification auth (also known as a an account status inquiry), use the following request parameters:

• order.type = accountVerification
• order.amount = Must be blank
• card.PAN = The card number to verify.
• card.expiryMonth = The expiry month.
• card.expiryYear = The expiry year.
• All other fields as normal. See API Request.

Example accountVerification request

order.type=accountVerification
customer.orderNumber=TEST123
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
card.PAN=5163200000000008
card.expiryMonth=01
card.expiryYear=22

Example successful response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902049
response.orderNumber=TEST123
response.RRN=701902049
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:00:35
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=752471
response.end

Stored credential transactions

A stored credential is information that is stored by a merchant or its agent to process future purchases for a cardholder. This generally consists of the card number, expiry date and cardholder name. A credential is not considered a stored credential when the merchant or its agent stores the credential to complete a single transaction. This section describes the parameters that merchants must send when using stored credentials for Visa and Mastercard cards.

There are different data requirements for the initial transaction vs subsequent transactions. The table below summarises the differences:

The following examples demonstrate these scenarios

Performing an initial stored credential transaction

To perform an initial stored credential transaction, use the following request parameters:

• order.type = capture
• card.posEntryMode = MANUAL
• card.storedCredentialUsage = INSTALMENT, RECURRING, UNSCHEDULED_CIT or UNSCHEDULED_MIT (Visa only)
• All other fields as normal. See API Request.

Example Visa request

order.type=capture
customer.orderNumber=TEST123
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=REC
card.PAN=4564710000000004
card.expiryMonth=02
card.expiryYear=19
card.posEntryMode=MANUAL
card.storedCredentialUsage=RECURRING

Example successful Visa response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902049
response.orderNumber=TEST123
response.RRN=701902049
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:00:35
response.cardSchemeName=VISA
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=752471
response.authTraceId=g9hs5s8sfphdslm
response.end

Example Mastercard request

order.type=capture
customer.orderNumber=TEST123
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=REC
card.PAN=5163200000000008
card.expiryMonth=08
card.expiryYear=20
card.posEntryMode=MANUAL

Example successful Mastercard response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902049
response.orderNumber=TEST123
response.RRN=701902049
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:00:35
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=752471
response.end

Performing a subsequent stored credential transaction

To perform a subsequent transaction with a stored credential, use the following request parameters:

• order.type = capture
• Card details can be specified using card.PAN, card.expiryMonth and card.expiryYear parameters, or looked up as per Pre-registered Card-holder Accounts.
• card.posEntryMode = STORED_CREDENTIAL
• card.storedCredentialUsage = INSTALMENT, RECURRING, UNSCHEDULED_CIT or UNSCHEDULED_MIT (Visa only)
• order.authTraceId contains the value from response.authTraceId for the initial transaction, if present (Visa only)
• All other fields as normal. See API Request.

Example Visa request

order.type=capture
customer.orderNumber=TEST1241
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=REC
card.PAN=4564710000000004
card.expiryMonth=02
card.expiryYear=19
card.posEntryMode=STORED_CREDENTIAL
card.storedCredentialUsage=RECURRING
order.authTraceId=g9hs5s8sfphdslm

Example successful Visa response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902050
response.orderNumber=TEST1231
response.RRN=701902049
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:00:35
response.cardSchemeName=VISA
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=642181
response.authTraceId=ashf98gan42gfbe
response.end

Example Mastercard request

order.type=capture
customer.orderNumber=TEST1241
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=REC
card.PAN=5163200000000008
card.expiryMonth=08
card.expiryYear=20
card.posEntryMode=STORED_CREDENTIAL

Example successful Mastercard response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902050
response.orderNumber=TEST1231
response.RRN=701902049
response.settlementDate=20170117
response.transactionDate=17-JAN-2017 12:00:35
response.cardSchemeName=MASTERCARD
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=642181
response.end

Scheme tokenisation transactions

Scheme tokenisation (also known as network tokenisation) allows merchants to replace the card number with a token number from the card scheme tokenisation API. The token is tied to the merchant, increasing the security of the solution as the merchant is no longer storing the underlying card number. Merchants acting as the token requestor can process transactions through QuickGateway as follows:

• card.posEntryMode, card.storedCredentialUsage and order.authTraceId are as per the Stored credential transactions section.
• card.PANType is DPAN.
• order.ECI should be 7 for the initial transaction, and as per normal rules otherwise. If the card scheme's transact API returns an ECI value, specify that value in the order.ECI field.
• order.tavv is the 28 character cryptogram value from the card scheme's transact API (if applicable), e.g. MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
• customer.tokenRequestorId is the value assigned to the merchant by the card scheme (if applicable).

Digital wallet transactions

Digital wallet payments are initiated from a website or app with a tokenised card from a digital wallet provider, e.g. Apple Pay, Google Pay, Samsung Pay. Digital wallets provide security through the use of a token and a cryptogram with dynamic secure data. Refer to the digital wallet provider's documentation for details on obtaining and decrypting the token details. Once decrypted, the transaction can be processed through QuickGateway as follows:

• customer.walletProvider is APPLE_PAY, GOOGLE_PAY or SAMSUNG_PAY.
• card.PANType is DPAN.
• order.ECI is often returned from the digital wallet provider, and will normally be 5.
• order.tavv is the 28 character cryptogram value from the digital wallet provider, e.g. MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=

3D Secure transactions

3D Secure is a mechanism for authenticating the cardholder before processing a transaction. QuickGateway does not perform the authentication, but supports the additional fields required for transaction processing. You will need additional software to perform the authentication, i.e a Merchant Plug-In (MPI) for v1 or a 3DS Server for v2.

3D Secure transactions can be processed through QuickGateway as follows:

Reversals

As described in Pre-Authorisations, each capture transaction is comprised of two parts behind the scenes. Since the transaction value does not actually appear on the card holder's statement until the end of that day, it is possible to cancel, or reverse, a transaction before it is cleared. Declined transactions do not need to be reversed.

The cut-off time for reversals is 6pm EST each day. For example, the settlement day of 15 Nov 2005 starts at 6pm on 14 Nov 2005, and ends at 6pm on 15 Nov 2005. Thus, any transaction processed with during the 15 Nov 2005 settlement day can be reversed until 6pm 15 Nov 2005. You cannot reverse any such transactions after this time. Instead, you should perform a refund if the original transaction was a capture, or perform a capture if the original transaction was a refund.

To reverse a transaction, you create the request message and specify the order type as reversal. You must also place the order number of the transaction you wish to reverse in the capture order number field. You should also specify the card number and expiry date of the original transaction if you have them, since extra checking of the transaction will be performed in this case. Below are the details of the parameters for a reversal transaction:

card.PAN, card.expiryYear, card.expiryMonth, order.amount - if supplied they must match the details given on the original transaction. If they are not supplied then the values given in the original transaction will be reused.

customer.orderNumber - new, unique txn reference for the reversal

customer.originalOrderNumber - order number of original transaction (capture, refund or preauth)

You may reverse capture, refund or pre-authorisation transactions. If you attempt to reverse any other transaction type, you will receive an error response.

If the reversal succeeds, a response code of 00 will be returned, and the response code of the original transaction will be updated to 91. If you attempt to query the original transaction, or view it through the administration screens, this is the status that you will see. Your software should also update the response code of the original transaction to 91 for consistency.

Because of the limited time you have to reverse a transaction, the main use of reversal transactions is to ensure that both your system and the QuickGateway system have a consistent status for a transaction. For example, if you perform a capture and before you receive a response, a network error is encountered, you could then reverse the original transaction so that both systems mark the transaction with a 91 response code.

The following table lists the various reasons that a reversal will not be accepted, and the response code you can expect to receive in that situation.

Processing these response codes is relatively simple. If the response is 00 or 21, then either the transaction has been reversed, or does not need to be reversed. If the response is 12, you should check the details of the transaction you are trying to reverse. For example, you may be specifying the wrong capture order number. If you receive a QE, QI or QX response or a network error, you should re-attempt your reversal.

Pre-registered card-holder accounts

The API now provides the option to store card-holder information against a customer reference number or preregistration code (Card Alias/Token), or both. The registering of these details normally takes place on a Westpac-hosted web page. This solution can potentially reduce your obligations under PCI DSS compliance.

For pre-registered cardholder information, use the following parameters:

• order.type - capture, preauth, refund, captureWithoutAuth, reversal (cardholder details are not required for other order types)
• card.PAN, card.expiryYear, card.expiryMonth, card.CVN - these parameters must not be present, otherwise the pre-registered account will not be used
• customer.customerReferenceNumber - the unique reference number for the pre-registered customer
• customer.preregistrationCode - this is often referred to as the 'card token' and can be used to lookup the stored card details instead of or in combination with the customerReferenceNumber.
• other parameters as normal

If the card-holder's details cannot be located, a QA Invalid Parameters response will be returned. Otherwise, the response you receive will be the same as if you had specified the card details yourself.

Administration

Complementing the QuickGateway is a set of administration features that:

• Allow ad-hoc card payments to be made
• Allow refunds to be made against previously successful captures
• Provide searches and export of QuickGateway transactions
• Provide a daily reconciliation email of payment attempts

The online features are accessible via a provided URL and web-based user/password. The site may be accessed over the Internet using recommended web browsers (eg Google Chrome) and operates securely over HTTPS with 128-bit encryption. To further enhance security, particular features may be turned on or off for individual users.

Refer to the separate "QuickStream Portal User Guide" document for more information.

Encrypting fields

Any field in the QuickGateway API can be encrypted. Simply append .encrypted to any field name to send an encrypted value in that field. For example, to send an encrypted card number, put the encrypted value in the card.PAN.encrypted field. QuickGateway will decrypt any field in any request message you wish.

For example, you can use card.PAN.encrypted for capture, refund, preauth, captureWithoutAuth, reversal and registerAccount order types.

You should not use the encrypted field name and the normal field name in the same request, e.g. use either card.PAN or card.PAN.encrypted, but not both.

Encryption process

The encrypted parameter contains the plain text value encrypted with the following process:

1. Extract the public key from the X.509 (.cer) certificate file you were provided.
2. Encrypt the parameter value using the RSA algorithm with PKCS#1 Padding (see https://tools.ietf.org/html/rfc3447#section-7.2.1).
3. Convert the binary result to a string using hexadecimal encoding.
4. Prepend the key ID from the common name on the certificate you were provided e.g. if the common name is "Message Encryption Key K1", then prepend {K1} to the encrypted string.

An example encrypted value is shown below:

{K1}5004D8E601E2FD2D16B1C57A82855ADB9978...2D7102AD9F0C3950B0A5589

Sample code for Java and .NET is below.

Sample code for Java

import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.NoSuchProviderException;
import java.security.cert.CertificateException;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.security.auth.x500.X500Principal;
import javax.xml.bind.DatatypeConverter;

/**
 * This is the sample code for encrypting message fields with the RSA key for
 * QuickGateway.
 */
public class MessageFieldEncryptor
{
    private static final Pattern theKeyIdSubjectPattern =
        Pattern.compile( ".*CN=Message Encryption Key (K\\d{1,3}).*" );
    private X509Certificate myCertificate;
    private final String myKeyId;

    public MessageFieldEncryptor( final File certificateFile )
            throws IOException, CertificateException
    {
        final InputStream certIn = new FileInputStream( certificateFile );
        try
        {
            myCertificate =
                (X509Certificate)CertificateFactory.getInstance( "X.509" )
                    .generateCertificate( certIn );
        }
        finally
        {
            certIn.close();
        }
        myKeyId = extractKeyId( myCertificate.getSubjectX500Principal() );
    }

    public MessageFieldEncryptor( final X509Certificate certificate )
    {
        myCertificate = certificate;
        myKeyId = extractKeyId( myCertificate.getSubjectX500Principal() );
    }

    private String extractKeyId( final X500Principal subjectX500Principal )
    {
        final String subject = subjectX500Principal.getName();
        final Matcher matcher = theKeyIdSubjectPattern.matcher( subject );
        if ( !matcher.matches() )
        {
            throw new IllegalStateException(
                "Could not get key identifier from subject " + subject );
        }
        return matcher.group( 1 );
    }

    public String encryptField( final String value )
            throws NoSuchAlgorithmException,
                   NoSuchProviderException,
                   NoSuchPaddingException,
                   InvalidKeyException,
                   IllegalBlockSizeException,
                   BadPaddingException
    {
        final Cipher rsa = Cipher.getInstance( "RSA", "SunJCE" );
        rsa.init( Cipher.ENCRYPT_MODE, myCertificate );
        return "{" + myKeyId + "}" +
            DatatypeConverter.printHexBinary( rsa.doFinal( value.getBytes() ) );
    }

    public static void main( final String[] args ) throws Exception
    {
        final MessageFieldEncryptor encryptor =
            new MessageFieldEncryptor( new File( "MessageEncryptionKey.cer" ) );

        final String cardNumber = "4444333322221111";

        System.out.println( encryptor.encryptField( cardNumber ) );
    }
}

Sample code for .NET

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Security.Cryptography.X509Certificates;
using System.Security.Cryptography;
using System.Text.RegularExpressions;

class MessageFieldEncryptor
{

    private X509Certificate2 myCertificate;
    private string myKeyId;

    public MessageFieldEncryptor(X509Certificate2 certificate)
    {
        myCertificate = certificate;
        myKeyId = extractKeyId(myCertificate.Subject);
    }

    public MessageFieldEncryptor(string certificateFileName) :
            this(new X509Certificate2(certificateFileName))
    {
    }

    private string extractKeyId(string subject)
    {
        Regex regex = new Regex(".*CN=Message Encryption Key (K\\d{1,3}).*");
        Match match = regex.Match(subject);
        if (match.Success)
        {
            return match.Groups[1].Value;
        }
        else
        {
            throw new Exception("Could not get key identifier from subject " + subject);
        }
    }

    public string encryptField(string value)
    {
        RSACryptoServiceProvider rsa =
            (RSACryptoServiceProvider)myCertificate.PublicKey.Key;
        byte[] encryptedBytes =
            rsa.Encrypt(Encoding.UTF8.GetBytes(value), false);
        return "{" + myKeyId + "}" +
            BitConverter.ToString(encryptedBytes).Replace("-", "");
    }

    static void Main(string[] args)
    {
        string cardNumber = "4444333322221111";

        MessageFieldEncryptor encryptor =
            new MessageFieldEncryptor("Z:\\MessageEncryptionKey.cer");

        Console.WriteLine( encryptor.encryptField( cardNumber ) );
        Console.ReadKey();
    }
}

Changing keys

The certificate containing the public key will change periodically. Each certificate has a unique key ID that must be present in the encrypted field value. You should make sure that you document the procedure to change the message encryption key certificate file in your solution.

Note that the certificate for message field encryption is different from your client certificate that authenticates your system to QuickGateway. Both will be changed periodically. The message field encryption certificate will always be a ".cer" file and have "Message Encryption Key" in the common name of its subject.

Dealing with QI responses

A QI response from the API most often indicates that there was a network error between your server and the QuickGateway server. Your server cannot know the transaction status because either the request did not arrive at the QuickGateway server, or the response did not make it back to your server.

If you have followed the recommendations in Error Handling, your software should correctly handle the QI response code using one of the following options:

1. Repeatedly querying the transaction via the API at a later stage to determine the status (see Query Orders)
2. Reversing the transaction via the API to ensure that the card holder is not debited (see Reversals), or
3. Raising an alert for your support staff to handle

Your support staff can always determine the final status of the transaction using the search pages in QuickStream Portal ⁴. Depending on your business procedures, your support staff can either enter this status into your system, or contact Customer Care to void the transaction. If a transaction does not appear on these pages, the transaction was not received or processed by the QuickGateway server.

Network errors can be almost impossible to investigate after the fact, so it is vital that you investigate while you are experiencing an issue. You should try these steps:

1. If you use a proxy, check that your proxy settings are correct, and check that there are no other issues with your proxy server.
2. If you do not use a proxy server, log in to your server and telnet to ccapi.client.qvalent.com on port 443. Record the results of this test for use by your network administrator.
3. Contact your network administrator and ask him/her to investigate the issue. The results of the telnet test can help him/her to begin the investigation.
4. If you still cannot locate the cause of the QI responses you should contact Qvalent Technical Support team for assistance. Your network administrators will need to be available to work through the problem with the Qvalent network administrators.

⁴ It may take a few minutes for the transaction to appear on these search pages.

Soft descriptors for Aggregators and Staged digital wallet operators

Soft-descriptors are informational fields that Aggregators and Staged Digital Wallet Operators 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 QuickGateway API request includes new fields to provide these soft-descriptors.

Read more about Soft descriptors for Aggregators.

API request fields

These fields must be in transaction requests for the following order.type values.

• capture
• refund
• preauth
• captureWithoutAuth
• reversal

Provide these fields as well as the standard fields for an API request.

API response fields

No additional fields are provided in an API response. See the standard fields for an API response.

Integration guides

Client software packages are available to download through QuickStream Portal. The following guides are available to assist in your integration with QuickGateway.

• Java Client Integration
• .Net Client Integration
• PHP Client Integration
• COM Client Integration
• Custom Integration

Java client integration

The QuickGateway API for Java requires Java 2 Standard Edition 1.4 or higher. Earlier versions of Java are not supported.

What the API distribution file contains

The CardsAPI_java.zip file you received contains the files and folders listed below:

Installation procedure

• Ensure that the CardsAPI.jar and bcprov-jdk14-130.jar files are in your class path. The specific details of this installation will depend on your application (e.g. a web application will include these JAR files in the WEB-INF/lib folder).
• Save your certificate on your computer. Ensure that you pass the full file path and name as the certificateFile parameter to the initialise method of the CardsAPI object. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
• Choose a log directory and ensure that your application can write to that directory on the computer. Ensure that you pass this value in the logDirectory parameter to the initialise method of the CardsAPI object.

Using the API client

Upgrade from pre-9.0 version

Version 9.0 of the API Client introduces restructuring of the API objects for future proofing. Rather than using separate CreditCardAPIRequest and CreditCardAPIResponse objects, the new client uses a single CardsAPI object that provides a processCreditCard method.

The processCreditCard method accepts a Map of request parameters (keys in the map are parameter names and values in the map are parameter values), and returns a Map of response parameters.

Calling the initialise method is mandatory for the new client. You cannot use the CardsAPI object until it has been initialised.

Changes will be required to your system to use the new client software. Please read the rest of this document for details on how to use the new CardsAPI object. You will need a new certificate file to use with the new API client.

Initialising the CardsAPI object

Before you can perform transactions with the CardsAPI object, you must initialise it with initialisation parameters. Details of the initialisation methods are shown below.

Method: initialise

Description: Initialise this object so that it can process QuickGateway transactions. Configuration information is read from the provided parameters.

Arguments: parameters - the java.util.Map of initialisation parameters to use. parameters must contain at a minimum the URL, the log directory and the certificate file. See the following table for the available parameters. The keys in the Map are the parameter names, and the values in the Map are the parameter values.

Return Value: None.

Method: isInitialised

Description: Returns true if this client object has been correctly initialised or false

Arguments: None.

Return Value: true if this client object has been correctly initialised or false otherwise.

The initialisation parameters are:

Processing transactions

Transactions are processed using the processCreditCard method, which is described in the table below.

Method: processCreditCard

Description: Main card processing method. Pass the request parameters into this method, then the current thread will wait for the response to be returned from the server.

Arguments: parameters - the java.util.Map containing all the request parameters to send to the server. The keys in the Map are the parameter names, and the values in the Map are the parameter values. Note that the message.end parameter is included for you - you do not need to include the message.end parameter in this map.

Return Value: A java.util.Map containing the response parameters from the server. The keys in the Map are the parameter names, and the values in the Map are the parameter values.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

Using the example code

Using the Java example code

• Save your certificate on your computer. Record this location for use in the initialisation of the CardsAPI object. Update this value in the CCAPITester.java file. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
• Choose a log directory and ensure that your application can write to that directory on the computer. Use this location in the initialisation of the CardsAPI object. Update this value in the CCAPITester.java file.
• Enter your username, password and merchant identifier in the CCAPITester.java file. You may need to add proxy information to the initialisation parameters, as per Initialising the CardsAPI object.
• If you have ANT installed on your machine, run ant compile test from the examples/ directory to compile and test your example program. If you do not have ANT installed, you must compile and run the test program manually.

Using the JSP example code

• Copy the contents of the examples/jsp/ directory to your web directory. Also, copy CardsAPI.jar and bcprov-jdk14-130.jar to the WEB-INF/lib/ directory under your web directory.
• Copy your certificate file to your server. Record this location for use in the initialisation of the CardsAPI object. Update this value in the processCard.jsp file. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
• Choose a log directory and ensure that your web application can write to that directory on the server. Use this location in the initialisation of the CardsAPI object. Update this value in the processCard.jsp file.
• Enter your username, password and merchant identifier in the processCard.jsp file. You may need to add proxy information to the initialisation parameters, as per Initialising the CardsAPI object.
• Using your web browser, browse to index.htm, then press the Process Capture button. You should receive a successful response from QuickGateway.

QuickGateway command-line application

To facilitate connectivity and configuration testing of the QuickGateway API, a sample command line application has been provided. This application helps you check your configuration before developing your own application.

To run the command line program, type the following at your command prompt:

java -cp CardsAPI.jar;bcprov-jdk14-130.jar com.qvalent.ccapi.CardsAPI
"url=https://ccapi.client.support.qvalent.com/post/CreditCardAPIRecei
ver&certificateFile=ccapi.q0&logDirectory=."
"customer.username=USER&customer.password=PASS&customer.merchant=MERC
HANT&order.type=capture&card.PAN=4564710000000004&card.CVN=847&card.e
xpiryYear=09&card.expiryMonth=02&order.amount=1000&customer.orderNumb
er=01&card.currency=AUD&order.ECI=SSL&message.end="

Please note the following points regarding the command above:

• There is a space between the two command-line arguments (i.e. after the logDirectory part and before the username part): ...logDirectory=." "customer.username=...
• You must run the above command in a directory that contains the CardsAPI.jar and bcprov-jdk14-130.jar files and your certificate file (which is named ccapi.q0).
• You should also replace USER with your API username, PASS with your API password and MERCHANT with your merchant identifier provide by Westpac.
• You may need to add proxy information to the initialisation parameters, as per Initialising the CardsAPI object.

After entering the above command, the result of the test transaction will be displayed. If the result contains a result.summaryCode parameter of 0, your test transaction was successful. Note that because this transaction is performed against the test environment, the transaction will not appear on the cardholder statement or your bank account.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

Troubleshooting

The table below describes some of the common errors you may encounter during your implementation phase, and what to do to resolve them.

.Net Client Integration

The QuickGateway API for Microsoft .NET requires the .NET Framework 4.5 or higher.

Windows Vista Service Pack 2 or later is required.

What the API distribution file contains

The CardsAPI_net.zip file you received contains the files and folders listed below:

Installation procedure

Install the QuickGateway API client as follows:

1. Extract the CardsAPI_net.zip file to a new directory on the computer. If you are using WinZip, ensure that the Use Folder Names option is checked.
2. Download your certificate and save it on your computer. Ensure that you pass the full file path and name as the certificateFile parameter to the Initialise method of the CardsAPI object. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
3. Choose a log directory and ensure that your application can write to that directory on the computer. Ensure that you pass this value in the logDirectory parameter to the Initialise method of the CardsAPI object.

Using the API client

Upgrade from pre-9.0 version

Version 9.0 of the API Client introduces a client object rather than using the ServerXMLHTTP object. The benefits are simpler configuration and logging to assist in trouble-shooting. The ProcessCreditCard method accepts an IDictionary of request parameters (keys in the map are parameter names and values in the map are parameter values), and returns an IDictionary of response parameters. Calling the initialise method is mandatory for the new client. You cannot use the CardsAPI object until it has been initialised.

Changes will be required to your system to use the new client software. Please read the rest of this document for details on how to use the new CardsAPI object. You will need a new certificate file to use with the new API client.

Initialising the CardsAPI object

Before you can perform transactions with the CardsAPI object, you must initialise it with initialisation parameters. Details of the initialisation methods are shown below.

Method: Initialise

Description: Initialise this object so that it can process QuickGateway transactions. Configuration information is read from the provided parameters.

Arguments: parameters - the IDictionary of initialisation parameters to use. parameters must contain at a minimum the URL, the log directory and the certificate file. See the following table for the available parameters. The keys in the IDictionary are the parameter names, and the values in the IDictionary are the parameter values.

Return Value: None.

Method: IsInitialised

Description: Returns true if this client object has been correctly initialised or false

Arguments: None.

Return Value: true if this client object has been correctly initialised or false otherwise.

The initialisation parameters are:

Note that after you have initialised the CardsAPI object, you can call the ProcessCreditCard method on it multiple times. However, you cannot use the object from multiple pages - you must create a new instance of the object each time the page is called. The COM Interop layer forces the CardsAPI object to have the Apartment threading model, so each instance of the object can only be used by one thread at a time. This means that you cannot put the CardsAPI object in the ASP Application object.

Processing transactions

Transactions are processed using the ProcessCreditCard method, which is described in the table below.

Method: ProcessCreditCard

Description: Main card processing method. Pass the request parameters into this method, then the current thread will wait for the response to be returned from the server.

Arguments: parameters - the IDictionary containing all the request parameters to send to the server. The keys in the IDictionary are the parameter names, and the values in the IDictionary are the parameter values. Note that the message.end parameter is included for you - you do not need to include the message.end parameter in this map.

Return Value: A IDictionary containing the response parameters from the server. The keys in the IDictionary are the parameter names, and the values in the IDictionary are the parameter values.

Using the example code

Using the command line example code

• Install the QuickGateway API on your web server.
• Copy your certificate file to your computer. Record this location for use in the initialisation of the CardsAPI object. Update this value in the CCAPITester.cs file. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
• Choose a log directory and ensure that your application can write to that directory on the computer. Use this location in the initialisation of the CardsAPI object. Update this value in the CCAPITester.cs file.
• Enter your username, password and merchant identifier in the CCAPITester.cs file. You may need to add proxy information to the initialisation parameters.
• Compile and run the CCAPITester.cs test program, referencing the CardsAPI.dll file.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

Using the ASP.Net example code with Visual Studio 2015

Install the QuickGateway API on your computer. If your web server is not the same as your development workstation, install the QuickGateway API on your development workstation.

• Using Visual Studio 2015, create a new C# ASP.NET Web Forms project on your web server. Delete the Default.aspx file from the project.
• Copy the contents of the examples/asp.net/ directory to your project directory on your web server, replacing any existing files.
• Using Visual Studio, right-click on your project and select Add -> Existing Item. In the file selection dialog, change the Files of type option to All Files (.). Depending on your configuration, you may also need to change the folder to a network share for your web server. In the file selection dialog, choose the following files:
  • index.htm
  • Global.aspx
  • processCard.aspx
  • processCard.aspx.cs
  • style.css
• Add a reference to the CardsAPI.dll to your Visual Studio project.
• Download your certificate and save it on your web server. Record this location for use in the initialisation of the CardsAPI object. Update this value in the Global.asax.cs file.
• Choose a log directory and ensure that your web application can write to that directory on the server. Use this location in the initialisation of the CardsAPI object. Update this value in the Global.asax.cs file.
• Enter your username and password in the processCard.aspx.cs file. You may need to add proxy information to the initialisation parameters.
• Build your project. Visual Studio will copy the required files to your web server.
• Right-click the index.htm file and select Set As Start Page. Press Ctrl-F5 to run the web site in a new browser window, then press the Process Capture button. You should receive a successful response from the Qvalent payment server.

QuickGateway command-line application

To facilitate connectivity and configuration testing of the QuickGateway API, a sample command line application has been provided. This application helps you check your configuration before developing your own application.

To run the command line program, type the following at your command prompt:

CardsAPITest "url=https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver&certificateFile=ccapi.q0&logDirectory=." "customer.username=USER&customer.password=PASS&customer.merchant=MERCHANT&order.type=capture&card.PAN=4564710000000004&card.CVN=847&card.expiryYear=09&card.expiryMonth=02&order.amount=1000&customer.orderNumber=01&card.currency=AUD&order.ECI=SSL"

Please note the following points regarding the command above:

• There is a space between the two command-line arguments (i.e. after the logDirectory part and before the username part): ...logDirectory=." "customer.username=...
• You must run the above command in a directory that contains the CardsAPITest.exe and CardsAPI.dll files and your certificate file (which is named ccapi.q0).
• You should also replace USER with your API username, PASS with your API password and MERCHANT with your merchant identifier provide by Westpac.
• You may need to add proxy information to the initialisation parameters, as per Initialising the CardsAPI object.

After entering the above command, the result of the test transaction will be displayed. If the result contains a result.summaryCode parameter of 0, your test transaction was successful. Note that because this transaction is performed against the test environment, the transaction will not appear on the cardholder statement or your bank account.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

Troubleshooting

The table below describes some of the common errors you may encounter during your implementation phase, and what to do to resolve them.

8000ffff Errors

This error normally occurs under Windows Server 2003 and is usually caused by either a permissions problem, or a .NET version conflict.

The first step to rectifying this issue is to ensure that your computer has the latest updates from Microsoft.

If the problem still occurs, you will need to change your permissions settings as follows:

1. Click Start then Run. Enter regedit and press enter.
2. Locate the following registry key. Note that this key may differ depending on which user your application pool is running as (default is Network Service [aka S-1-5-20]). HKEY_USERS\S-1-5-20\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Zones
3. Right-click on Zones and select 'Permissions'.
4. Add the IUSR account (or whichever account your application runs under) to this list and ensure that the box under Allow and next to Read is checked.
5. Press OK then exit Registry Editor.

If the problem still occurs, it may be a .NET version conflict. This could be the case if you have other .NET applications on the same web server and they use .NET 2.0, conflicts can occur. You should create a new application pool for your ASP application as follows:

1. In IIS Manager, expand the icon for your computer.
2. Right-click Application Pools and select New -> Application Pool.
3. Enter the name for the pool as 'AppPool .Net 1.1' and select Use default settings for new application pool.
4. Expand the web sites under the computer icon and right-click on the folder for your web application.
5. On the Directory tab, if the Application Name is 'Default Application', press Create. Select 'AppPool .Net 1.1' as the Application Pool.
6. On the ASP.NET tab, ensure that '1.1.4322' is selected as the ASP.NET Version.
7. Press OK.
8. Restart IIS.

PHP client integration

The QuickGateway API for PHP requires PHP 5 or higher.

You must install the 'libcurl' package for PHP. See http://www.php.net/manual/en/ref.curl.php.

What the API distribution file contains

The CardsAPI_php.zip file you received contains the files and folders listed below:

Installation procedure

1. Copy the Qvalent_CardsAPI.php file to your web server.
2. Include the Qvalent_CardsAPI.php file in your payments page as follows:

<?php include 'Qvalent_CardsAPI.php' ?>

Using the API client

Initialising the CardsAPI object

Before you can perform transactions with the Qvalent_CardsAPI object, you must initialise it with initialisation parameters. Details of the initialisation methods are shown below.

Method: initialise

Description: Initialise this object so that it can process QuickGateway transactions. Configuration information is read from the provided parameters.

Arguments: parameters - the array of initialisation parameters to use. parameters must contain at a minimum the URL, the log directory and the certificate file. See the following table for the available parameters. The keys in the array are the parameter names, and the values in the array are the parameter values.

Return Value: None.

Method: isInitialised

Description: Returns true if this client object has been correctly initialised or false

Arguments: None.

Return Value: true if this client object has been correctly initialised or false otherwise.

The initialisation parameters are:

Processing transactions

Transactions are processed using the processCreditCard method, which is described in the table below.

Method: processCreditCard

Description: Main card processing method. Pass the request parameters into this method, then the current thread will wait for the response to be returned from the server.

Arguments: parameters - the array containing all the request parameters to send to the server. The keys in the array are the parameter names, and the values in the array are the parameter values. Note that the message.end parameter is included for you - you do not need to include the message.end parameter in this array.

Return Value: A array containing the response parameters from the server. The keys in the array are the parameter names, and the values in the array are the parameter values.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

Using the web example code

• Copy the Qvalent_CardsAPI.php file and the contents of the examples/ directory to your web directory.
• Copy your certificate file to your server. Replace CERT_FILE with the fully qualified file name of the certificate file in the processCard.php file. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
• Copy the cacerts.crt Certificate Authority file to a secure location on your server. Replace CA_FILE with the fully qualified file name of the Certificate Authority file in the processCard.php file.
• Choose a log directory and ensure that your web application can write to that directory on the server. Replace LOG_DIR with the log directory in the processCard.php file.
• Enter your username, password and merchant identifier in the processCard.php file. You may need to add proxy information to the initialisation parameters.
• Using your web browser, browse to the example index.htm (e.g. http://localhost/card_test/index.htm), then press the Process Capture button. You should receive a successful response from the Qvalent payment server.

Troubleshooting

The table below describes some of the common errors you may encounter during your implementation phase, and what to do to resolve them.

COM client integration

The QuickGateway API for Microsoft Component Object Model (COM) requires the .NET Framework 4.5 or higher. The API itself runs under .NET and is available to COM applications through COM Interop.

Windows Vista Service Pack 2 or later is required.

What the API distribution file contains

The CardsAPI_com.zip file you received contains the files and folders listed below:

Installation procedure

Install the QuickGateway API client as follows:

1. Extract the CardsAPI_com.zip file to a new directory on the computer. If you are using WinZip, ensure that the Use Folder Names option is checked.
2. Double click on the register.cmd file.
3. The following message will be displayed: 'Types registered successfully'. Press any key to close the window.
4. Download your certificate and save it on your computer. Ensure that you pass the full file path and name as the certificateFile parameter to the Initialise method of the CardsAPI object. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
5. Choose a log directory and ensure that your application can write to that directory on the computer. Ensure that you pass this value in the logDirectory parameter to the Initialise method of the CardsAPI object.

Using the API client

Upgrade from pre-9.0 version

Version 9.0 of the API Client introduces a client object rather than using the ServerXMLHTTP object. The benefits are simpler configuration and logging to assist in trouble-shooting. The ProcessCreditCard method accepts an IDictionary of request parameters (keys in the map are parameter names and values in the map are parameter values), and returns an IDictionary of response parameters. Calling the initialise method is mandatory for the new client. You cannot use the CardsAPI object until it has been initialised.

Changes will be required to your system to use the new client software. Please read the rest of this document for details on how to use the new CardsAPI object. You will need a new certificate file to use with the new API client.

Initialising the CardsAPI object

Before you can perform transactions with the CardsAPI object, you must initialise it with initialisation parameters. Details of the initialisation methods are shown below.

Method: Initialise

Description: Initialise this object so that it can process QuickGateway transactions. Configuration information is read from the provided parameters.

Arguments: parameters - the IDictionary of initialisation parameters to use. parameters must contain at a minimum the URL, the log directory and the certificate file. See the following table for the available parameters. The keys in the IDictionary are the parameter names, and the values in the IDictionary are the parameter values.

Return Value: None.

Method: IsInitialised

Description: Returns true if this client object has been correctly initialised or false

Arguments: None.

Return Value: true if this client object has been correctly initialised or false otherwise.

The initialisation parameters are:

Note that after you have initialised the CardsAPI object, you can call the ProcessCreditCard method on it multiple times. However, you cannot use the object from multiple pages - you must create a new instance of the object each time the page is called. The COM Interop layer forces the CardsAPI object to have the Apartment threading model, so each instance of the object can only be used by one thread at a time. This means that you cannot put the CardsAPI object in the ASP Application object.

Processing transactions

Transactions are processed using the ProcessCreditCard method, which is described in the table below.

Method: ProcessCreditCard

Description: Main card processing method. Pass the request parameters into this method, then the current thread will wait for the response to be returned from the server.

Arguments: parameters - the IDictionary containing all the request parameters to send to the server. The keys in the IDictionary are the parameter names, and the values in the IDictionary are the parameter values. Note that the message.end parameter is included for you - you do not need to include the message.end parameter in this map.

Return Value: A IDictionary containing the response parameters from the server. The keys in the IDictionary are the parameter names, and the values in the IDictionary are the parameter values.

Using the ASP example code

• Install the QuickGateway API on your web server.
• Copy the contents of the examples/ directory to your web directory.
• Save your certificate on your computer. Record this location for use in the initialisation of the CardsAPI object. Update this value in the processCard.asp file. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future.
• Choose a log directory and ensure that your web application can write to that directory on the server. Use this location in the initialisation of the CardsAPI object. Update this value in the processCard.asp file.
• Enter your username and password in the processCard.asp file. You may need to add proxy information to the initialisation parameters..
• Using your web browser, browse to index.htm (e.g. http://localhost/card_test/index.htm), then press the Process Capture button. You should receive a successful response from the Qvalent payment server.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

QuickGateway command-line application

To facilitate connectivity and configuration testing of the QuickGateway API, a sample command line application has been provided. This application helps you check your configuration before developing your own application.

To run the command line program, type the following at your command prompt:

CardsAPITest "url=https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver&certificateFile=ccapi.q0&logDirectory=." "customer.username=USER&customer.password=PASS&customer.merchant=MERCHANT&order.type=capture&card.PAN=4564710000000004&card.CVN=847&card.expiryYear=09&card.expiryMonth=02&order.amount=1000&customer.orderNumber=01&card.currency=AUD&order.ECI=SSL"

Please note the following points regarding the command above:

• There is a space between the two command-line arguments (i.e. after the logDirectory part and before the username part): ...logDirectory=." "customer.username=...
• You must run the above command in a directory that contains the CardsAPITest.exe and CardsAPI.dll files and your certificate file (which is named ccapi.q0).
• You should also replace USER with your API username, PASS with your API password and MERCHANT with your merchant identifier provide by Westpac.
• You may need to add proxy information to the initialisation parameters, as per Initialising the CardsAPI object.

After entering the above command, the result of the test transaction will be displayed. If the result contains a result.summaryCode parameter of 0, your test transaction was successful. Note that because this transaction is performed against the test environment, the transaction will not appear on the cardholder statement or your bank account.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

Troubleshooting

The table below describes some of the common errors you may encounter during your implementation phase, and what to do to resolve them.

8000ffff Errors

This error normally occurs under Windows Server 2003 and is usually caused by either a permissions problem, or a .NET version conflict.

The first step to rectifying this issue is to ensure that your computer has the latest updates from Microsoft.

If the problem still occurs, you will need to change your permissions settings as follows:

1. Click Start then Run. Enter regedit and press enter.
2. Locate the following registry key. Note that this key may differ depending on which user your application pool is running as (default is Network Service [aka S-1-5-20]). HKEY_USERS\S-1-5-20\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Zones
3. Right-click on Zones and select 'Permissions'.
4. Add the IUSR account (or whichever account your application runs under) to this list and ensure that the box under Allow and next to Read is checked.
5. Press OK then exit Registry Editor.

If the problem still occurs, it may be a .NET version conflict. This could be the case if you have other .NET applications on the same web server and they use .NET 2.0, conflicts can occur. You should create a new application pool for your ASP application as follows:

1. In IIS Manager, expand the icon for your computer.
2. Right-click Application Pools and select New -> Application Pool.
3. Enter the name for the pool as 'AppPool .Net 1.1' and select Use default settings for new application pool.
4. Expand the web sites under the computer icon and right-click on the folder for your web application.
5. On the Directory tab, if the Application Name is 'Default Application', press Create. Select 'AppPool .Net 1.1' as the Application Pool.
6. On the ASP.NET tab, ensure that '1.1.4322' is selected as the ASP.NET Version.
7. Press OK.
8. Restart IIS.

Certificate files

Protecting your certificate

Your certificate file is used to authorise your requests to the API server. Do not give your certificate file to anyone. Never email your certificate in clear text. Always use a secure method to copy your certificate file to your server.

Upgrading your certificate

Your certificate is valid for a maximum of 2 years. When your certificate is near expiry, you will be contacted by Qvalent with details on how to get a new certificate file. You will simply copy the new certificate file over the top of the old certificate file, and restart your system.

Custom integration

Note that this section only gives a general overview of what needs to be done. Specific details are not provided, since they vary depending on the actual technology you use. For this reason, Westpac can provide only limited assistance to customers using custom integration. We recommend that you only undertake a custom integration if you have previous experience with SOAP, HTTPS and digital client certificates.

What the API distribution file contains

The CardsAPI_custom.zip file you received contains the files and folders listed below:

SOAP

Requirements

Your SOAP library must support SOAP 1.1 or higher.

URLs

The URL to use in your code is shown in the table below.

Calling the SOAP function

To make the remote procedure call, you can either use generated code stubs (if your SOAP library supports this), or manually code the remote procedure call. The first option will generally be easier.

Generation of code stubs

• Your SOAP library will generally have some sort of code generation tool which generates code from a WSDL file. For example, the Microsoft .NET tool is named wsdl.exe and the Java tool is named wsimport.exe.
• Use this tool to create code stubs from the WSDL file, then write your software using these stubs.

Manual coding of remote procedure calls

• If your SOAP library does not have a code generation tool, you will have to code the remote procedure calls manually.
• Refer to the XML examples in the next section.

Processing transactions

To process a transaction, your software must send a processRequest XML message containing the request parameters. You will receive a processRequestResponse XML message with the result of the transaction. If you generate code stubs with your SOAP library, the stub will likely expose this as a method called processRequest with the following details:

• An argument called requestParameters which is an array of NameValueParameter objects (each containing a parameter name and value).
• A return type of array of NameValueParameter objects (each containing a parameter name and value).

SOAP request

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

A sample SOAP request XML is shown below:

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
        <ns2:processRequest xmlns:ns2="urn:com.qvalent.quickgateway">
            <requestParameter>
                <name>order.type</name>
                <value>refund </value>
            </requestParameter>
            <requestParameter>
                <name>customer.username</name>
                <value>COMPANYA</value>
            </requestParameter>
            <requestParameter>
                <name>customer.password</name>
                <value>insurance</value>
            </requestParameter>
            <requestParameter>
                <name>customer.merchant</name>
                <value>companya</value>
            </requestParameter>
            <requestParameter>
                <name>card.PAN</name>
                <value>4242424242424242</value>
            </requestParameter>
            <requestParameter>
                <name>card.CVN</name>
                <value>564</value>
            </requestParameter>
            <requestParameter>
                <name>card.expiryYear</name>
                <value>10</value>
            </requestParameter>
            <requestParameter>
                <name>card.expiryMonth</name>
                <value>06</value>
            </requestParameter>
            <requestParameter>
                <name>order.amount</name>
                <value>3400</value>
            </requestParameter>
            <requestParameter>
                <name>customer.orderNumber</name>
                <value>AB1322-refund</value>
            </requestParameter>
            <requestParameter>
                <name>card.currency</name>
                <value>AUD</value>
            </requestParameter>
            <requestParameter>
                <name>order.ECI</name>
                <value>IVR</value>
            </requestParameter>
            <requestParameter>
                <name>customer.originalOrderNumber</name>
                <value>AB1322</value>
            </requestParameter>
        </ns2:processRequest>
    </S:Body>
</S:Envelope>

SOAP response

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

A sample SOAP response XML is shown below.

<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
        <ns2:processRequestResponse xmlns:ns2="urn:com.qvalent.quickgateway">
            <responseParameter>
                <name>response.summaryCode</name>
                <value>0</value>
            </responseParameter>
            <responseParameter>
                <name>response.responseCode</name>
                <value>00</value>
            </responseParameter>
            <responseParameter>
                <name>response.Text</name>
                <value>Transaction processed successfully</value>
            </responseParameter>
            <responseParameter>
                <name>response.RRN</name>
                <value>13238</value>
            </responseParameter>
            <responseParameter>
                <name>response.settlementDate</name>
                <value>20050103</value>
            </responseParameter>
            <responseParameter>
                <name>response.previousTxn</name>
                <value>0</value>
            </responseParameter>
            <responseParameter>
                <name>response.referenceNo</name>
                <value>12922</value>
            </responseParameter>
            <responseParameter>
                <name>response.orderNumber</name>
                <value>1234567</value>
            </responseParameter>
            <responseParameter>
                <name>response.cardSchemeName</name>
                <value>VISA</value>
            </responseParameter>
            <responseParameter>
                <name>response.creditGroup</name>
                <value>VI/BC/MC</value>
            </responseParameter>
            <responseParameter>
                <name>response.transactionDate</name>
                <value>03-JAN-2005 13:24:41</value>
            </responseParameter>
        </ns2:processRequestResponse>
    </S:Body>
</S:Envelope>

Installing the client certificate

• You must use an SSL client certificate to communicate with the API web service. This certificate will be provided to you by your implementation manager. You may not use a certificate from another source (e.g. Verisign).
• Your certificate is generally provided in PKCS12 (or PFX) format. This file format requires a password for the certificate. You will be provided with this certificate password. Do not confuse this password with the password you use to login, or the customer.password parameter required in the card request. Your certificate password will always start with a 'C'.
• A few SOAP libraries require the client certificate file to be in PEM format. If this is the case, please inform your implementation manager to get the certificate in the correct format. The PEM format does not require a password for the certificate.
• Once you have obtained your certificate in the correct format, you must reference it from your SOAP library. The details of this will vary between SOAP libraries, so consult the documentation for your SOAP library.
• Be sure to document the procedure to install the certificate, since the certificate must be replaced every 2 years.

HTTPS POST

Requirements

Your HTTP library must support HTTP 1.0 or 1.1 and SSL 3 or higher.

The URL to use in your code is shown in the table below.

Processing transactions

HTTP request

You must specify the Content-type header as application/x-www-form-urlencoded. You must set the Content-length header correctly.

The body of your HTTP request must contain the request parameters (delimited with an ampersand (&)). See Formatting the request parameters for more information on how the parameters are concatenated together.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

The following is an example HTTPS request:

POST /post/CreditCardAPIReceiver HTTPS/1.0
Content-type: application/x-www-form-urlencoded
Content-length: 328
Host: ccapi.client.support.qvalent.com:443
order.type=refund&customer.username=COMPANYA&customer.password=insurance&customer.merchant=companya&card.PAN=4242424242424242&card.CVN=564&card.expiryYear=10&card.expiryMonth=06&order.amount=3400&customer.orderNumber=AB1322-refund&card.currency=AUD&order.ECI=IVR&customer.originalOrderNumber=AB1322&order.priority=1&message.end=

HTTP response

The body of the HTTP response will contain the response parameters (delimited with a CR LF end of line). See section 4.5 for more information on how the parameters are concatenated together.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

The following is an example HTTPS response:

HTTP/1.1 200 Ok
Content-length: 358
Content-type: text/plain
response.summaryCode=0
response.responseCode=00
response.Text=Transaction processed successfully
response.RRN=13238
response.settlementDate=20050103
response.previousTxn=0
response.referenceNo=12922
response.orderNumber=1234567
response.cardSchemeName=VISA
response.creditGroup=VI/BC/MC
response.transactionDate=03-JAN-2005 13:24:41
response.end

Formatting the request parameters

The request parameters are concatenated together according to the following rules:

• Each parameter is of the form: name=value
• Parameters are separated by ampersand characters (&)

The same format applies regardless of how you connect to the API server. Only use standard ASCII characters in your parameter values. Do not use any of the following special characters in your parameter values:

• Ampersand (&) - ASCII character number 38
• Plus sign (+) - ASCII character number 43
• Percentage sign (%) - ASCII character number 37

Parsing the response parameters

The request parameters will be returned in a concatenated string according to the following rules:

• Each parameter is of the form: name=value
• Parameters are separated by a CR LF end-of-line sequence. Each parameter is on its own line.

Installing the client certificate

• You must use an SSL client certificate to communicate with the API web server. This certificate will be provided to you by your implementation manager. You may not use a certificate from another source (e.g. Verisign).
• Your certificate is generally provided in PKCS12 (or PFX) format. This file format requires a password for the certificate. You will be provided with this certificate password. Do not confuse this password with the password you use to login, or the customer.password parameter required in the card request. Your certificate password will always start with a 'C'.
• A few HTTP libraries require the client certificate file to be in PEM format. If this is the case, please inform your implementation manager to get the certificate in the correct format. The PEM format does not require a password for the certificate.
• Once you have obtained your certificate in the correct format, you must reference it from your HTTP library. The details of this will vary between HTTP libraries, so consult the documentation for your HTTP library.
• Be sure to document the procedure to install the certificate, since the certificate must be replaced every 2 years.

Coding your application

Recommendations

• Log detailed information about each transaction you process through the API. This information will help you diagnose any potential problems you may encounter later. You should not log your customer password, the full card number, the CVN or the expiry date. However, it is safe to log the first 6 digits of the card number and the last 3 (e.g. 411111...111).
• Protect your certificate file. If necessary, restrict the permissions on this file so that only your application can access the certificate.

Handling errors

In the event of a system outage, you may receive a HTTP error code (e.g. 404, 500) or a SOAP fault. Your code should handle this scenario, and treat it the same as if you had received a QI Transaction Incomplete response (which has summary code 2).

See QuickGateway Error Handling and Dealing with QI Responses for details on handling summary code 2 errors.

QuickGateway command-line application

To facilitate connectivity and configuration testing of the QuickGateway API, a sample command line application has been provided. This application helps you check your configuration before developing your own application.

To run the command line program, type the following at your command prompt:

java -cp CardsAPI.jar;bcprov-jdk14-130.jar com.qvalent.ccapi.CardsAPI
"url=https://ccapi.client.support.qvalent.com/post/CreditCardAPIRecei
ver&certificateFile=ccapi.q0&logDirectory=."
"customer.username=USER&customer.password=PASS&customer.merchant=MERC
HANT&order.type=capture&card.PAN=4564710000000004&card.CVN=847&card.e
xpiryYear=09&card.expiryMonth=02&order.amount=1000&customer.orderNumb
er=01&card.currency=AUD&order.ECI=SSL&message.end="

Please note the following points regarding the command above:

• There is a space between the two command-line arguments (i.e. after the logDirectory part and before the username part): ...logDirectory=." "customer.username=...
• You must run the above command in a directory that contains the CardsAPI.jar and bcprov-jdk14-130.jar files and your certificate file (which is named ccapi.q0).
• You should also replace USER with your API username, PASS with your API password and MERCHANT with your merchant identifier provide by Westpac.
• You may need to add proxy information to the initialisation parameters, as per Initialising the CardsAPI object.

After entering the above command, the result of the test transaction will be displayed. If the result contains a result.summaryCode parameter of 0, your test transaction was successful. Note that because this transaction is performed against the test environment, the transaction will not appear on the cardholder statement or your bank account.

For QuickGateway, the parameters in the request and response, see QuickGateway Technical Implementation Guide.

For QuickVault API, the parameters in the request and response, see QuickVault API Registration Technical Implementation Guide.

Troubleshooting

The table below describes some of the common errors you may encounter during your implementation phase, and what to do to resolve them.

Transaction settlement

See Transaction processing and settlement.

Response codes

See Transaction Response Codes.

Glossary