Additional 3 Party Functionality
9 Troubleshooting and FAQs
Troubleshooting
This section contains suggestions and solutions to problems that may occur with your integration.
What Do We Do if a Session Timeout Occurs?
It is possible that while a cardholder is entering their card details at the Payment Server, the session is broken (say a communication failure due to a modem
connection dropping off). If this occurs, a cardholder will lose their session. Even if they come back to your site, they will have a new session, and their old session will never be completed.
To determine the status of the lost transaction, you will need to perform a QueryDR transaction based on the original MerchTxnRef.
Does the Cardholder's Internet Browser Need to Support Cookies?
The Payment Client interface requires a cardholder's browser to support cookies for all 3-Party.
What Happens if a Digital Receipt Fails to Come Back?
To deal with a Digital Receipt that fails to come back:
1 Flag the transaction as having an error, so that it needs to be manually checked using Merchant Administration on the Payment Server.
Or,
2 Use the Advanced Merchant Administration (AMA), QueryDR command to search the Payment Server database for the transaction. The MerchTxnRef is used as the transaction identifier when searching using QueryDR command.
Since the Digital Receipt has failed to come back, there is no transaction number available from the Payment Server to identify the transaction in question, and this is why you use the MerchTxnRef. It is important to have a unique MerchTxnRef for every transaction otherwise the query could return multiple results. Only the most recent transaction is returned in the QueryDR command if there are multiple results, but this may not be the transaction you are concerned with.
• If the DigitalReceipt.QSIResponseCode was successful
When you find the required MerchTxnRef in the QueryDR, check the DigitalReceipt.QSIResponseCode field to see if it is successful (should be equal to '0'). If the DigitalReceipt.QSIResponseCode is 0, then the transaction is successful and you just need to extract the relevant data details from the QueryDR results for your records.
• If the DigitalReceipt.QSIResponseCode code was not successful.
If the DigitalReceipt.QSIResponseCode is not 0, you need to determine the next course of action based on what you would do if the
DigitalReceipt.QSIResponseCode were not 0 in a normal Digital Receipt coming back from the Payment Server.
• If you did not find a QueryDR result.
If you query the Payment Server for the MerchTxnRef using the QueryDR call and you do not receive any results, that is QueryDR.DRExists = 'N', then it is safe to repeat the transaction. It is safe to use the same MerchTxnRef, as the existing one does not show up in the Payment Server's database and therefore it was never processed.
• If you find multiple QueryDR results.
If the QueryDR is flagged as having multiple results (returns 'Y' in the
QueryDR.FoundMultipleDRs field), then the MerchTxnRef is not unique.
This is the primary reason for implementing a unique MerchTxnRef for every transaction. QueryDR returns the latest transaction but this may not be the one you require.
This solution requires more data capture and processing, but it is only necessary when you do not have a unique MerchTxnRef number.
How Do I Add the PCThread.sh in the Start-up Environment in Linux?
1 Log in as root.
2 Navigate to /etc/rc.d directory.
cd /etc/rc.d
3 Open rc.local file, using vi or pico, for editing.
4 At the end of the file add following line
<path_to_java>/java -cp<path_to_PaymentClient_classes>
PaymentClient.PCService &
5 For example on our system that is:
/usr/local/apps/jdk1.3.1/jre/bin/java -cp /usr/local/Dialect/PaymentClient/classes PaymentClient.PCService &
6 Save the file and re-boot the machine.
Notes
• Make sure the line ends with '&', as that will run the process in the background, and will not obstruct the start-up process.
• Make sure that the paths are correct. You can test it by running it on the command line prior to entering it to the file.
• To test, you can do a netstat and verify that port 9050 is in use, or telnet on localhost to port 9050 and type:
Handling Socket connection Time Outs
In most applications like ASP and Java, the Sockets are set-up with a socket time-out value, for example in ASP:
' Open a socket connection to the Payment Client socketPayClient.TimeOut = 200000 ' 200 seconds
socketPayClient.Host = payClientIP & ":" & payClientPort
If the socket times out you need to handle the situation and determine the status of the transaction that timed out. The easiest way to do this is to perform a QueryDR transaction based on the original MerchTxnRef.
It is much better to have the sockets timeout value set to a longer value than a shorter value.
If the socket timeout period is reduced to a value too low, for example 10 seconds, then under times of heavy load on the Payment Server this short timeout period may be exceeded. The time out would normally occur on processing messages like
sending a Digital Order, which take time for the Payment Server to process. The message is transmitted to the Payment Server, where it is processed successfully, but the successful response of '1,1' may take longer to arrive back at the socket than the socket time out period allows. So the data remains in the Payment Client buffer waiting for transmittal to the application. If the time out is ignored, the next command sent will contain this old status value, and its status will still be in the Payment Client buffer again waiting for transmittal to the application. All responses are then displaced.
Note: In each of the socket example commands shown in this guide, the “\n” 'New Line' character at the end of each command string is used to tell Java to input a “Line Feed” character to indicate the end of the command.
Failure to include this character or a “Carriage Return” character - Java “\r” at the end causes the socket command to fail.
Some programming languages such as ASP can automatically add this to the end of the command so the programmer does not have to include it.
You need to ensure that the timeout period is long enough not to time out
prematurely, but if the socket does time out, it needs to be detected and not continue with the next step of the transaction. If the merchant application continues and process the next command, then all future responses are displaced.
Comparison of a good and bad transaction when the timeout is ignored
Socket Information Flow 2-Party
Good Transaction Bad Transaction
Sent Received Sent Received
1,Test\n 1,echo:Test 1,Test\n 1,echo:Test
translates to echo("Test") command in Payment Client
7,CardNum,5123456789012346\n 1,1 7,CardNum,512345678901234
6\n 1,1
addDigitalOrderField("CardNum") command
7,CardExp,0202\n 1,1 7,CardExp,0202\n 1,1
addDigitalOrderField("CardExpiry") command
7,ticketNo,data for transaction\n 1,1 7,ticketNo,data for
transaction\n 1,1
addDigitalOrderField("TicketNo") command
6,1234,Test2008,100,en,\n 1,1 6,1234,Test2008,100,en,\n Socket times out, no response. Merchant continues with the next command.
sendMOTODigitalOrder("1234", "Test2008", "100", "en", "")
5\n 1,1 5,\n 1,1 (From
6,1234,Test2008, etc.) nextResult( ) command
4,DigitalReceipt.QSIResponseCode
\n 1,0 * 4,DigitalReceipt.QSIResponse
Code\n 1,1 (From 5,) Error
4,DigitalReceipt.ReceiptNo\n 1,01102502 4,DigitalReceipt.ReceiptNo\n 1,271 (From 4, …TxNo,) objPayClient.getResultField("DigitalReceipt.ReceiptNo")
* A QSIResponse Code of '0' indicates a
successful transaction. * A QSIResponse Code of '1' indicates a declined transaction
The commands for the Sockets interface are shown in The Payment Client Reference Manual. If the time out is not detected and the transaction continues, the data
returned is incorrect for each of the following commands that are sent after the socket timeout.
The result of not detecting and handling the time out is that a successful transaction has been conducted but the merchant application will interpret the transaction as a
The response from the command '5\n' is '1,1',
which is a good response but it is actually from the sendMOTODigitalOrder
command (6,1234,Test2008,100,en,\n)
The response from command '4,DigitalReceipt.QSIResponseCode\n' is '1,1' which shows up as a QSIResponseCode of '1', which indicates a failed transaction, but this response is actually from the '5\n' command. The actual QSIResponseCode is '0' because the transaction completed successfully, but it is delayed one command so it is lost. One of the common responses to this is to have the merchant
application redo the transaction, which would result in a duplicate transaction.
The response from command '4,DigitalReceipt.TransactionNo\n' is '1,0' which shows up as a Transaction No of '0', which is incorrect, but this response is actually from the '4,DigitalReceipt.QSIResponseCode\n' command.
The response from command '4,DigitalReceipt.ReceiptNo\n' is '1,271' which shows up as a Receipt No of '271', which is incorrect, but this response is from the
4,DigitalReceipt.TransactionNo\n command. The real Receipt No of '01102502' is lost from the transaction stream.
If the Payment Server has successfully processed the transaction and the transaction is repeated it would result in a duplicate transaction.
If a socket time out occurs, do not ignore the time out, as it will only cause errors.
Detection can be as simple as looking for an empty receive value from the socket.
There are two ways of dealing with a Payment Client sockets timeout:
1 Flag the transaction as having an error that needs to be manually checked using Merchant Administration on the Payment Server. You need to determine what to send back to the cardholder while this manual check is performed, as it could be a good transaction.
2 Close the socket and open a new socket connection and use Advanced Merchant Administration commands to search the Payment Server database for the
transaction. The QueryDR command can be used to search the Payment Server using the MerchTxnRef as the transaction identifier. At this stage there is no transaction number available back from the Payment Server to identify the transaction, so it is important to have a unique MerchTxnRef for every transaction.
If you are using QueryDR then:
• If the QSIResponseCode code in the QueryDR function was successful
When you find the required MerchTxnRef in the QueryDR, check the
QSIResponseCode field to see if it is successful (should be equal to '0'). If the
QSIResponseCode is 0, then the transaction is successful and you just need to extract the relevant data details from the QueryDR results for your records.
• If the QSIResponseCode code the QueryDR function was not successful
If the QSIResponseCode is not 0, you need to determine the next course of action based on what you would do if the QSIResponseCode were not 0 in a normal Digital Receipt coming back from the Payment Server.
• If you did not find any results using QueryDR function
If you query the Payment Server for the MerchTxnRef using the QueryDR
function and you do not receive any results, (i.e. QueryDR.DRExists = N) then it is safe to repeat the transaction. It is safe to use the same MerchTxnRef, as the existing one does not show up in the Payment Server's database and was therefore never processed.
• If the QueryDR is flagged as having multiple results
If the QueryDR is flagged as having multiple results (returns 'Y' in the
QueryDR.FoundMultipleDRs field), the MerchTxnRefis not unique and you will have to manually check all the results for the same time when the MerchTxnRef number was created.
This solution requires more data capture and processing, but it is only necessary when you don't have a unique MerchTxnRef number.
Frequently Asked Questions
What is an Outage?
An outage is considered a “production fault” as it means that the Payment Server is temporarily offline; for example for maintenance and upgrades, and so forth.
During an outage, all transactions are declined with an error message indicating that the service is currently unavailable.
Can the Payment Server's Payment Pages be Modified for a Merchant?
No. The Payment Server's payment pages are branded using either the Payment Provider's or Bank's branding to assure cardholders of the security of the transaction.
If you do not wish to display the Payment Provider's branded pages you need to implement either the 3-Party with card details, or the 2-Party integration models.
Note: Using the 2-Party Integration model prohibits the use of 3-D Secure Verified by Visa™ MasterCard SecureCode™ and J/Secure™ functionality.
How Do I know If a Transaction Has Been Approved?
All approved transactions are represented with a DigitalReceipt.QSIResponseCode of '0' (zero) from the Payment Server. Any other code represents a declined or failed transaction.
Can the Payment Client Listen on Any Port Other than 9050?
Yes, the ...\Dialect\PaymentClient\config\PCService.properties file can be amended to reflect the new port number, any other IP addresses and the
maximum number of threads allocated to the new port. This can be done as follows.
Open the ...\Dialect\PaymentClient\config\PCService.properties file in a text file editor and amend the following lines:
ports=XXXX (Where XXXX represents the socket port number to be used.)
ipNumber1=127.0.0.1 (127.0.0.1 is the localhost machine)
ipNumberX=xxx.xxx.xxx.xxx (xxx.xxx.xxx.xxx is the IP number of a machine requiring to connect to the socket remotely)
threads=X (Maximum number of threads that may connect to the socket interface)
Detailed instructions are included in the Payment Client Installation Guide.
Longevity - How Long Will the Technology be Useful?
Additional functionality can be added to the Payment Server, which requires the merchant to perform small additional integration work to utilise any new functions.
Typically, existing Payment Clients and their methods are not affected by new functionality and remain backward compatible.
Handling Large Peaks in Transaction Volumes?
The Payment Server queues pending transactions so transactions are not lost, although the cardholder may at times notice a slight delay when transactional loads are very high.
How Often Can I Reconcile?
Reconciliation can be completed using either Merchant Administration or Advanced Merchant Administration. In either case the Payment Client does not limit the frequency of the function, but the payment processor may have a settlement frequency - generally daily - which is useful if any problems with transactions occur as all the days transaction are in the same batch.
Is a Shopping Cart required?
It is not necessary to have a shopping cart. All that is required is that the transaction information is within the Digital Order passed to the Payment Server.
What is Merchant Administration?
Merchant Administration is the merchants internet based administration portal, which allows merchants to monitor and manage their on-line processing and administration of payments through a series of easy to use pages.
To use Merchant Administration, you need to have access to the internet through a browser (such as Internet Explorer). You also need the Acquiring Institutions URL (or web site address).
The merchant can use one of two methods to manage their transactions:
• Merchant Administration ‒ using a browser interface to interactively perform historical searches, captures, refunds settlements and to perform setup activities.
These functions are described in this guide. For more details, please refer to the Merchant Administration User Guide.
• Advanced Merchant Administration ‒‒ using the Payment Client to directly access the Payment Gateway to perform all transaction-related actions (for example, captures, refunds and purchases) integrated with merchants' software interfaces.
Why Can't I Utilise the Advanced Merchant Administration (AMA) Functionality Via the Payment Client?
The following reasons may cause AMA functionality not to work:
• A separate operator needs to be created for AMA API calls
• Your merchant account is required to have the privileges to execute AMA functions, please check with the helpdesk that this is enabled for your merchant account.
• Advanced Admin methods privilege has to be enabled in operator set-up in Merchant Administration. An AMA operator cannot connect to Merchant Administration unless the AMA privilege is removed.
• Check that you are not using incorrect MerchantId, OperatorID or Password details.
• If the Payment Client is communicating with the Payment Server when
attempting to process AMA calls, check that the firewall is open to communicate between the two applications.
How Much Will it Cost to Keep the Payment Site Running?
The Payment Client is very stable, is not difficult to keep running and requires no more maintenance than the web server itself.
Does the Payment Server Handle Large Peaks in Transaction Volumes?
The Payment Server queues pending transactions so transactions are not lost, although the cardholder may at times notice a slight delay when transactional loads are extremely high.
How Long Will an Authorisation be Valid on a Cardholder Account?
This depends on the Financial Institution who issued the card to the cardholder.
Each card Issuer defines the authorisation expiry period in which they hold the funds on the cardholder's account, while they wait for the arrival of the capture transaction.
Generally it is 5-8 processing days, before the authorisation purges from the cardholder account and access to the funds are released back to the cardholder.
What is the RRN and How Do I Use It?
RRN (Reference Retrieval Number) is a unique number for a particular MerchantId.
This is the value that is passed back to the cardholder for their records. You cannot search for this field in Merchant Administration, but it is displayed in Merchant Administration on the transaction details pages as the Reference Retrieval Number (RRN). It is one of the fields returned in a QueryDR and the transaction result (captures, refunds).
The RRN is useful when your application does not provide a receipt number. The RRN can be viewed in Merchant Administration.
What is the Difference Between RRN, MerchTxnRef, OrderInfo, AuthorizeId and TransNo ?
• RRN (Reference Retrieval Number) is a unique number assigned to each transaction for a particular MerchantId. This is the value that is passed back to the cardholder for their records. You cannot search on this field in Merchant Administration, but it is displayed in Merchant Administration on the transaction details pages as the Reference Retrieval Number (RRN). It is one of the fields returned in a queryDR and the transaction result (captures, refunds).
• MerchTxnRef is generated by your merchant application. Ideally it should be a unique value for each transaction and you should retain this number so that transactions can be searched for in your application and the Payment Server. See Merchant Transaction Reference (MerchTxnRef) on page 19)
• OrderInfo is also generated by your application. It should also be a unique value for each order, which you should retain so that you can search for the
transaction in your application and the Payment Server.
• AuthorizeId is an identifier from the Acquiring Bank, which is in the Digital Receipt for the authorisation. This field cannot be searched for in Merchant Administration, but it is displayed in Merchant Administration as the
Authorisation Code. It is one of the fields returned in a transaction result and an AMA QueryDR.
• TransNo or TransactionNo is a unique number for each MerchantId generated by the Payment Server that is called the OrderID or shopping transaction number. The OrderID is the key reference value for transactions when using AMA transactional functions like captures and refunds.
Advanced Function Compatibility
The following table lists the common functions available on the Payment Server and the compatibility of functions the merchant can use. To determine the functionality that can be included in a Digital Order choose a function in a column and follow it
The following table lists the common functions available on the Payment Server and the compatibility of functions the merchant can use. To determine the functionality that can be included in a Digital Order choose a function in a column and follow it