Moneris Checkout Overview

Moneris Checkout gives e-commerce merchants a simple and secure way to process payments by integrating a Moneris-hosted payment module into the merchant checkout page.

System and Skills Requirements

In order to integrate with Moneris Checkout as a merchant, you must have:

• An e-commerce website with a back-end server

For development, you should have some understanding of the following:

• JavaScript
• JSON
• Server-side programming

Additionally, for Google Pay™ integration, all your front-end web pages must use the HTTPS protocol.

Configuration

The first step is to configure your Moneris Checkout page in the Moneris Merchant Resource Center (MRC).

In the initial stage of development, you create a test configuration in the testing MRC. Once the solution is ready to be deployed to production, you must create a new, separate configuration for the production environment in the production MRC.

The checkout ID is the key value that is generated after the configuration is completed and used within the Preload Request in order to identify the specific Moneris Checkout configuration.

To get the checkout ID and start configuring your page, do the following:

1. Log into the Merchant Resource Center at one of the following URLs (according to your stage of development)
   
   Testing:
   https://esqa.moneris.com/mpg
   
   Production:
   https://www3.moneris.com/mpg
   
   
2. In the Admin menu, select Moneris Checkout Config
3. Click the Create Profile button
4. Follow the on-screen steps to complete the configuration

For more information, see the Merchant Resource Center documentation

Additional Features in Moneris Checkout

• Tokenization of Credentials With Moneris Checkout
• Fraud Tools in Moneris Checkout
• Window Size in Moneris Checkout

Tokenization of Credentials with Moneris Checkout

You can configure Moneris Checkout to store a cardholder's credentials in the Moneris Vault and receive a token that represents those credentials for use in future transactions.

If you want to tokenize credentials in Moneris Checkout transactions, you select the Tokenize Card option in the Merchant Resource Center

Fraud Tools in Moneris Checkout

About Fraud Tools in Moneris Checkout

Several tools to mitigate the risk of fraud are available for transactions in Moneris Checkout, including:

• AVS
• CVD
• 3-D Secure
• Kount

To select which of these tools to use when performing transactions with Moneris Checkout, go to your Moneris Checkout configurator in the Moneris Merchant Resource Center under the Payment Security section.

NOTE: CVD is always enabled as a fraud tool and will be performed on each transaction request in Moneris Checkout, but you can choose whether Moneris will treat the CVD result as a mandatory or optional factor to approve or deny the transaction.

Kount as a Fraud Tool in Moneris Checkout

If you select Kount as a fraud tool in Moneris Checkout and your company has its own Enterprise service account from Kount, you will need to include your Kount Merchant ID, Kount API Key and Kount Website ID when you configure your Moneris Checkout store in the Merchant Resource Center.

If you are using Moneris' basic fraud service package and do not have your own Kount enterprise account, you do not require this information.

Fraud Tools and Auto Decision-Making

Moneris Checkout can be configured to automatically proceed with or deny transactions as a result of a risk assessment it makes based on the responses it receives from the selected fraud tools.

When you check the box for auto decision-making, you also can choose whether each fraud tool's analysis will be treated by Moneris as an optional or mandatory factor in the decision to approve or deny the transaction.

This information applies to all fraud tools with the following exception:

• 3-D Secure, which is always mandatory if enabled

Window Size in Moneris Checkout

You can customize the appearance of the Moneris Checkout window presented to the customer on their web browser, including how much of the browser window will be taken up by Moneris Checkout.

The default sizing behaviour of the Moneris Checkout window is full-screen, i.e., Moneris Checkout fills the entire web page. You can alter this behaviour to present the customer with a windowed view instead.

If you do not use the full-screen option, you must define the size of the <div> for the windowed view.
For more information, see the Client-Side Checkout Page section.

You configure the sizing along with other aspects of the Moneris Checkout window in the Merchant Resource Center.

Transaction Process Overview

Client-Side Checkout Page

In order to prepare your client-side checkout page for interacting with Moneris Checkout, you need to do a few tasks first:

1. Add a call to the Moneris Checkout JavaScript library in a <script> tag:
   
   Test
   
   <script src="https://gatewayt.moneris.com/chkt/js/chkt_v1.00.js">
   
   Production
   
   <script src="https://gateway.moneris.com/chkt/js/chkt_v1.00.js">
   
   
