QuickGateway

The QuickGateway solution allows customers to process credit 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 credit card processing features including:

  • Capture - debit funds from a nominated credit card
  • Refund - credit funds to a nominated credit card
  • Pre-authorisations - reserve funds from a nominated credit 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 credit 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.

Solution Overview

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 credit card transaction settlement and a full list of possible response codes.
  5. White-list 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, Connectivity Troubleshooting with Internet Explorer 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 credit 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 credit 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 credit 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 credit 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 also test connectivity using Internet Explorer as described in Connectivity Troubleshooting with Internet Explorer. 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 Credit Cards and Response Codes.

Please note: the response codes operate differently for the NZ 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.

Test Credit Cards

During the testing phase QuickStream will generate a response code based on the credit card number entered. The last 2 digits of the credit card number will map to a particular response code.

  • Any credit card number that ends with a value between 00-89 will result in an approved transaction.
  • Any credit card number that ends with a value between 90-99 will result in a declined transaction.

The table below lists the credit card numbers you can test with and the corresponding response codes are returned.

Visa Logo Visa Test Cards
Last 2 digits of card number Example card number Response code Summary code
00-89 4242424242424242
4111111111111111
4444333322221111
Debit Card: 4041370000456459
08 (Honour with identification) 0 (Transaction Approved)
90 4111111117444490 01 (Refer to card issuer) 1 (Transaction Declined)
91 4111111116444491 04 (Pick-up card) 1 (Transaction Declined)
92 4111111115444492 05 (Do not honour) 1 (Transaction Declined)
93 4111111114444493 91 (Issuer or switch is inoperative) 1 (Transaction Declined)
94 4111111113444494 54 (Expired card) 1 (Transaction Declined)
95 4111111112444495 42 (No universal account) 1 (Transaction Declined)
96 4111111111444496 51 (Not sufficient funds) 1 (Transaction Declined)
97 4111111110444497
Debit Card: 4041370000011197
62 (Restricted card) 1 (Transaction Declined)
98 4111111119444498 43 (Stolen card, pick up) 1 (Transaction Declined)
99 4111111118444499 01 (Refer to card issuer) 1 (Transaction Declined)
Mastercard Logo Mastercard Test Cards
Last 2 digits of card number Example card number Response code Summary code
00-89 5163200000000008
5200000009915957
2224000000031118
Debit Cd. 5188680400000008
08 (Honour with identification) 0 (Transaction Approved)
90 5100000000404390 01 (Refer to card issuer) 1 (Transaction Declined)
91 2229000000002791 04 (Pick-up card) 1 (Transaction Declined)
92 5163200000000792 05 (Do not honour) 1 (Transaction Declined)
93 5500000000101893 91 (Issuer or switch is inoperative) 1 (Transaction Declined)
94 5400000000501994 54 (Expired card) 1 (Transaction Declined)
95 2300000000887995 42 (No universal account) 1 (Transaction Declined)
96 5100000000432896 51 (Not sufficient funds) 1 (Transaction Declined)
97 2710000000011897
Debit Card: 5188683000000097
62 (Restricted card) 1 (Transaction Declined)
98 5200000000022498 43 (Stolen card, pick up) 1 (Transaction Declined)
99 5200000000830999 01 (Refer to card issuer) 1 (Transaction Declined)
Amex Logo Amex Test Cards
Last 2 digits of card number Example card number Response code Summary code
00-89 340000000636513
370000000201048
08 (Honour with identification) 0 (Transaction Approved)
90 340000000075290 01 (Refer to card issuer) 1 (Transaction Declined)
91 370000000024291 04 (Pick-up card) 1 (Transaction Declined)
92 340000000067792 05 (Do not honour) 1 (Transaction Declined)
93 340000000070093 91 (Issuer or switch is inoperative) 1 (Transaction Declined)
94 370000000094294 54 (Expired card) 1 (Transaction Declined)
95 370000000093395 42 (No universal account) 1 (Transaction Declined)
96 340000000089796 51 (Not sufficient funds) 1 (Transaction Declined)
97 370000000092397 62 (Restricted card) 1 (Transaction Declined)
98 370000000064198 43 (Stolen card, pick up) 1 (Transaction Declined)
99 370000000079899 01 (Refer to card issuer) 1 (Transaction Declined)
Diners Logo Diners Test Cards
Last 2 digits of card number Example card number Response code Summary code
00-89 30000000056030
5200000009915957
39000000022686
08 (Honour with identification) 0 (Transaction Approved)
90 39000000000690 01 (Refer to card issuer) 1 (Transaction Declined)
91 38000000008991 04 (Pick-up card) 1 (Transaction Declined)
92 39000000003892 05 (Do not honour) 1 (Transaction Declined)
93 30000000008593 91 (Issuer or switch is inoperative) 1 (Transaction Declined)
94 36000000009694 54 (Expired card) 1 (Transaction Declined)
95 38000000004495 42 (No universal account) 1 (Transaction Declined)
96 39000000004296 51 (Not sufficient funds) 1 (Transaction Declined)
97 30000000006597 62 (Restricted card) 1 (Transaction Declined)
98 36000000003598 43 (Stolen card, pick up) 1 (Transaction Declined)
99 38000000003299 01 (Refer to card issuer) 1 (Transaction Declined)
JCB Logo JCB Test Cards
Example card number Expiry Date CVN Response code Summary code
3530000000000003 10/2025 573 00 (Approved or completed successfully) 0 (Transaction Approved)
3530000000000011 10/2025 573 05 (Do not honour) 1 (Transaction Declined)
UnionPay Logo UnionPay Test Cards
Example card number Expiry Date CVN Response code Summary code
6250947000000014 12/2033 123 08 (Honor with identification) 0 (Transaction Approved)

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

Application Programming Interface

The QuickGateway API provides a real-time, synchronous interface to execute credit card transactions. That is, only one method call is needed to request processing against a credit 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 credit 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:

Message Flows

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 credit card request parameters. 5. The API server contacts the issuing bank and requests authorisation for the credit 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 credit 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

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

Parameter Name Value Description Required
order.type See Description for valid order types The type of processing required:
  • capture
  • refund
  • query
  • echo
  • preauth
  • captureWithoutAuth
  • reversal
  • accountVerification
  • preauthCancellation
Yes
customer.username At most 32 chars The username that identifies your company. Yes
customer.password At most 32 chars The password provided to you with your username. Yes
customer.merchant At most 32 chars The merchant identifier to use for the transaction. This allows you to have multiple merchant accounts. Values for this field will be provided to you by Westpac. Yes
card.PAN At most 19 chars The credit card number Required for capture / preauth, optional for captureWithoutAuth / refund / reversal
card.CVN 4 digits The card verification number. This is a 3 or 4 digit code that provides extra security for online payments. For Visa, Mastercard, Diners and Union Pay, this is the last 3 digits on the back of the signature panel. For Amex, this is the 4 digit number on the front of the card above the embossed card number. Under no circumstances should the CVN be stored in any system. No
card.expiryYear 2 digits The year the card expires Required for capture / preauth, optional for captureWithoutAuth / refund / reversal
card.expiryMonth 2 digits The month the card expires Required for capture / preauth, optional for captureWithoutAuth / refund / reversal
card.cardHolderName At most 60 chars The name on the credit card being processed. Note this is for information only - the card holder name will not be checked by the card issuer. Note: Do not use any of the following characters in the card holder name: & % No
order.amount At most 12 digits The amount to apply to the card based on the order.type in cents. This amount should be a positive value for all order types. For example, enter 1295 for an amount of “$12.95”. Limits may be applied to these amounts for security purposes (see Limits). Required for capture / preauth, optional for captureWithoutAuth / refund / reversal
customer.orderNumber At most 40 chars A unique customer generated number for this transaction. This number can be used at a later date to query a transaction. This is your own internal tracking number for this transaction, which can also be used in the QuickStream search screens. This number must be used by your systems to prevent duplicate transaction processing.

