Response Handling
During development, Moneris provides simulator systems for testing your solution and ensuring your applications and systems are ready to handle transaction responses.
During development, Moneris provides simulator systems for testing your solution and ensuring your applications and systems are ready to handle transaction responses. Handling a response from the Moneris API involves confirming the status of the request itself and building logic within your solution for taking the next correct action. In some successful scenarios, this may involve using a value within the response body to inform the next appropriate transaction to perform; in failed transactions, this may involve incorporating documented errors to prevent transaction retries or prompt cardholders for alternate methods of payment.
Response Levels
Third Party Systems as Level 0.5 or 1.5
Some merchant integrations may utilize a third-party vendor or ‘middleware’ provider that acts between levels in this diagram. They may appear either:
Between merchant server and Moneris, usually a as a pre-built payment integration
Between the cardholder and the merchant server (such as a pre-built shopping cart module for an eCommerce store). If your solution includes either of these, keep that additional layer in mind as part of your design for response handling.
In a typical transaction, communication flow passes through multiple systems. This diagram below provides an abstraction for understanding possible failure points in your transaction to aid in development and troubleshooting. We will use the term ‘Response Level’ for each zone in the diagram and discuss the problems possible for that interface.
Level 1: Cardholder to Merchant
Errors generated at this stage occur before a Moneris API request is sent and are specific to your merchant implementation. Errors may or may not be related to payment itself, depending on validation on data performed by your solution. 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, but we suggest that any error messages you produce are user-friendly to the cardholder.
Level 2: Merchant to Moneris Gateway
Errors generated at this stage involve your server sending a request message and receiving a response indicating failure or no response at all.
Failed Response
The nature of processing transactions includes possibility of format or content errors within your request message or communication errors downstream from our Moneris API endpoints which cannot be avoided. Therefore, your payment application must properly handle any resulting responses indicating an error.
The Moneris API makes use of standard HTTP Status Codes and a Problem JSON in every error response to assist with troubleshooting the nature of the error. Fields from the error response body can provide links to documentation on the error, details on on the nature of this specific instance of the error, and enumerate related fields to the error.
Official HTTP status codes are defined via RFC standards and registered in the IANA Status Code Registry.
Main RFC standards are RFC7231 - HTTP/1.1: Semantics (or RFC7235 - HTTP/1.1: Authentication) and RFC 6585 - HTTP: Additional Status Codes
In addition, Moneris uses Problem JSON objects per RFC 7807 in error responses for client usage errors (4xx status codes) and server side processing errors (5xx status codes).
No Response / Timed Out
Failure to receive a response indicates a network connection problem between your merchant server and Moneris.
Confirm the URL you are using for the request is valid within our materials; typos in the domain can lead to time-out issues
Network issues with your internet provider or merchant server outside the scope of this documentation
Level 3: Moneris to Card Brands and Issuers
Partial POST Create Payment
Some requests from the Moneris API can return successfully but require additional response handling beyond the HTTP status code itself. Commonly this involves particular fields within the response body that indicate the status of the entity itself or inform business decisions performed by your application. These elements are outside the scope of HTTP status itself, or represent microservices downstream in the payment flow returning their responses as part of the overall transaction.
ISO and Host Response Codes
For the Payment endpoints, Moneris suggests using the possible values of “paymentStatus” as your common test scenarios. If you require the additional layer of transaction details, you can also replicate various host “responseCode” values via our Penny Value Simulator in the test environment. During testing, the cents value of your transaction ($1.xx) determines the success or failure of your payment. Consult the Penny Value table and the Host and ISO Response Code tables for more.
Receipt Handling
After handling the response itself, you may need to provide information taken from the response to form a receipt for the customer. Receipts involves card association rules that must be met in generating receipts for cardholders. This topic is explained in more detail in Receipt Handling.
For a basic example, we can look at the response for a Payment entity:
“paymentStatus” gives the current status of the the Payment. Possible states are listed in our API Reference, for instance:
“DECLINED _RETRY” advises to reattempt the payment transaction immediately
“DECLINED” advises that the transaction was rejected by our host, the card brand, or the issuing bank
“CANCELED” indicates the payment was voided via the POST Cancel Payment endpoint
“AUTHORIZED” is the state for a preauthorization payment prior to completing it with the POST Complete Payment endpoint
“SUCCEEDED” is the state of an approved payment, whether by the POST Complete Payment OR for a purchase via POST Create Payment with “automaticCapture” set to “true”
“PROCESSING” returns in any response from an ongoing asynchronous process.
“transactionDetails” holds useful information for troubleshooting declined transactions, such as the terminal “message” for the response, the “isoResponseCode” and the “responseCode”. These offer further context for issuer-based declines when investigating declined transactions
HTTP Status Codes
Redirection Codes
Returned when your request fails and your client must take additional actions to complete the request.
Success Codes
Returned when the request is successfully received, understood, and accepted.
Server-Side Error Codes
Returned when your request fails due to server-side issues or errors.
Client-Side Error Codes
Returned when your request fails due to possible errors in the request message.