2. Create a <div> in the HTML:
   
   <div id="monerisCheckout"></div>
   
   (Optional): If you are not using the "Full screen" window sizing option, you will need to define the size of your window by creating another <div> around this one, for example:
   <div id="outerDiv" style="width:400px"; height"300px">
<div id="monerisCheckout"></div>
</div>
   
   
3. Instantiate the monerisCheckout object and set it up:
   
   var myCheckout = new monerisCheckout();
myCheckout.setMode("qa");
myCheckout.setCheckoutDiv("monerisCheckout");
   
   
4. Set callbacks in JavaScript:
   
   myCheckout.setCallback("page_loaded", myPageLoad);
myCheckout.setCallback("cancel_transaction", myCancelTransaction);
myCheckout.setCallback("error_event", myErrorEvent);
myCheckout.setCallback("payment_receipt", myPaymentReceipt);
myCheckout.setCallback("payment_complete", myPaymentComplete);

For more information about callbacks in Moneris Checkout, see Handling Callbacks.

Preload Request

The Preload request is the means by which a Moneris Checkout instance is securely generated at transaction time. It involves a server-to-server post using the JSON format.

The response to the Preload request returns a ticket number which uniquely identifies the instance and must be passed in the JavaScript monerisCheckout.startCheckout(ticket #) request in order to display the Moneris Checkout page in the browser.

In your server implementation, use the following Moneris Checkout URLs to post to, depending on the development stage:

Testing:
https://gatewayt.moneris.com/chkt/request/request.php

Production:
https://gateway.moneris.com/chkt/request/request.php

JSON structure overview for Preload request

{
   "store_id":"moneris",
   "api_token":"hurgle",
   "checkout_id":"chkt5BF66neris",
   "txn_total":"452.00",
   "environment":"qa",
   "action":"preload",
   "order_no":"",
   "cust_id":"chkt - cust - 0303",
   "dynamic_descriptor":"dyndesc",
   "language":"en",
   "recur":{
      "bill_now":"true",
      "recur_amount":"1.00",
      "start_date":"2020-1-1",
      "recur_unit":"month",
      "recur_period":"1",
      "number_of_recurs":"10"
   },
   "cart":{
      "items":[
         {
            "url":"https:\/\/example.com\/examples\/item1.jpg",
            "description":"One item",
            "product_code":"one_item",
            "unit_cost":"100.00",
            "quantity":"1"
         },
         {
            "url":"https:\/\/example.com\/examples\/item2.jpg",
            "description":"Two item",
            "product_code":"two_item",
            "unit_cost":"200.00",
            "quantity":"1"
         },
         {
            "url":"https:\/\/example.com\/examples\/item3.jpg",
            "description":"Three item",
            "product_code":"three_item",
            "unit_cost":"100.00",
            "quantity":"1"
         }
      ],
      "subtotal":"400.00",
      "tax":{
         "amount":"52.00",
         "description":"Taxes",
         "rate":"13.00"
      }
   },
   "contact_details":{
      "first_name":"bill",
      "last_name":"smith",
      "email":"test@moneris.com",
      "phone":"4165551234"
   },
   "shipping_details":{
      "address_1":"1 main st",
      "address_2":"Unit 2012",
      "city":"Toronto",
      "province":"ON",
      "country":"CA",
      "postal_code":"M1M1M1"
   },
   "billing_details":{
      "address_1":"1 main st",
      "address_2":"Unit 2000",
      "city":"Toronto",
      "province":"ON",
      "country":"CA",
      "postal_code":"M1M1M1"
   }
}

Request fields for Preload request – Required

Optional Preload Request Variables

Optional Objects for Preload Requests in Moneris Checkout

Moneris Checkout also allows you to send optional objects in the Preload request that reflect additional information entered by the customer at checkout, enable additional features, or meet transaction processing requirements.

If you have configured Moneris Checkout to handle these additional items, you do not send the corresponding object in the Preload request. Only send these optional objects if you are using your own ecommerce page to collect them separately from Moneris Checkout.

Preload Request with Recurring Billing

Optional object

Include this object in Preload request to indicate the start of a series of Recurring Billing transactions that will be managed by Moneris.

Top level object field

recur

Preload Request with Shopping Cart

Optional object

The shopping cart object can contain multiple items (each item is represented as its own array within the Shopping Cart object).

Top level field

cart

Required Variables for Shopping Cart

Preload Request with Contact Details

Optional object

Top Level Field

contact_details

Required Variables for Contact Details Object

Preload Request with Shipping Details

Optional object

Top Level Field

shipping_details

Required Variables for Shipping Details Object

Preload Request with Billing Details

Optional object

Top Level Field

billing_details

Required Variables for Billing Details Object

Response to Preload Request

//Successful Preload
{
    "response":{
       "success":"”true”",
       "ticket":"1585G9G9GIKKGGGIGIOG09G9OGKGJFKFJFNjuit8g9"
    }
}

//Failed Preload
{
    "response":{
       "success":"”false”",
       "error":{
          "billing_details":{
             "data":"”billing address must be set when AVS is enabled”"
          }
       }
    }
}

Response Fields – Response to Preload Request

Displaying in the Browser

When a customer goes to check out their items for purchase, the Moneris Checkout page is displayed in the <div> tag you created on your web site

To insert the Moneris Checkout instance into the <div>, you call the JavaScript function:

monerisCheckout.startCheckout([ticket #])

Handling Callbacks

Callbacks are the means by which Moneris Checkout communicates with your merchant checkout page. All callbacks include a single parameter defined as a JSON-formatted string.

In order to handle callbacks, you need to create JavaScript functions that receive the callbacks being sent by Moneris Checkout when the events occur. These functions are linked to the callbacks you set earlier when you prepared your site's checkout page, as described in the Client-Side Checkout Page section.

Callback Types

These callbacks are required to be included in the JavaScript of your page:

• Page Loaded
• Cancel Transaction
• Error Event
• Payment Receipt
• Payment Complete

Callback Response Fields

Page Loaded

Callback Use

To get the page loaded status of the Moneris Checkout page.

This callback is called once the Moneris Checkout is loaded.

JavaScript Set Method for Callback

myCheckout.setCallback("page_loaded",myPageLoad);

JSON Response Message Format

{
    "handler":"page_loaded",
    "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
    "response_code":"001"
}
            

Cancel Transaction

Callback Use

This callback is called in the event the cardholder presses the cancel button in Moneris Checkout.

Standard is to call the closeCheckout() method to close the Moneris Checkout <div>.

The closeCheckout() method will need to be called and a new Preload request will be required in order to initiate a new Moneris Checkout instance.

JavaScript Set Method for Callback

myCheckout.setCallback("cancel_transaction",myCancelTransaction);

JSON Response Message Format

{
    "handler":"cancel_transaction",
    "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
    "response_code":"001"
}
            

Error Event

Callback Use

When an error occurs during the checkout process. This requires the Moneris Checkout session to be closed using the closeCheckout() function

To attempt the transaction again, a new Preload request must be sent to the Moneris Checkout server in order to get a new transaction ticket number.

JavaScript Set Method for Callback

myCheckout.setCallback("error_event",myErrorEvent);

JSON Response Message Format

{
    "handler":"error_event",
    "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
    "response_code":"902"
}
            

Payment Receipt

Callback Use

Transaction is complete and receipt is ready to be collected.

If you have chosen to have Moneris Checkout generate the receipt, this callback is called once the Moneris Checkout displays the transaction receipt.

Please note that if you have chosen Moneris Checkout not to generate a receipt, this callback will not be called. Please refer Payment Complete callback to know when to obtain the receipt response for the transaction.

JavaScript Set Method for Callback

myCheckout.setCallback("payment_receipt",myPaymentReceipt);

JSON Response Message Format

{
    "handler": "payment_receipt",
    "ticket": "1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
    "response_code": "001"
}
            

Payment Complete

Callback Use

This callback is called once Moneris Checkout has completed payment.

If you have chosen Moneris Checkout to generate a receipt, the cardholder has to return to your Checkout page in order for the callback to be called. Please refer to Payment Receipt callback to know when to obtain the receipt response for the transaction.

Moneris Checkout should be closed by calling the closeCheckout() method

JavaScript Set Method for Callback

myCheckout.setCallback("payment_complete",myPaymentComplete);

JSON Response Message Format

{  
    "handler":"payment_complete",
    "ticket":"1539961059DdrvGG3Yj7rxvMAgvRlc4nqKXF7YjT",
    "response_code":"001"
}
            

Callback Response Codes

Receipt Request

Once the Payment Complete callback has been called, your merchant website can make the server-to-server Receipt Request call in order to obtain the details of the transaction for the receipt and to determine whether the transaction was approved or declined.

In your server implementation, use the following Moneris Checkout URLs to post to, depending on the development stage:

Testing:
https://gatewayt.moneris.com/chkt/request/request.php

Production:
https://gateway.moneris.com/chkt/request/request.php

{
    "store_id":"example_storeId",
    "api_token":"example_apiToken",
    "checkout_id":"example_checkoutId",
    "ticket":"1539966660vfTyEASfnwNrsQqFE8VkMAOcN169zt",
    "environment":"qa",
    "action":"receipt"
}

Request fields for Receipt Request – Required

Response to Receipt Request

Responses to Receipt Requests can contain multiple, nested response objects.

JSON structure overview for Preload request

{
   "response":{
      "success":"true",
      "request":{
         "txn_total":"452.00",
         "cart":{
            "items":[
               {
                  "url":"https:\/\/example.com\/examples\/item1.jpg",
                  "description":"One item",
                  "product_code":"one_item",
                  "unit_cost":"100.00",
                  "quantity":"1"
               },
               {
                  "url":"https:\/\/example.com\/examples\/item2.jpg",
                  "description":"Two item",
                  "product_code":"two_item",
                  "unit_cost":"200.00",
                  "quantity":"1"
               },
               {
                  "url":"https:\/\/example.com\/examples\/item3.jpg",
                  "description":"Three item",
                  "product_code":"three_item",
                  "unit_cost":"100.00",
                  "quantity":"1"
               }
            ],
            "subtotal":"400.00",
            "tax":{
               "amount":"52.00",
               "description":"Taxes",
               "rate":"13.00"
            }
         },
         "cust_info":{
            "first_name":"bill",
            "last_name":"smith",
            "phone":"4165551234",
            "email":"test@moneris.com"
         },
         "shipping":{
            "address_1":"1 main st ",
            "address_2":"Unit 2000",
            "city":"Toronto",
            "country":"Canada",
            "province":"Ontario",
            "postal_code":"M1M1M1"
         },
         "billing":{
            "address_1":"1 main st ",
            "address_2":"Unit 2000",
            "city":"Toronto",
            "country":"Canada",
            "province":"Ontario",
            "postal_code":"M1M1M1"
         },
         "cc_total":"252.00",
	 "gift":[
	    {
		"balance_remaining":"0.00",
		"Description":"Gift Fixed Reload",
		"first4last4":"************0214",
		"pan":"0211020000001000214",
		"cvd":"123",
		"balance_used":"200.00"
	    }
	 ],
         "cc":{
            "first6last4":"4761735637",
            "expiry":"0121",
            "cardholder":"bill smith"
         },
         "ticket":"1575568715l0pAi0PJRFZaOISm4DHQvigFswDnET ",
         "cust_id":" chkt - cust - 0303",
         "dynamic_descriptor":"dyndesc",
         "order_no":null,
         "eci":"7"
      },
      "receipt":{
         "result":"a",
         "gift":[
            {
               "order_no":"1583250405Ad1BmCSsfHHDeu4_g1",
               "transaction_no":"6198-1583250435590-00157838_15",
               "reference_no":"3276071",
               "response_code":"000",
               "benefit_amount":"200.00",
               "benefit_remaining":"0.00",
               "first6last4":"0211020214"
            }
         ],
         "cc":{
            "order_no":"1572443908zc9cIHRI6aJTwZU",
            "cust_id":null,
            "transaction_no":"5246-0_14",
            "reference_no":"660187030012750100",
            "transaction_code":"00",
            "transaction_type":"200",
            "transaction_date_time":"2019-10-30 09:59:14",
            "corporateCard":"false",
            "amount":"252.00",
            "response_code":"027",
            "iso_response_code":"01",
            "approval_code":"851268",
            "card_type":"V",
            "dynamic_descriptor":"dyndesc",
            "invoice_number":null,
            "customer_code":null,
            "eci":"7",
            "cvd_result_code":"1M",
            "avs_result_code":"M",
            "first6last4":"4761735637",
            "expiry_date":"0121",
            "recur_success":null,
            "issuer_id":"570106735143835",
            "ecr_no":"66018703",
            "batch_no":"275",
            "sequence_no":"010",
            "result":"a",
            "tokenize":{
               "success":"true",
               "firstlast4":"4761***5637",
               "datakey":"lRNJbQUpcsw4qRkd3LpZ5Lpi7",
               "status":"001",
               "message":"Successfully registered CC details."
            },
            "fraud":{
               "cvd":{
                  "decision_origin":"Merchant",
                  "result":"1",
                  "condition":"1",
                  "status":"success",
                  "code":"1M",
                  "details":""
               },
               "avs":{
                  "decision_origin":"Merchant",
                  "result":"1",
                  "condition":"1",
                  "status":"success",
                  "code":"M",
                  "details":""
               },
               "3d_secure":{
                  "decision_origin":"Moneris",
                  "result":"1",
                  "condition":"1",
                  "status":"success",
                  "code":"5",
                  "details":{
                     "VERes":"Y",
                     "PARes":"true",
                     "message":"Successful Payer Authentication",
                     "cavv":"AAACADlzFBchc3F5NHMUEwAAAAA=",
                     "loadvbv":true
                  }
               },
               "kount":{
                  "decision_origin":"Merchant",
                  "result":"2",
                  "condition":"0",
                  "status":"failed_optional",
                  "code":"001",
                  "details":{
                     "responseCode":"001",
                     "message":"Success",
                     "receiptID":"1567780065NjErgHzsUubOkoIA31gaSUtLkxKseT",
                     "result":"D",
                     "error":[
                        "DECLINE when Device Country is not the same as the BIN Country for VISA and MC & Data Collector is present",
                        "DECLINE when the BIN country is not the same as the Billing Country for VISA and MC"
                     ]
                  }
               }
            }
         }
      }
   }
}

Definition of Response Fields – Response to Receipt Request

The following are fields that may be returned in the Response to Receipt Request, shown with nesting

Terminating Instance

To terminate the Moneris Checkout instance, call monerisCheckout.closeCheckout(), for example:

myCheckout.closeCheckout([ticket #]);

Testing MCO Integration

In the testing stage of development:

1. Use the testing Merchant Resource Center at https://esqa.moneris.com/mpg to configure your Moneris Checkout page for testing purposes

2. Use the testing URL for server to server requests:

https://gatewayt.moneris.com/chkt/request/request.php

3. Use the testing JavaScript library:

<script src="https://gatewayt.moneris.com/chkt/js/chkt_v1.00.js"></script>

4. Set up your monerisCheckout object to the testing mode:

myCheckout.setMode("qa");

5. In all Preload requests use the value "qa" for the environment variable

6. In all Preload requests, make sure that you are using the testing version of your credentials for Store ID, API token and Checkout ID

7. In all Receipt requests use the value "qa" for the environment variable

8. In all Receipt requests, make sure that you are using the testing version of your credentials for Store ID, API token and Checkout ID

Moving to Production with MCO

Once you have finished testing your Moneris Checkout integration, do the following to move the integration into production:

1. Ensure that you have duplicated your final testing configuration in your Moneris Checkout production configuration in the production Merchant Resource Center at https://www3.moneris.com/mpg

2. Use the production URL for server to server requests:

https://gateway.moneris.com/chkt/request/request.php

3. Use the production JavaScript library:

<script src="https://gateway.moneris.com/chkt/js/chkt_v1.00.js"></script>

4. Set up your monerisCheckout object to the production mode:

myCheckout.setMode("prod");

5. In all Preload requests use the value "prod" for the environment variable

6. In all Preload requests, make sure that you are using the production version of your credentials for Store ID, API token and Checkout ID

7. In all Receipt requests use the value "prod" for the environment variable

8. In all Receipt requests, make sure that you are using the production version of your credentials for Store ID, API token and Checkout ID