Note 1: This must be unique for a given merchant id.
Note 2: Do not use any of the following characters in your order number: & %
Only for capture / refund / query
card.currency 3 chars The currency for the transaction amount. If no currency is specified, your pre-configured default currency is used. Optional for capture / refund
order.ECI 3 chars or 1 digit The Electronic Commerce Indicator (ECI) to apply to this card transaction. Please refer to ECI for more details on this parameter. Only for capture / refund
customer.originalOrderNumber At most 40 chars This field is used to reference a previous transaction in the system when performing a refund, reversal or captureWithoutAuth.
This field is used when performing a Refund to link the refund with the original Capture. See Refund Orders.
Also required when performing a reversal of a preauth/ capture. In this case, this parameter must be populated with the original order number of the preauth / capture transaction. See Reversals.
Also used when capturing a previous preauth. In this case, this parameter must be populated with the original order number of the preauth transaction. See Pre-Authorisations.

Note that this field was previously named customer.captureOrderNumber
Required for refund / reversal / captureWithoutAuth unless customer.originalReferenceNo is specified.
customer.originalReferenceNo At most 20 digits When performing a refund, you can specify the reference number of the original transaction you wish to refund. This the value returned in the response.referenceNo parameter. In this case, you do not have to specify the customer.originalOrderNumber parameter. This also allows you to refund transactions made through other QuickStream channels, such as QuickWeb or QuickBatch.

Also can be used when capturing a previous preauth. In this case, this parameter must be populated with the reference number of the preauth transaction. This also allows you to capture preauths made through other QuickStream channels, such as QuickWeb or QuickBatch.
Optional for refund / captureWithoutAuth. Only one of customer.originalOrderNumber and customer.originalReferenceNo needs to be used.
order.authId 6 chars The authorisation Id returned from the corresponding preauth transaction.
Note that this field may contain spaces, so be careful not to trim spaces from this field.
Optional for captureWithoutAuth, must not be present for other transaction types.
customer.customerReferenceNumber At most 20 chars The customer reference number to record against this transaction. This field will appear in any transaction reports that you receive. Only letters, numbers, dashes, underscores and full-stops are accepted in this field.
This field is used to identify the customer’s account if you are using pre-registered accounts. See Pre-registered Card-holder Accounts.
No
customer.preregistrationCode At most 20 chars This field is used to identify the customer’s account if you are using pre-registered accounts. Can be used as well as customerReferenceNumber or instead of it. See Pre-registered Card-holder Accounts. No
order.xid 20 chars The transaction ID (XID) value for the 3D Secure authentication for this transaction. No
order.cavv 28 chars or 32 chars The base 64 encoded Cardholder Authentication Verification Value (CAVV) for the 3D Secure authentication for this transaction. This value is returned from your Merchant Plugin Interface (MPI) software.
order.ipAddress At most 15 chars The IP address of the card holder performing the transaction (if the transaction is an internet payment). This field must not be populated for mail, telephone or recurring payments. This information is used in fraud checking if you have opted for the Fraud Guard module. E.g. 10.101.101.101 Yes if the Fraud Guard module is used, or if order.ECI is SSL, SWP, 5, 6 or 7.
order.authType At most 20 chars Available for Visa and Mastercard only. For order.type=preauth, one of:
  • INITIAL - A new preauth.
  • INCREMENTAL - Top-up a preauth. Available for Visa and Mastercard only.
  • EXTENSION - Extend a preauth to the maximum time frame supported by the card scheme. At the time of writing this is 30 days but may differ without notice. Available for Mastercard only.
  • REAUTHORISATION - Reauthorise a preauth that has expired after the maximum time frame supported by the card scheme. At the time of writing this is 30 days but may differ without notice. Available for Visa only.
  • blank - Same as INITIAL
You must provide the original order number in customer.originalOrderNumber for INCREMENTAL, EXTENSION and REAUTHORISATION preauth types. See Pre-Authorisations
Yes for preauth.
order.cancellationType At most 20 chars Available for Visa and Mastercard only. For order.type = preauthCancellation, one of:
  • PARTIAL - Partially cancel some of the outstanding amount of an existing preauth.
  • FULL - Fully cancel the entire outstanding amount of an existing preauth.
You must provide the order number of the initial preauth in customer.originalOrderNumber. See Pre-Authorisations
Yes for preauthCancellation.
card.posEntryMode At most 20 chars Available for Visa and Mastercard only. One of:
  • MANUAL - The card number was manually entered into the system by the cardholder or the merchant.
  • STORED_CREDENTIAL - The card number is stored by the merchant to process future purchases for a cardholder.
Defaults to MANUAL if not specified.
No
card.storedCredentialUsage At most 20 chars Available for Visa only. One of:
  • INITIAL_STORAGE - The merchant is storing the card number for the first time.
  • RECURRING - The stored card number is being used for a recurring transaction (which are processed at fixed, regular intervals not to exceed one year between transactions).
  • UNSCHEDULED - The stored card number is being used for a merchant-initiated unscheduled transaction (which does not occur on a scheduled or regularly occurring transaction date). The transaction is initiated by the merchant without active participation of the cardholder.
Only applicable for order.type values capture, preauth and captureWithoutAuth. See Stored Credential Transactions
No
order.authTraceId String (At most 15 characters) Available for Visa only. Used to identify the previous transaction for the cardholder when using a stored credential. Yes if card.storedCredentialUsage is RECURRING or UNSCHEDULED
order.debtRepayment Boolean Available for Visa only.true when the transaction is part of a debt repayment arragement. No
customer.merchantVerificationValue 10 digits Available for Visa only. The Merchant Verification Value assigned to the merchant by Visa. No
customer.walletId 3 digits Available for MasterCard only. The Wallet Id assigned to the merchant by MasterCard. No
message.end No value Must be the last property in the message Yes

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

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

Parameter Name Value Description Always
response.summaryCode number The summary code in numeric format:
0 - Approved
1 - Declined
2 - Erred
3 - Rejected
Yes
response.responseCode 2 chars The AS2805 response code of the transaction. See Response Codes Yes
response.text String (At most 200 characters) A textual description of the transactions response or failure. Yes
response.RRN String (At most 12 characters) The retrieval reference number provided by the banking network. See RRN. May be returned for approved transactions
response.settlementDate yyyymmdd The settlement date for the transaction. See Settlement Date. May be returned for most approved or declined transactions.
response.previousTxn number Indicates if transaction response is returned based on previous transaction response for same order number or if this is a new order (see PreviousTxn).
0 = new transaction response
1 = previous transaction response
Only if transaction has been processed (either now or previously)
response.referenceNo String (At most 32 characters) Internal QuickStream reference number for transaction. Only if transaction is successful
response.orderNumber String Order number as supplied in transaction request. Only if supplied in transaction request.
response.cardSchemeName String (At most 20 characters) This is the card scheme of the card used in the transaction (see Card Scheme vs Credit Group for more details).
Values returned are:
  • AMEX
  • DINERS
  • MASTERCARD
  • VISA
  • UNIONPAY
  • JCB
Only if card scheme is known
response.creditGroup String (At most 20 characters) This is the card scheme grouping of the card used in the transaction (see Card Scheme vs Credit Group for more details).
Values returned are:
  • AMEX
  • DINERS
  • VI/BC/MC
Only if card scheme is known
response.transactionDate dd-mmm-yyyy hh24:mi:ss The date/time the transaction occured. Only if transaction passes initial parameter checks.
response.authId String (At most 6 characters) The authorisation Id returned from the issuing bank for the preauth transactions. This value may be passed in with any subsequent captureWithoutAuth transaction for the same card. Only for approved preauth transactions
response.cvnResponse String (1 character) The result of CVN checking performed by the card issuer. Expected values are:
  • M - Matched
  • N - Not matched
  • P - Not processed
  • S - Suspicious
Note that some card issuers may occasionally return other values than those listed above. The meaning of such values is undefined.
Only if received from card issuer
response.traceCode String (At most 32 characters) A unique trace code from the payment gateway. Only if received from the payment gateway. For example, Westpac transactions in Australia will always have an associated trace code.
response.authTraceId String (At most 15 characters) Returned by Visa and Mastercard to identify the lifecycle of a preauth or purchase. In most cases you can ignore this field. No
response.end No value Must be the last property in the message Yes

