My Profile_

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

preload request high level

EXAMPLE PRELOAD REQUEST JSON
{
   "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

Variable Name Type and Limits Description
store ID

store_id 		String

10-character alphanumeric 		Unique identifier provided by Moneris upon merchant account set up
API token

api_token 		String

20-character alphanumeric 		Unique alphanumeric string assigned upon merchant account activation
checkout ID

checkout_id 		String

30-character alphanumeric 		Identifies your Moneris Checkout configuration; this is given to you when you configure your page in the Merchant Resource Center
transaction amount

txn_total 		String

10-character decimal

Up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point
 The total dollar amount of the transaction
developmental mode

environment 		String

alphabetic

qa or prod 		Indicates the stage of development you are sending the request for:

testing = qa

production = prod
request type

action 		String

alphabetic

preload or receipt 		Type of request being made to Moneris Checkout server; is either preload or receipt request

Optional Preload Request Variables

Variable Name Type and Limits Description
order number

order_no 		String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \ 		The order number is a unique identifier appended to every financial transaction
customer ID

cust_id 		String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Merchant-defined field that can be used as an identifier
dynamic descriptor

dynamic_descriptor 		String

20-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \

total of 22 characters including
your merchant name
and separator
 Merchant-defined description sent on a per-transaction basis that will appear on the credit card statement appended to the merchant’s business name.

Dependent on the card issuer, the statement will typically show the dynamic descriptor appended to the merchant's existing business name separated by the "/" character; additional characters will be truncated.

Note: The 22-character maximum limit must take the "/" into account as one of the characters
language

language 		String

2-character alphabetic 		Determines which language Moneris Checkout will display information in

Allowable values:

en – English

fr – French

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.

Variable Name Type and Limits Description
Recurring Billing

recur 		Object

N/A 		Contains fields related to Recurring Billing
Shopping Cart

cart 		Object

N/A 		The virtual shopping cart and its contents
Contact Details

contact_details 		Object

N/A 		Customer contact information
Shipping Details

shipping_details 		Object

N/A 		Customer shipping information
Billing Details

billing_details 		Object

N/A 		Customer billing information

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

Variable Name Type and Limits Description
number of recurs

number_of_recurs		 String

numeric

1-999		 The number of times that the transaction must recur
period

recur_period		 String

numeric

1-999		 Number of recur unit intervals that must pass between recurring billings
recurring amount

recur_amount		 String

10-character decimal, minimum three digits

Up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point		 Dollar amount of the recurring transaction

This amount will be billed on the start date, and then billed repeatedly based on the interval defined by period and recur unit
recur unit

recur_unit		 String

day, week, month or eom		 Unit to be used as a basis for the interval

Works in conjunction with the period variable to define the billing frequency
start date

start_date		 String

YYMMDD format		 Date of the first future recurring billing transaction; this must be a date in the future

If an additional charge will be made immediately, the start now variable must be set to true
bill now

bill_now 		String

true or false 		Set to true if a charge will be made against the card immediately; otherwise set to false

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

Variable Name Type and Limits Description
shopping cart items

items		 Object

sub-object containing arrays, nested within cart

contains following items in blue		 Encapsulates the entire array of items in the shopping cart
URL

items.url		 String

alphanumeric		 URL that corresponds to the image Moneris Checkout shopping cart item
description

items.description		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \		 Describes the item in the shopping cart
product code

items.product_code		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 The SKU for the item
unit cost

items.unit_cost		 String

10-character decimal

Up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point
EXAMPLE: 1234567.89		 Per-unit cost of the item
quantity

items.quantity		 String

numeric

6 characters maximum		 Number of individual instances of the given item in the shopping cart
subtotal

subtotal		 String

10-character decimal

Up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point
EXAMPLE: 1234567.89		 Total dollar amount of the shopping cart before taxes
tax

tax		 Object

sub-object nested within cart

contains following items in blue		 Contains items related to taxes
tax amount

tax.amount		 String

10-character decimal

Up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point
EXAMPLE: 1234567.89		 Dollar amount of taxes
tax description

tax.description		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \		 Describes type of tax being applied
tax rate

tax.rate		 String

Must be a numer wth up to 3 decimal places
EXAMPLE: xx or xx.x or xx.xx or xx.xxx 		Percentage tax rate charged

Preload Request with Contact Details

Optional object

Top Level Field

contact_details

Required Variables for Contact Details Object

Variable Name Type and Limits Description
first name

first_name		 String
30-character alphanumeric
 Customer first name
last name

last_name		 String
30-character alphanumeric
 Customer last name
e-mail

email		 String
255-character alphanumeric
 Customer email
phone number

phone		 String
30-character alphanumeric
 Customer phone number

Preload Request with Shipping Details

Optional object

Top Level Field

shipping_details

Required Variables for Shipping Details Object

Variable Name Type and Limits Description
shipping address line 1

address_1		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Customer shipping address
shipping address line 2

address_2		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Customer shipping address
shipping city

city		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Customer shipping address city
shipping province

province		 String

3-character alphanumeric
 Customer shipping address province
Country subdivision ISO 3166-2
shipping country

country		 String

3-character alphanumeric
 Customer shipping address country
ISO 3166-1 alpha-2
shipping postal code

postal code		 String

20-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Customer shipping address postal code

Preload Request with Billing Details

Optional object

Top Level Field

billing_details

Required Variables for Billing Details Object

Variable Name Type and Limits Description
billing address line 1

address_1		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \		 Customer billing address
billing address line 2

address_2		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Customer billing address
billing city

city		 String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Customer billing address city
billing province

province		 String

3-character alphanumeric
Customer shipping address province
Country subdivision ISO 3166-2
billing country

country		 String

3-character alphanumeric
 Customer shipping address country
ISO 3166-1 alpha-2
billing postal code

postal code		 String

20-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
 Customer billing address postal code

Response to Preload Request

Example Preload Response

//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

Variable Name Description
response

"response":{ 		Top level response object
 success

 "success": 		Denotes whether the Preload request was successful
 ticket

 "ticket": 		Identifies the specific Moneris Checkout instance

Only returned if success = true
 error

 "error":{ 		Sub-object that encapsulates all errors that occurred as a result of the Preload request

Only returned if success = false
  data

  "data": 		Describes the specific type of error that occurred as a result of some aspect of the Preload request