Response Handling

This document describes the basic steps in handling transaction responses received by a payment application from the Moneris Gateway. The recommended steps outlined in this document should only be implemented for transactions sent using one of the API methods of integration.

Response handling for other methods of integration such as Hosted Paypage, Direct Post, Batch File Upload, and Card Present Integration are not covered in this section.

System and Skill Requirements

This document is intended to be used in conjunction with the regular Moneris Gateway API Merchant Integration Guides and the Response Code document. For specific system and skill requirements, please refer to the specific API’s Integration Guide. For descriptions on each Response Code, please refer to the Response Code document.

All references to programming constructs in this document will be language-neutral. For language-specific constructs, please refer to the appropriate API Integration Guide for the programming language of your interest.

Response Handling

In handling responses from the Moneris Gateway, merchants are advised to provide their own messages that are more user-friendly to the cardholders and indicative of the Message values that may be returned in the transaction response. This is especially important when handling error conditions as the error messages returned may or may not make sense to the cardholder. Note that receipt handling is different from response handling and there are card association rules that must be met in generating receipts for the cardholder. Please refer to each API’s Integration Guide for information on receipt requirements.

When a payment is made from a payment application through the Moneris Gateway using one of the API’s, a Response will be returned to the merchant’s payment application. The payment application must first check for the results of 2 parameters in the transaction Response; Complete and TimedOut. These values could be retrieved by calling the two specific functions of the API’s Response. The function names are typically “getComplete” and “getTimedOut”, respectively. There are 4 possible resulting Conditions from calling these functions. These conditions are described in Table 1 below. These Conditions are grouped into 2 types of outcome; Success or Error. Condition A is grouped as a Success outcome and Condictions B, C, and D are grouped as Error outcome. For information on the Error type of outcome and the recommended way of handling it, please refer to section “4. Error Level”. This section describes the recommended way of handling a Success outcome.

Condition	Function		Description
	getComplete	getTimedOut
A	true	false	These are the normal results returned for transactions that were successful, such as approved and declined with responses returned from the host. This is not considered an error condition. The response returned to the cardholder should indicate the transaction has been either approved or declined. For details on handling this condition, please refer to section “4. Response Handling”.
B	false	null	This is typically an indication of error conditions at Level 2. Problems with connections to the Moneris Gateway would generate these results. Further checking of the values for the other parameters may be required in order to determine the error level.
C	false	false	This is typically an indication of error conditions at Level 2. Problems with merchant account setup or integration would return these results. Further checking of the values for the other parameters may be required in order to determine the error level.
D	false	true	This is typically an indication of error conditions at Level 3. Further checking of the values for the other parameters may be required in order to determine the error level.

Referring to the above table, upon confirming that the results match Condition A by checking the values of the TimedOut and Complete parameters, two additional parameters’ value (below) in the Response must also be checked. The function names typically used in the API to obtain the values are getResponseCode and getMessage.

The Response Code value must first be checked. Values of 0 to 49 (inclusive) indicate the transaction was successfully Approved. Values of 50 to 999 (inclusive) indicate the transaction was successfully Declined. The Message value is then checked to obtain the descriptoin detail of the Response Code. Please refer to the Response Code document referenced in section 2 for detail information about each Response Code. The Response Codes document groups the responses into different categories. You may want to handle Declined responses more generically based on the categories that they belong and generate category-based generic messages for display to the cardholder.

Error Level

In a typical online business, the Check-out process-flow may involve at least 4 significant levels of participants in getting a response back to the original cardholder. Please refer to the Diagram 1 below. The Check-out or Response handling process should be accommodating for all the possible error conditions that could occur at the various levels of participation.

Level 1: Cardholder – Merchant:

Any error generated as a result of problem at this stage is usually specific to the merchant implementation. Errors may or may not be related to payment. For payment-related errors that are returned from the payment gateway, we recommend that merchants in turn produce their own error messages that are more user-friendly to the end cardholder. Error messages generated at this level and the process to resolve them will be specific to each merchant’s system and outside the scope of this document.

Level 2: Merchant – Moneris Gateway:

When a payment is made through the Moneris Gateway using one of the API’s, a Response will be returned to the merchant’s payment application. There are 2 possible error Conditions (B & C in Table 1) resulting from problems at this level. Errors at this level may be caused by problems in the following areas:

1. Network connection between merchant and Moneris Solutions
2. Merchant account profile set up at the gateway level
3. Payment Integration problems at the merchant level
4. Technical difficulties at the Moneris Gateway

Please refer to the description of each area below for additional detail.

Network Connection Problem

This type of problem will result in the Complete and TimedOut parameters to be those of Condiction B in Table 1. Some API’s may provide additional information by calling the “getMessage” function to obtain the Message parameter’s value in the Response. Other API’s may contain “null” in the Message. It is recommended that this type of error be individually investigated.

There may be minor subtle difference in the responses returned among the different flavours of the API’s due to the nature of the technologies they use. It is highly recommended that all the conditions specifically be tested using your chosen API language.

Account Setup Error, Payment Integration-related Problems, & Technical Difficulty

This type of problem will result in the Complete and TimedOut parameters to be those of Condiction C in Table 1. Further checking of the Message parameter’s value must be made by calling the “getMessage” function of the Response. It is recommended that this type of error be individually investigated. Based on the Message value, our Technical Support or Sales team may be contacted for assistance. The Message may also indicate problems with the components in the transaction request in which case the payment application needs to be investigated.

Level 3: Moneris Gateway – Host:

The nature of processing transactions electronically includes communication errors which can not be avoided and therefore must be properly handled by the payment application. Any error resulting from this level is usually related to a connection problem between the Moneris Gateway and the host. Depending on when and where the error occurs, transaction results may or may not make it all the way back to the payment application.

When a payment is made from a payment application through the Moneris Gateway using one of the API’s, a Response will be returned to the payment application. Upon confirmation of Condition D in Table 1 by checking the values of the TimedOut and Complete parameters, the Message parameter’s value in the Response must also be checked. The function name typically used in the API to obtain the value is “getMessage”. It is recommended that each transaction be fully investigated by contacting our Technical Support helpdesk.

Special Condition

There are certain transaction types or conditions that will require special handling of the responses. Details of how to handle each case is described below.

OpenTotals and BatchClose Transactions:

In a successful OpenTotals or BatchClose transaction (Condition A of Table 1), the Response Code value of the Response will be “null” instead of the standard 0 – 999 value.