HTTPS POST Example

Request Example

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

    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=

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

Further Details

The following section provides further details on the request and response parameters.

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 - credit 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 3rd 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 API server at varying levels depending on the parameters supplied. If you include order.type=echo with:

  • No other parameters, a response code of 00 will be returned if the QuickStream 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.
  • Your identification details (customer.username, customer.password & customer.merchant) but no currency, your community’s default currency (eg AUD or NZD) will be used. A 00 response returned if your identification details are valid, your IP address is registered and the payment gateway for the default currency is available. Otherwise, an appropriate error response is returned.
  • Your identification details (customer.username, customer.password & customer.merchant) and a currency is supplied, a 00 response is returned if your identification details are valid, your IP address is registered and the payment gateway for the supplied currency is available. Otherwise an appropriate error response is returned.

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.

ECI Value Description
CCT Call Centre Transaction
IVR IVR Transaction
MTO MOTO Transaction
SSL Channel Encrypted Transaction (SSL or other)
REC Recurring payment1
INS Instalment payment2
5 3D Secure transaction. This is the value returned from your MPI (Merchant Plugin Interface) software for 3D Secure transactions3
6 As above.
7 As above.
  • 1 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.
  • 2 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.
  • 3 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, credit 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 credit 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 credit 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.

Summary Code Description Recommended System Action
0 Transaction Approved Transaction is successful. No further action required.
1 Transaction Declined Transaction has been declined by the financial institution. Some of the more common reasons are invalid credit card details (QQ), expired card (54) or insufficient funds (51).
In many cases, the problem can be addressed by either:
  • Carefully checking the card details and correcting any mistakes before retrying under a new customer.orderNumber; or
  • Retrying the transaction under a new orderNumber with an alternative card of the customer.
The reason for the decline may not always be obvious from the detailed response code eg Do Not Honour (05) and may require offline follow up with the financial institution that issued the card.
2 Transaction Erred Transaction is of an unknown status. Please refer to section below for details on how to handle this status.
3 Transaction Rejected Transaction request has been rejected by the Westpac QuickGateway API, often due to invalid parameters or system configuration. This is similar to the Transaction Declined (Summary Code of 1) in terms of error handling. Refer to the detailed response code and either:
  • Correct the transaction details if required and retry under a new customer.orderNumber; or
  • Handle offline through Westpac/Qvalent CustomerCare if unable to be resolved.

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 credit 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:

cardScheme creditGroup Acquiring Bank
AMEX AMEX American Express
DINERS DINERS Diners Club
MASTERCARD VI/BC/MC Westpac
VISA VI/BC/MC Westpac
UNIONPAY VI/BC/MC Westpac

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.

Advanced QuickGateway API Features

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 credit 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 Preauth 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 credit 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
Historical Note

In previous versions of the API, matching of the “preauth” transaction depended on the order.authId parameter in the captureWithoutAuth. This matching depends on the “customer.originalOrderNumber” parameter (as described above). This is now the preferred method since it means that you do not have to store the credit card details. You should upgrade to the new method where possible.

The old method of performing a captureWithoutAuth transaction is still accepted by the system. This old method uses the following request parameters:

  • order.type = captureWithoutAuth
  • card.PAN, card.expiryYear, card.expiryMonth - must be supplied and must match the details given on the original transaction.
  • 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 - the value from the response.authId parameter in the response to the original pre-authorisation transaction
  • order.amount - the amount to charge the card-holder
  • customer.originalOrderNumber - not present

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 can include 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 cards.

Performing an Initial Stored Credential Transaction

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

  • order.type = purchase
  • card.posEntryMode = MANUAL
  • card.storedCredentialUsage = INITIAL_STORAGE
  • All other fields as normal. See API Request.

Example request

order.type=purchase
customer.orderNumber=TEST123
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=SSL
card.PAN=4564710000000004
card.expiryMonth=02
card.expiryYear=19
card.posEntryMode=MANUAL
card.storedCredentialUsage=INITIAL_STORAGE

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=VISA
response.creditGroup=VI/BC/MC
response.previousTxn=0
response.traceCode=752471
response.authTraceId=g9hs5s8sfphdslm
response.end
Performing a Recurring Stored Credential Transaction

Recurring transactions are processed at fixed, regular intervals not to exceed one year between transactions. To perform a recurring transaction with a stored credential, use the following request parameters:

  • order.type = purchase
  • Card details can be specified using card.PAN, card.expiryMonth and card.expiryYear parameters, or looked up as per Pre-registered Card-holder Accounts.
  • order.ECI = REC
  • card.posEntryMode = STORED_CREDENTIAL
  • card.storedCredentialUsage = RECURRING
  • order.authTraceId = The value returned in the response.authTraceId field for the previous transaction using this stored credential.
  • All other fields as normal. See API Request.

Example request

order.type=purchase
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 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
Performing an Unscheduled Stored Credential Transaction

Unscheduled stored credential transactions do not occur on a scheduled or regularly occurring transaction date. These transactions are initiated by the merchant without active participation of the cardholder. To perform an unscheduled stored credential transaction, use the following request parameters:

  • order.type = purchase
  • Card details can be specified using card.PAN, card.expiryMonth and card.expiryYear parameters, or looked up as per Pre-registered Card-holder Accounts.
  • order.ECI = MTO
  • card.posEntryMode = STORED_CREDENTIAL
  • card.storedCredentialUsage = UNSCHEDULED
  • order.authTraceId = The value returned in the response.authTraceId field for the previous transaction using this stored credential.
  • All other fields as normal. See API Request.

Example request

order.type=purchase
customer.orderNumber=TEST1232
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=MTO
card.PAN=4564710000000004
card.expiryMonth=02
card.expiryYear=19
card.posEntryMode=STORED_CREDENTIAL
card.storedCredentialUsage=UNSCHEDULED
order.authTraceId=g9hs5s8sfphdslm

Example successful response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902051
response.orderNumber=TEST1232
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
Performing a Cardholder-Initiated Stored Credential Transaction

To perform a cardholder-initiated stored credential transaction, use the following request parameters:

  • order.type = purchase
  • Card details can be specified using card.PAN, card.expiryMonth and card.expiryYear parameters, or looked up as per Pre-registered Card-holder Accounts.
  • order.ECI = MTO
  • card.posEntryMode = STORED_CREDENTIAL
  • card.storedCredentialUsage = not present
  • order.authTraceId = The value returned in the response.authTraceId field for the previous transaction using this stored credential.
  • All other fields as normal. See API Request.

Example request

order.type=purchase
customer.orderNumber=TEST1232
customer.username=TEST
customer.password=TEST
customer.merchant=TEST
order.ECI=MTO
card.PAN=4564710000000004
card.expiryMonth=02
card.expiryYear=19
card.posEntryMode=STORED_CREDENTIAL
order.authTraceId=g9hs5s8sfphdslm

Example successful response

response.summaryCode=0
response.responseCode=08
response.text=Honour with identification
response.referenceNo=701902051
response.orderNumber=TEST1232
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

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.

Situation Response Received
Original transaction not found, i.e. no transaction with the specified capture order number exists in the system. 21 - no action taken
Original transaction was not approved, i.e. the original transaction had a summary code other than 0. 21 - no action taken
Original transaction is not reversible, i.e. a reversal was submitted for a transaction that was not a capture, captureWithoutAuth, refund or preauth. 12 - invalid reversal
Reversal details do not match original transaction details, i.e. different card details were specified in the original transaction and the reversal 12 - invalid reversal
Current Settlement date is not the same as the original transaction, i.e. the original transaction’s settlement date is different from the current system settlement date 12 - invalid transaction
Original transaction was already reversed, i.e. a reversal was submitted for a transaction that had previously been reversed 00 - approved or completed successfully
Reversal accepted, i.e. a valid reversal was submitted and processed 00 - approved or completed successfully
Error occurred during processing QE - Internal Error
Communications error occurred between client and Qvalent QI/QX - Incomplete or Network error

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 credit 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 Internet Explorer) 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 http://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.

