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
< > $ % = ? ^ { } [ ] \
Merchant-defined description sent on a per-transaction basis that will appear on the credit card statement appended to the merchant’s business name
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

num_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
30-character alphanumeric Customer first name
last name

last_name
30-character alphanumeric Customer last name
e-mail

email
255-character alphanumeric Customer email
phone number

phone
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

50-character alphanumeric

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

country
String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
Customer shipping address country
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

50-character alphanumeric

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

country
String

50-character alphanumeric

Note: some special characters are not allowed
< > $ % = ? ^ { } [ ] \
Customer billing address country
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