Connectivity Troubleshooting with Internet Explorer

This section describes how to use Internet Explorer to perform connectivity troubleshooting. The steps described in this section can be used to isolate problems if your application is unable to connect to the QuickGateway API server. These instructions were written using Internet Explorer 5.5.

In order to perform these steps, you will require the HTML Client (a file named CCAPI_support_tester.htm). This is available on request.

  1. Log in to the server that will be making the API call as the same user that your application will run under.
  2. Save the file as a CCAPI_support_tester.htm file on the machine.
  3. Close any existing Internet Explorer windows
  4. Open the saved .HTM file in Internet Explorer.
  5. Enter the details of the API call that you wish to perform. Ensure that the username, password and merchant are correct. For the purposes of this test, the default details will usually suffice (you can use any credit card number e.g. 4242424242424242 and the amount must be in cents eg 100 = $1.00)
  6. Click “Make Payment”. This will cause IE to do a POST to the QuickGateway API server.
  7. If you receive “The page can not be displayed” or a DNS error then your server is unable to make a network connection to the QuickGateway API server. Check your proxy, DNS and firewall settings.
  8. Internet Explorer should prompt, “The Web site you want to review requests identification. Select the certificate to use when connecting.” A list of certificates will be displayed. Select your client certificate. This is the private key used to digitally sign the request from your server to the QuickGateway API server. It is validated against your server’s public key which is held on the QuickGateway API server. If it does not appear in the list it is not installed correctly.
  9. The QuickGateway API should respond to the QuickGateway API request. This will look like something like this: -
response.summaryCode=0 response.responseCode=00 response.text=Approved or completed successfully response.referenceNo=8499901 response.orderNumber= X12345112 response.RRN=231232 response.settlementDate=20051216 response.previousTxn=0 response.paymentInstrumentId=1 response.cardSchemeName=VISA response.creditGroup=VI/BC/MC response.transactionDate=16-Dec-2005 14:12:11 response.end

If the QuickGateway API works correctly from Internet Explorer, but your application does not work correctly, check the following :-

  • The proxy server settings used by your application are identical to those specified in Internet Explorer
  • The POST URL used by your application is identical to those specified on the web page (NB. The web page uses the HTTPS POST interface, a different URL applies if you are using the SOAP interface).
  • The client certificate (your private key) you selected using Internet Explorer is being used when sending the POST

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

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

Parameter Name Value Description (for a Payment) Required
customer.merchantName At most 22 characters Must be in the format AggregatorName*SubMerchantName.
For example:
  • AggregatorName is Jane's Transactions, abbreviated to JAT.
  • SubMerchantName name is Jill's Bikes.
  • The value of this field may be JAT*JillsBikes.
AggregatorName may be an abbreviation and must be agreed with Westpac during your implementation.
Yes
customer.merchantStreetAddress At most 48 characters The street address of the sub-merchant’s trading address.
It is a scheme requirement to populate the street address as part of the payment. Westpac does not hold the street address information for sub-merchants and it will not appear on the cardholder’s or merchant’s statement.
Must contain the street address lines only:
  • Include the city or suburb in customer.merchantLocation.
  • Include the state in customer.merchantState.
  • Include the country in customer.merchantCountry.
  • Include the post code in customer.merchantPostCode.
Yes
customer.merchantLocation At most 13 characters The city or suburb of the sub-merchant’s trading address. Yes
customer.merchantState At most 3 characters The state of the sub-merchant’s trading address. One of:
  • NSW
  • ACT
  • VIC
  • QLD
  • NT
  • SA
  • WA
  • TAS
Yes
customer.merchantCountry At most 2 characters Must be set to AU.
The sub-merchant must be registered in Australia and have a presence and process payments within Australia.
Yes
customer.merchantPostCode At most 4 characters The postal code of the sub-merchant’s trading address. Yes
customer.subMerchantId At most 15 characters A unique identifier for your sub-merchant. The aggregator allocates the sub-merchant identifier. Westpac does not allocate this value. Yes for aggregators, not present for Staged DWOs

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

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:

File/Folder Description
bcprov-jdk14-130.jar The Bouncy Castle JCE provider used to perform encryption of card transactions. This JAR file must be in your application’s class path.
CardsAPI.jar The QuickGateway API for Java. This JAR file contains the com.qvalent.ccapi.CardsAPI class and must be in your application’s class path.
readme.txt The quick start documentation file with simple instructions for using the example code.
version.txt The file containing the version of the API that you are using.
doc/ The folder containing the Javadoc for the Java API.
examples/ The folder containing the example programs demonstrating the use of the CardsAPI object.
examples/java/ The folder containing the example program which demonstrates the use of the CardsAPI object from a command line application.
examples/jsp/ The folder containing the example program which demonstrates the use of the CardsAPI object from a JSP web application.

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:

Name Description Required
url The URL of the QuickGateway API service. Use https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver for testing and https://ccapi.client.qvalent.com/post/CreditCardAPIReceiver for production Yes
logDirectory The directory to place the log files in. If the directory does not exist, it will be created. Yes
certificateFile The location of the file containing your certificate. Use a fully qualified file name including the drive letter and full directory information. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future. Yes
proxyHost The host name of the proxy server that your application must connect through to access the Qvalent API server. Do not include this parameter if you do not require a proxy server. No
proxyPort The port number the proxy server listens on. Do not include this parameter if you do not require a proxy server. No
proxyUser The username required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No
proxyPassword The password required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No
Processing transactions

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

Method: processCreditCard

Description: Main credit 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 theCardsAPI 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.

Error Description Suggested Resolution
NoClassDefFoundError: com/qvalent/ccapi/CardsAPI Ensure that the CardsAPI.jar file is in your class path.
Could not load the security provider Ensure that bcprov-jdk14-130.jar is in your class path.
Could not open certificate file Ensure that the certificateFile initialisation parameter is set correctly for the initialise call (i.e. that the value is the location of the certificate file that you have downloaded). Also, ensure that your application is allowed to read this file.
Specified log directory is not a directory Ensure that the logDirectory initialisation parameter is set correctly for the initialise call. Also, ensure that the specified directory is a directory (not a file), and that your application is allowed to write to this directory.
response.responseCode = QH (Incorrect Customer Username or Password) Ensure that you have used the correct username and password in the request parameters (i.e. ensure that you have replaced USER and PASS in the example code).
response.responseCode = QK (Unknown Customer Merchant) Ensure that the customer.merchant request parameter is set to the correct value.
response.responseCode = QJ (Invalid Customer Certificate) Ensure that you have used the correct certificate file in the ‘initialise’ call (i.e. the 'certificateFile’ initialisation parameter points to the correct certificate file).
response.responseCode = QU (Unknown Customer IP Address) The IP address listed in the error message should be emailed to your implementation manager for configuration.
response.responseCode = QI (Transaction Incomplete) Check the log file for more information. The most likely cause is that you have not specified the proxy information correctly. Another common cause is that your firewall is not configured to allow outbound SSL connections on port 443.
response.responseCode = QX response.text=TLS version TLSv1 is not strong encryption TLSv1.2 must be used. Prior to calling the QuickGateway, force TLS v1.2.

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

File/Folder Description
CardsAPI.dll The QuickGateway API library. You must install this file on each server that will use the API
CardsAPITest.exe The API connectivity test program
readme.txt The quick start documentation file with simple instructions for using the example code.
version.txt The file containing the version of the API that you are using.
doc/ The folder containing the NDoc for the .Net API.
examples/ The folder containing the example program which demonstrates the use of the CardsAPI object from an ASP.Net web application.

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:

Name Description Required
url The URL of the QuickGateway API service. Use https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver for testing and https://ccapi.client.qvalent.com/post/CreditCardAPIReceiver for production Yes
logDirectory The directory to place the log files in. If the directory does not exist, it will be created. Yes
certificateFile The location of the file containing your certificate. Use a fully qualified file name including the drive letter and full directory information. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future. Yes
proxyHost The host name of the proxy server that your application must connect through to access the Qvalent API server. Do not include this parameter if you do not require a proxy server. No
proxyPort The port number the proxy server listens on. Do not include this parameter if you do not require a proxy server. No
proxyUser The username required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No
proxyPassword The password required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No

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

Error Description Suggested Resolution
ActiveX component can’t create object: Qvalent.CCAPI.CardsAPI Ensure that the register.cmd file has been run on your web server and the message Types registered successfully was displayed.
Certificate from file does not exist or Certificate file format error Ensure that the ‘certificateFile’ initialisation parameter is set correctly for the Initialise call (i.e. that the value is the location of the certificate file that you have downloaded). Also, ensure that your application is allowed to read this file.
Specified log directory is not a directory Ensure that the logDirectory initialisation parameter is set correctly for the initialise call. Also, ensure that the specified directory is a directory (not a file), and that your application is allowed to write to this directory.
SecurityException Check the permissions that are granted to your application. The API client requires the following permissions:
  • SecurityPermission with the ControlPrincipal flag
  • FileIOPermission on the log directory and the certificate file
  • WebPermission for the URIs https://ccapi\.client\.support\.qvalent\.com/.* and https://ccapi\.client\.qvalent\.com/.*
Server object error 'ASP 0177 : 8000ffff' Server.CreateObject Failed See 8000ffff
response.responseCode = QH (Incorrect Customer Username or Password) Ensure that you have used the correct username and password in the request parameters (i.e. ensure that you have replaced USER and PASS in the example code).
response.responseCode = QK (Unknown Customer Merchant) Ensure that the customer.merchant request parameter is set to the correct value.
response.responseCode = QJ (Invalid Customer Certificate) Ensure that you have used the correct certificate file in the 'initialise’ call (i.e. the 'certificateFile’ initialisation parameter points to the correct certificate file).
response.responseCode = QU (Unknown Customer IP Address) The IP address listed in the error message should be emailed to your implementation manager for configuration.
response.responseCode = QI (Transaction Incomplete) Check the log file for more information. The most likely cause is that you have not specified the proxy information correctly. Another common cause is that your firewall is not configured to allow outbound SSL connections on port 443.
response.responseCode = QX response.text=TLS version TLSv1 is not strong encryption TLSv1.2 must be used. Prior to calling the QuickGateway, force TLS v1.2: ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; This change is per application domain and will affect other HTTPS connections.
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:

File/Folder Description
Qvalent_CardsAPI.php The QuickGateway API for PHP. This source file contains the Qvalent_CardsAPI class you will call from your application code.
cacerts.crt The Certificate Authority file that you must reference when calling the initialise method.
readme.txt The quick start documentation file with simple instructions for using the example code.
version.txt The file containing the version of the API that you are using.
examples/ The folder containing the example programs demonstrating the use of the Qvalent_CardsAPI object.

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:

Name Description Required
url The URL of the QuickGateway API service. Use https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver for testing and https://ccapi.client.qvalent.com/post/CreditCardAPIReceiver for production Yes
logDirectory The directory to place the log files in. If the directory does not exist, it will be created. Yes
certificateFile The location of the file containing your certificate. Use a fully qualified file name including the drive letter and full directory information. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future. Yes
caFile The Certificate Authority file containing the list of trusted certificates. Set this to the location of the cacerts.crt file from the API distribution. Yes
proxyHost The host name of the proxy server that your application must connect through to access the Qvalent API server. Do not include this parameter if you do not require a proxy server. No
proxyPort The port number the proxy server listens on. Do not include this parameter if you do not require a proxy server. No
proxyUser The username required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No
proxyPassword The password required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No
Processing transactions

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

Method: processCreditCard

Description: Main credit 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.

Error Description Suggested Resolution
Class 'Qvalent_CardsAPI' not found Ensure that the Qvalent_CardsAPI.php file is in your class path.
Certificate Authority file does not exist Ensure that the caFile initialisation parameter is set correctly for the initialise call. Also, ensure that your application is allowed to read this file.
Certificate file does not exist Ensure that the certificateFile initialisation parameter is set correctly for the initialise call (i.e. that the value is the location of the certificate file that you have downloaded). Also, ensure that your application is allowed to read this file.
Cannot use logging directory Ensure that the logDirectory initialisation parameter is set correctly for the initialise call. Also, ensure that the specified directory is a directory (not a file), and that your application is allowed to write to this directory.
[function.fopen]: failed to open stream: Permission denied Ensure that your application is permitted to write to the directory specified in the logDirectory initialisation parameter.
Call to undefined function curl_init() Check your installation of the libcurl package for PHP. See http://www.php.net/manual/en/ref.curl.php
PHP Startup: Unable to load dynamic library 'c:\php\ext\php_curl.dll' - The specified module could not be found Check your installation of the libcurl package for PHP. See http://www.php.net/manual/en/ref.curl.php
Error Number: 58, Description: unable to use client certificate (no key found or wrong pass phrase?) Check your installation of the libcurl package for PHP. See http://www.php.net/manual/en/ref.curl.php. Ensure that the certificateFile initialisation parameter is set correctly for the initialise call (i.e. that the value is the full file-path to the ccapi.pem certificate file that you downloaded). Also, ensure that your application is allowed to read this file.
Error Number: 6, Description: Couldn't resolve host 'ccapi.client.support.qvalent.com' Check your proxy configuration.
response.responseCode = QH (Incorrect Customer Username or Password) Ensure that you have used the correct username and password in the request parameters (i.e. ensure that you have replaced USER and PASS in the example code).
response.responseCode = QK (Unknown Customer Merchant) Ensure that the customer.merchant request parameter is set to the correct value.
response.responseCode = QJ (Invalid Customer Certificate) Ensure that you have used the correct certificate file in the ‘initialise’ call (i.e. the 'certificateFile’ initialisation parameter points to the correct certificate file).
response.responseCode = QU (Unknown Customer IP Address) The IP address listed in the error message should be emailed to your implementation manager for configuration.
response.responseCode = QI (Transaction Incomplete) Check the log file for more information. The most likely cause is that you have not specified the proxy information correctly. Another common cause is that your firewall is not configured to allow outbound SSL connections on port 443.
response.responseCode = QX response.text=TLS version TLSv1 is not strong encryption TLSv1.2 must be used. Prior to calling the QuickGateway, force TLS v1.2.

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:

File/Folder Description
CardsAPI.dll The QuickGateway API library. You must install this file on each server that will use the API
CardsAPITest.exe The API connectivity test program
register.cmd The command file to register CardsAPI.dll for COM Interop.
unregister.cmd The command file to de-register CardsAPI.dll for COM Interop.
readme.txt The quick start documentation file with simple instructions for using the example code.
version.txt The file containing the version of the API that you are using.
doc/ The folder containing the NDoc for the COM API.
examples/ The folder containing the example program which demonstrates the use of the CardsAPI object from an ASP web application.

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:

Name Description Required
url The URL of the QuickGateway API service. Use https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver for testing and https://ccapi.client.qvalent.com/post/CreditCardAPIReceiver for production Yes
logDirectory The directory to place the log files in. If the directory does not exist, it will be created. Yes
certificateFile The location of the file containing your certificate. Use a fully qualified file name including the drive letter and full directory information. Make sure you document the location of the certificate file to facilitate easy upgrading of your certificate in the future. Yes
proxyHost The host name of the proxy server that your application must connect through to access the Qvalent API server. Do not include this parameter if you do not require a proxy server. No
proxyPort The port number the proxy server listens on. Do not include this parameter if you do not require a proxy server. No
proxyUser The username required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No
proxyPassword The password required to connect to the proxy server. Do not include this parameter if you do not require a proxy server. Do not include this parameter if your proxy server does not require authentication. No

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

Error Description Suggested Resolution
ActiveX component can’t create object: Qvalent.CCAPI.CardsAPI Ensure that the register.cmd file has been run on your web server and the message Types registered successfully was displayed.
Certificate from file does not exist or Certificate file format error Ensure that the ‘certificateFile’ initialisation parameter is set correctly for the Initialise call (i.e. that the value is the location of the certificate file that you have downloaded). Also, ensure that your application is allowed to read this file.
Specified log directory is not a directory Ensure that the logDirectory initialisation parameter is set correctly for the initialise call. Also, ensure that the specified directory is a directory (not a file), and that your application is allowed to write to this directory.
SecurityException Check the permissions that are granted to your application. The API client requires the following permissions:
  • SecurityPermission with the ControlPrincipal flag
  • FileIOPermission on the log directory and the certificate file
  • WebPermission for the URIs https://ccapi\.client\.support\.qvalent\.com/.* and https://ccapi\.client\.qvalent\.com/.*
Server object error 'ASP 0177 : 8000ffff' Server.CreateObject Failed See 8000ffff
response.responseCode = QH (Incorrect Customer Username or Password) Ensure that you have used the correct username and password in the request parameters (i.e. ensure that you have replaced USER and PASS in the example code).
response.responseCode = QK (Unknown Customer Merchant) Ensure that the customer.merchant request parameter is set to the correct value.
response.responseCode = QJ (Invalid Customer Certificate) Ensure that you have used the correct certificate file in the 'initialise’ call (i.e. the 'certificateFile’ initialisation parameter points to the correct certificate file).
response.responseCode = QU (Unknown Customer IP Address) The IP address listed in the error message should be emailed to your implementation manager for configuration.
response.responseCode = QI (Transaction Incomplete) Check the log file for more information. The most likely cause is that you have not specified the proxy information correctly. Another common cause is that your firewall is not configured to allow outbound SSL connections on port 443.
response.responseCode = QX response.text=TLS version TLSv1 is not strong encryption TLSv1.2 must be used. Prior to calling the QuickGateway, force TLS v1.2: ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; This change is per application domain and will affect other HTTPS connections.
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:

File/Folder Description
CardsAPIDocumentLiteralService.wsdl The Web Services Description Language (WSDL) file describing the CardsAPI web service. Use this file to generate code stubs for your application.
CardsAPIDocumentLiteralService_schema1.xsd The XML Schema document that describes the message formats used in the WSDL.
readme.txt The quick start documentation file with simple instructions for using the provided WSDL file.
version.txt The file containing the version of the API that you are using.

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.

Environment URL
Test https://ccapi.client.support.qvalent.com/webservice/CardsAPIDocumentLiteral
Production https://ccapi.client.qvalent.com/webservice/CardsAPIDocumentLiteral
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 credit 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.

Environment URL
Test https://ccapi.client.support.qvalent.com/post/CreditCardAPIReceiver
Production https://ccapi.client.qvalent.com/post/CreditCardAPIReceiver
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 credit 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 credit 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.

Troubleshooting

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

Error Description Suggested Resolution
Network error or HTTP error code Check the URL you have specified in your code. Also check that your proxy information is correctly specified and that your firewall is configured to allow outbound SSL connections on port 443.
Certificate error or SSL error Ensure that you have referenced the certificate file correctly for your HTTP or SOAP library. Ensure that your application is allowed to read this file. Also, check your HTTP or SOAP library’s documentation about what file format is required.
response.responseCode = QH (Incorrect Customer Username or Password) Ensure that you have used the correct username and password in the request parameters (i.e. ensure that you have replaced USER and PASS in the example code).
response.responseCode = QK (Unknown Customer Merchant) Ensure that the customer.merchant request parameter is set to the correct value.
response.responseCode = QJ (Invalid Customer Certificate) Ensure that you have used the correct certificate file in the ‘initialise’ call (i.e. the 'certificateFile’ initialisation parameter points to the correct certificate file).
response.responseCode = QU (Unknown Customer IP Address) The IP address listed in the error message should be emailed to your implementation manager for configuration.
response.responseCode = QI (Transaction Incomplete) Check the log file for more information. The most likely cause is that you have not specified the proxy information correctly. Another common cause is that your firewall is not configured to allow outbound SSL connections on port 443.
response.responseCode = QX response.text=TLS version TLSv1 is not strong encryption TLSv1.2 must be used. Prior to calling the QuickGateway, force TLS v1.2.

3D Secure Card Payments

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

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

See 3D Secure Card Payments for QuickGateway for more.

Transaction Settlement

Credit card transaction settlement

Westpac credits your account the same day, except on weekends and national public holidays when the settlement is delayed until the next banking day. The amount credited is the total of approved transactions. Any direct debit or 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 (i.e. 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.

For reconciliation purposes, all successful transactions through a given acquirer that return the same settlement date will be credited together on the same day.

What are the credit card cut-off times?

The standard cut-off time for credit card payments is 18:00 (Australia/Sydney Time).

When are payments sent to the bank?

Generally, credit card transactions will be processed immediately. The settlement date will depend on the time of processing (whether they were processed before the current day’s cutoff time).

Response codes

These response codes have been presented for your reference and are derived from the message format defined in Australian Standard 2805.2 (1997).

It is highly unlikely that you will receive many of these response codes; as a general rule you should use the provided summary response code to determine whether a transaction is approved or declined. Valid response codes are of a two digit alphanumeric format.

If an unknown response code is returned please contact Westpac with the appropriate transaction details.

Please note that there are no response codes specific to card verification number mismatches. This is because no financial institutions within Australia currently return any such information if declining a transaction for security reasons. Response Codes are generally returned from the customer’s issuing bank.

Credit card transaction response codes

Successful credit card transactions will generally have a response code of 00 - Approved or completed successfully or 08 - Honour with Identification. Other statuses indicate a problem processing the transaction. If you receive a status code starting with ‘Q’ that you do not understand, you should contact your Client Enquiry Manager with the transaction details.

For non approved transaction statuses that do not start with 'Q’ the card holder will likely need to contact their issuing financial institution for more information about the rejected transaction.

When doing so you can recommend they:

  • provide the date and amount of the transaction.
  • request specific information regarding the transaction rejection.
Summary Code Description
0 Approved
1 Declined
2 Error
3 Rejected


Response Code Description Summary Code Soft Decline
00 Approved or completed successfully. More information 0
01 Refer to card issuer. More information 1 Yes
02 Refer to card issuers special conditions 1
03 Invalid merchant. More information 1
04 Pick-up card. More information 1
05 Do not honor. More information 1 Yes
06 Error 1
07 Pick-up card, special condition 1
08 Honor with identification. More information 0
09 Request in progress 1
10 Approved for partial amount 0
11 Approved VIP 0
12 Invalid transaction. More information 1
13 Invalid amount 1
14 Invalid card number (no such number). More information 1
15 No such issuer 1
16 Approved, update Track 3 0
17 Customer cancellation 1
18 Customer dispute 1
19 Re-enter transaction 1 Yes
20 Invalid response 1
21 No action taken 1
22 Suspected malfunction. More information 1 Yes
23 Unacceptable transaction fee 1
24 File update not supported by receiver 1
25 Unable to locate record on file 1
26 Duplicate file update record, old record replaced 1
27 File update field edit error 1
28 File update file locked out 1
29 File update not successful, contact acquirer 1
30 Format error 1
31 Bank not supported by switch 1
32 Completed partially 1
33 Expired card 1
34 Suspected fraud 1
35 Card acceptor contact acquirer 1
36 Restricted card 1
37 Card acceptor call acquirer security 1
38 Allowable PIN tries exceeded 1
39 No credit account 1
40 Request function not supported 1
41 Lost card 1
42 No universal account. More information 1
43 Stolen card, pick up 1
44 No investment account 1
45-50 Reserved for ISO use 1
51 Not sufficient funds 1 Yes
52 No cheque account 1
53 No savings account 1
54 Expired card. More information 1
55 Incorrect PIN 1
56 No card record 1
57 Transaction not permitted to cardholder 1
58 Transaction not permitted to terminal 1
59 Suspected fraud 1
60 Card acceptor contact acquirer 1
61 Exceeds withdrawal amount limits. More information 1 Yes
62 Restricted card 1
63 Security violation 1
64 Original amount incorrect 1
65 Exceeds withdrawal frequency limit 1 Yes
66 Card acceptor call acquirers security department 1
67 Hard capture (requires that card be picked up at ATM) 1
68 Response received too late 1 Yes
69-74 Reserved for ISO use 1
75 Allowable number of PIN tries exceeded 1 Yes
76-89 Reserved for private use 1
90 Cutoff is in process (Switch ending a day’s business and starting the next. The transaction can be sent again in a few minutes). 1 Yes
91 Issuer or switch is inoperative. More information 1 Yes
92 Financial institution or intermediate network facility cannot be found for routing 1 Yes
93 Transaction cannot be completed. Violation of law 1
94 Duplicate transmission 1 Yes
95 Reconcile error 1
96 System malfunction 1 Yes
97 Advises that reconciliation totals have been reset 1
98 MAC error 1
99 Reserved for national use 1
EA response text varies depending on reason for error 2
EG response text varies depending on reason for error 2
EM Error at the Merchant Server level 2
N1 Unknown Error (NZ Only) 1
N2 Bank Declined Transaction (NZ Only) 1
N No Reply from Bank (NZ Only) 1
N4 Expired Card (NZ Only) 1
N5 Insufficient Funds (NZ Only) 1
N6 Error Communicating with Bank (NZ Only) 1
N7 Payment Server System Error (NZ Only) 1
N8 Transaction Type Not Supported (NZ Only) 1
N9 Bank declined transaction (NZ Only) 1
NA Transaction aborted (NZ Only) 1
NC Transaction cancelled (NZ Only) 1
ND Deferred Transaction (NZ Only) 1
NF 3D Secure Authentication Failed (NZ Only) 1
NI Card Security Code Failed (NZ Only) 1
NL Transaction Locked (NZ Only) 1
NN Cardholder is not enrolled in 3D Secure (NZ Only) 1
NP Transaction is Pending (NZ Only) 2
NR Retry Limits Exceeded, Transaction Not Processed (NZ Only) 1
NT Address Verification Failed (NZ Only) 1
NU Card Security Code Failed (NZ Only) 1
NV Address Verification and Card Security Code Failed (NZ Only) 1
Q1 Unknown Buyer 1
Q2 Transaction Pending 2
Q3 Payment Gateway Connection Error. More information 3 Yes
Q4 Payment Gateway Unavailable 3 Yes
Q8 Error verifying 3D Secure enrolment 3
Q9 3D Secure authentication failed 3
QA Invalid parameters 3
QB Order type not currently supported 3
QC Invalid Order Type 3
QD Invalid Payment Amount - Payment amount less than minimum/exceeds maximum allowed limit 1
QE Internal Error 3
QF Transaction Failed 3 Yes
QG Unknown Customer Order Number 3
QH Unknown Customer Username 3
QI Transaction incomplete - contact Westpac to confirm reconciliation 2 Yes
QJ Incorrect Customer Password 3
QK Unknown Customer Merchant 3
QL Business Group not configured for customer 3
QM Payment Instrument not configured for customer 3
QN Configuration Error 1
QO Missing Payment Instrument 3
QP Missing Supplier Account 3
QQ Invalid Credit Card \ Invalid Credit Card Verification Number 1
QR Transaction Retry 2
QS Transaction Successful 0
QT Invalid currency 3
QU Unknown Customer IP Address 3
QV Invalid Capture Order Number specified for Refund, Refund amount exceeds capture amount, or Previous capture was not approved 1
QW Invalid Reference Number 1
QX Network Error has occurred 3 Yes
QY Card Type Not Accepted 1
QZ Zero value transaction 0
RA response text varies depending on reason for rejection 3
RG response text varies depending on reason for rejection 3
RM Rejected at the Merchant Server level 3
No Short for 'No Account’, this response code indicates the QuickVault account used for the transaction was not found. More information. 3

00 - Approved

This indicates that the transaction has been authorised.

What authorisation DOES mean:-

  • The card number is valid
  • The card has not been reported lost or stolen (although it may in fact be lost, stolen or compromised [card details improperly obtained or copied] and the card owner is unaware)
  • There are sufficient funds available to cover the transaction.

What authorisation DOES NOT mean:-

  • An authorisation does NOT confirm that the person providing the card number is the legitimate card holder. The risk remains that the person providing the credit card number has either stolen or improperly obtained the card.

01 - Refer to card issuer

This indicates an error or problem from the card issuer. The problem may be related to the card holder’s account. This response code is often a result of one of the following:-

  • Suspected Fraud
  • Insufficient Funds
  • Stolen Card
  • Expired Card
  • Invalid CVN
  • Any other rule imposed by the card issuer that causes a decline (e.g. daily limit exceeded, minimum monthly payment not made, duplicate transaction suspected, etc).

03 - Invalid merchant

This can indicate a problem with Westpac’s merchant configuration. This can also be returned for AMEX transactions when there is a problem with the setup at American Express. This code can be returned from an issuing bank if they don’t like the acquiring bank. An example of this would be someone trying to pay their speeding fine with an overseas credit card. The overseas issuing bank would return a 03, indicating that they wouldn’t allow the transaction over the internet for an Australian bank.

04 - Pickup Card.

This can mean the card has been reported as lost or stolen. The card holder should contact their issuing bank.

05 - Do not honour

This indicates an error or problem from the card issuer. The problem may be related to the card holder’s account. In general the reason for this response code may be any of the following:-

  • Suspected Fraud
  • Insufficient Funds
  • Stolen Card
  • Expired Card
  • Invalid CVN
  • Any other rule imposed by the card issuer that causes a decline (e.g. daily limit exceeded, minimum monthly payment not made, duplicate transaction suspected, etc).

08 - Honor with identification

This indicates that the transaction has been authorised.

What authorisation DOES mean:-

  • The card number is valid
  • The card has not been reported lost or stolen (although it may in fact be lost, stolen or compromised [card details improperly obtained or copied] and the card owner is unaware)
  • There are sufficient funds available to cover the transaction.

What authorisation DOES NOT mean:-

  • An authorisation does NOT confirm that the person providing the card number is the legitimate card holder. The risk remains that the person providing the credit card number has either stolen or improperly obtained the card.

12 - Invalid transaction

This code is often returned from the issuer when they do not accept the transaction. This can possibly be when a transaction for the same amount and merchant is attempted multiple times quickly for the same card. The card holder should contact their issuing bank.

14 - Invalid card number (no such number)

This code indicates that the card number does not exist. Also returned code if an AMEX card is used, but the merchant is not setup for AMEX cards.

22 - Suspected Malfunction

This code normally indicates that the card number was invalid.

42 - No Universal Account

This error is returned from some issuers when the credit account does not exist at the issuing bank. This situation is similar to the 14 response code.

54 - Expired Card

This error is returned when the credit card has expired. Check that the expiry date is correct, and attempt the transaction again. If the transaction still does not work, check with the card holder to see if they have a new card with a new expiry date.

61 - Exceeds withdrawal amount limits

This error is returned when the card holder does not have enough credit to pay the specified amount. Ask the card holder if they have another card to use for the payment.

91 - Issuer or switch is inoperative

This code is used to indicate that the next party in a credit card transaction timed out and the transaction has been reversed. This may happen between QuickStream and Westpac, or further down the chain. This response may also be returned for pre-authorisation transactions that are manually reversed.

92 - Financial institution or intermediate network facility cannot be found for routing

The card number is incorrect. The first 6 digits of the credit card number indicate which bank issued the card. These are used for routing credit card requests through the credit card network to the issuing bank. This error indicates that there is no bank that corresponds to the first 6 digits of the card number.

QI - Transaction incomplete

This status code indicates that a request message was sent to the QuickStream server but no response was received within the timeout period.

QQ - Invalid Card

The QQ error code indicates that the credit card details (card number, expiry date or CVN) are invalid. This could be because the card number does not meet check digit validation, an invalid expiry date was entered, or an invalid CVN was entered.

QY - Card Type not accepted

The QY error code indicates that the merchant is not enabled for the particular card scheme. This error code is normally returned for American Express and Diners Club cards, or when a UnionPay debit card is used. Only UnionPay credit cards are supported.

Q3 - Payment Gateway Unavailable

The downstream credit card gateway was unavailable. The credit card transaction was not attempted and the transaction record will not exist. When you receive this response code, the transaction will not exist in QuickStream.

No - No Account

The QuickVault account used for the transaction was not found or is not enabled. Please check that the QuickVault account exists and is enabled. You can do this in via QuickGateway or in QuickStream Portal.

Glossary

CA-XCOM

CA-XCOM is a cross-platform, value added data transport solution, providing high-performance unattended file transfer with complete audit trails and reporting. CA-XCOM provides a single solution for sending and receiving files, as well as sending reports and jobs, to a wide range of platforms. This is Qvalent’s standard file transfer mechanism.


Certificate

An electronic document that identifies an entity (e.g. a person, computer or company). Each certificate contains the entity’s public key, along with details about which encryption algorithms the entity can use. Certificates are issued by Certificate Authorities (CAs) when the CA verifies the entity requesting the certificate.

Each certificate contains a subject, describing who the certificate is for, and an issuer, describing the organisation that signed the certificate. The certificate contains the entity’s public key, as well as the digital signature of the CA. This signature is like a hologram on a credit card, verifying that the CA has authenticated the entity’s identity. Certificates can be marked for various purposes, including SSL client, SSL server and CA. See also Certificate Authority, Digital Signature, SSL and Public Key Encryption.

Certificate Authority

A trusted third party that signs certificates for other parties. Often in internet communications, the two parties will not trust each other, but will trust a third party. Party A can trust party B’s certificate if it is signed by that third party (the certificate authority or CA).

Certain CAs (e.g. Verisign, Thawte) are automatically trusted by all certificate software. See also Certificate and Certificate Hierarchy.

Certificate Hierarchy

The chain of certificates for an entity consisting of that entity’s certificate and any CAs which signed the certificate. All certificates are signed by another certificate, generating a hierarchy. This hierarchy terminates at a root certificate, which is self-signed. This type of certificate contains an identical issuer and subject.

A certificate is trusted by a party if the certificate chain terminates at a CA which is trusted by that party. Each party maintains a list of trusted root CAs. See also Certificate, Certificate Authority and Self-signing.

Digital Signature

A process of signing a message electronically. Normally, the sender of a message will calculate a message digest, then encrypt that digest value with the sender’s private key. This resulting value is the digital signature.

The receiver can verify the signature by calculating the message digest, and compare it to the value obtained by decrypting the digital signature with the sender’s public key. See also Message Digest and Public Key Encryption.

Encryption/Decryption

The process of scrambling a message so that it cannot be read by a third party while in transit. The sender encrypts a message before sending, and the receiver decrypts the received message before reading it. Many algorithms are available to encrypt data. Examples include RSA, RC4 and DES. The algorithm is generally well known, but a number (called a key) must be used with the algorithm to produce an encrypted result or to decrypt previously encrypted information. Decryption with the correct key is simple, whereas without the key, decryption is almost impossible.

HTTP

Hypertext Transfer Protocol: The application level protocol that is used to transfer data on the web. A client sends a request message to the server, and the server sends a response message. Each message consists of a start line (which is either a request line or a status line as appropriate), followed by a set of message headers and finally an optional message body.

The request line contains the method (usually GET or POST) used for the request. GET is a simple request for information, whereas POST allows the client to send data to the server in the request. A web browser generally sends a GET request to the server for information, and the server responds with an HTML document in the response for the browser to display.

The HTTP protocol uses the TCP/IP protocol to transport the information between client and server. HTTP uses TCP port 80 by default. See also TCP/IP.

HTTPS

Hypertext Transfer Protocol, Secure: The HTTP protocol using the Secure Sockets Layer (SSL), providing encryption and non-repudiation. HTTPS uses TCP port 443 by default. See also HTTP and SSL.

Message Digest

A mathematical function which generates a number from a message (also called a one-way hash). The generated number is unique for the message, in that changing any part of the message changes the resulting number. The function is one-way in that it is, for all practical purposes, impossible to determine the message from the number. Common algorithms are MD5 and SHA-1.

Non-repudiation

Assurance the sender of data is provided with proof of delivery and the recipient is provided with proof of the sender’s identity, so neither can later deny having processed the data.

Proxy Server

An intermediate server on the client side of an HTTP transaction which makes requests on behalf of the client. Proxy servers improve corporate security by only exposing the proxy server to the internet, rather than each individual computer in the organisation. The client sends its request to the proxy server, which then sends the request (with any modifications) to the server.

The server responds to the proxy, which then passes the response to the client. System administrators can restrict which servers are accessible simply by configuring the proxy server. See also HTTP.

Public Key Encryption

An encryption method where different keys are used for encryption and decryption. Each party has two keys - a public key and a private key. Messages encrypted with the public key can only be decrypted with the private key, and messages encrypted with the private key can only be decrypted by with the public key. Each party publishes their public key and keeps their private key secret.

Encryption is accomplished by the sender encrypting the message with the receiver’s public key. The message can then only be decrypted by the receiver with his private key.

Non-repudiation is accomplished by the sender encrypting the message with her private key. The message can then be decrypted by anyone with the sender’s public key (which is published), but the receiver can be assured of the message’s origin. See also Symmetric Key Encryption and Encryption.

Self-Signing

Self-signing occurs when the owner of a key uses his private key to sign his public key. Self-signing a key establishes some authenticity for the key, at least for the user IDs. The user ID of the signature must match the user ID of the key. (Where there are multiple user IDs, the ID of the signature must match the primary ID of the key.) Also, the key ID of the signature matches the key ID of the key. This verifies that whoever placed a user ID on a public key also possesses the private key and passphrase. Of course, this does not verify that the owner of the key is really who she says she is. That is done by the signatures of others on the public key (such as a root CA like Verisign).

SOAP

Simple Object Access Protocol: An XML-based protocol allowing remote procedure calls and asynchronous messaging. SOAP generally uses HTTP to transport the messages between computers. SOAP is becoming popular because of its use of standard internet protocols as its basis. See XML and HTTP.

SSL

Secure Sockets Layer: A protocol designed by Netscape to encrypt data, authenticate the client and server and ensure message integrity. SSL sits between the application layer protocol (e.g. HTTP) and above the TCP/IP network protocol.

The SSL handshake establishes the SSL connection, setting up the secure channel. In this process, the server presents its certificate to the client for authentication:

  • The server encrypts some data with its private key and the client then checks this signature with the public key from the server’s certificate.
  • The client checks that the server DNS name is the same as that in the certificate.
  • The client checks that the server certificate has not expired.
  • The client checks that the server’s certificate is signed by a trusted CA.

The server can also optionally require the client to present its certificate to the server for authentication.

The handshake also allows the client and server to agree on an encryption algorithm (a symmetric key algorithm for speed) and securely exchange the session key. This session key is used in the encryption algorithm which encrypts the data exchanged between the client and server after the handshake is finished. The session key length can be 40-bit, 56-bit or 128-bit, with the longer keys being more difficult to break. See also TCP/IP.

Symmetric Key Encryption

An encryption method where the sender and receiver use the same key to encrypt and decrypt the message. This method relies on the key being kept a secret between the two parties. If the key is discovered, anyone can read the messages in transit, or send false messages to the receiver.

This type of encryption is often used for bulk encryption because it is much faster than public key encryption. See also Encryption and Public Key Encryption.

TCP/IP

Transmission Control Protocol over Internet Protocol. IP allows packets of data to be sent across the internet from one computer to another. TCP provides a reliable communication stream between the two computers, using the Internet Protocol.

XML

eXtensible Markup Language: A document formatting language which describes a standard syntax, but allowing many different document types. Business partners can then agree on the specific documents they will exchange, using the standard syntax. XML documents contain a hierarchical list of tags, some of which contain values.