---
updatedAt: 2026-09-01T23:57:49.000Z
---
# 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 documented below.
The response to the Preload request returns a ticket number which uniquely identifies the instance and must be passed in the JavaScript request in order to display the Moneris Checkout page in the browser.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "Moneris Checkout API",
"description": "API Reference for Moneris Checkout Integration (Preload and Receipt requests). This specification uses a unified schema design optimized for compatibility with ReadMe.com's API Designer.",
"version": "1.0.18",
"contact": {
"email": "clientintegrations@moneris.com"
}
},
"servers": [
{
"url": "https://gatewayt.moneris.com/chktv2/request",
"description": "Testing Server"
},
{
"url": "https://gateway.moneris.com/chktv2/request",
"description": "Production Server"
}
],
"paths": {
"/request.php": {
"post": {
"summary": "Preload Request",
"description": "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 documented below.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"store_id": {
"type": "string",
"description": "Unique identifier provided by Moneris upon merchant account set up."
},
"api_token": {
"type": "string",
"description": "Unique alphanumeric string assigned upon merchant account activation."
},
"checkout_id": {
"type": "string",
"description": "Identifies your Moneris Checkout configuration; this is given to you when you configure your page in the Merchant Resource Center."
},
"txn_total": {
"type": "string",
"description": "The total dollar amount of the transaction."
},
"environment": {
"type": "string",
"description": "Indicates the stage of development you are sending the request for:\n\ntesting = qa\n\nproduction = prod",
"enum": [
"qa",
"prod"
]
},
"action": {
"type": "string",
"description": "Type of request being made to Moneris Checkout server; is either preload or receipt request.",
"enum": [
"preload",
"receipt"
],
"default": "preload"
},
"order_no": {
"type": "string",
"description": "The order number is a unique identifier appended to every financial transaction.\n\n50-character alphanumeric with some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"cust_id": {
"type": "string",
"description": "Merchant-defined field that can be used as an identifier. Searchable from the Moneris Merchant Resource Center.\n\n50-character alphanumeric with some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"data_key_format": {
"type": "string",
"description": "2-character alphanumeric string that specifies the data key format being returned. If left blank, data key format will default to 25-character alphanumeric.\n\nNOTE: If the request uses a format with uniqueness, indicated by suffix [U], any attempt to tokenize a card that is already stored under this merchant account will return the existing token instead of a new token.\n\nPossible values:\n - 0 = 25 character alphanumeric data key.\n - 0U = 0 = unique 25 character alphanumeric data key.\n - 1 = first 6, last 4 from card number.\n - with random characters between. Preserves card length.\n - 1U = first 6, last 4 from card number with random characters between. Preserves card length. Unique.\n - 2 = first 6, last 4 from card number with random characters between. Does not preserve card length.\n - 2U = first 6, last 4 from card number with random characters between. Does not preserve card length. Unique.\n- 4U = first 6, last 4 from card number. 7th character is random alpha, others between are random. Forces 16 character length. Unique.\n",
"enum": [
"0",
"0U",
"1",
"1U",
"2",
"2U",
"4U"
]
},
"dynamic_descriptor": {
"type": "string",
"description": "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.\n\nNOTE: The 22-character maximum limit must take the \"/\" into account as one of the characters.\n\n20-character alphanumeric total of 22 characters including your merchant name and separator.\n\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"language": {
"type": "string",
"description": "Determines which language Moneris\nCheckout will display information in.",
"enum": [
"en",
"fr"
]
},
"data_key": {
"type": "string",
"description": "25-character alphanumeric unique identifier for a Vault profile, and used in future Vault financial transactions to associate a transaction with that profile Data key is generated by Moneris and returned to you in the Receipt object when the profile is first registered.\n\nNOTE: Only send this field with Vault Card Update, or else the Preload request will be rejected; this feature is only available when the Preload transaction type sent is a Card Verification.\n"
},
"ask_cvv": {
"type": "string",
"enum": [
"Y",
"N"
],
"description": "When set to Y, Moneris Checkout will prompt the cardholder to enter their CVV when they select a payment card that has been stored as a token.\n\nNOTE: This field is only applicable when sending the Token object."
},
"recur": {
"type": "object",
"properties": {
"number_of_recurs": {
"type": "string",
"description": "The number of times that the transaction must recur.\n\nNumeric: 1-999"
},
"recur_period": {
"type": "string",
"description": "Number of recur unit intervals that must pass between recurring billings.\n\nNumeric: 1-999"
},
"recur_amount": {
"type": "string",
"description": "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.\n\n10-character decimal, minimum three digits. Up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point.\nEg. 1234567.89"
},
"recur_unit": {
"type": "string",
"description": "Unit to be used as a basis for the interval Works in conjunction with the period variable to define the billing frequency.\n",
"enum": [
"day",
"week",
"month",
"eom"
]
},
"start_date": {
"type": "string",
"description": "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. If recur_internal = EOM, then start_date must have a valid date entered.\n\nYYYY/MM/DD or YYYY-MMDD format\n"
},
"bill_now": {
"type": "string",
"description": "Set to true if a charge will be made against the card immediately; otherwise set to false.",
"enum": [
"true",
"false"
]
}
},
"description": "Contains fields related to Recurring Billing."
},
"cart": {
"type": "object",
"description": "The virtual shopping cart and its contents.",
"properties": {
"items": {
"type": "array",
"items": {
"properties": {
"url": {
"type": "string",
"description": "URL that corresponds to the image of the Moneris Checkout shopping cart item."
},
"description": {
"type": "string",
"description": "Describes the item in the shopping cart.\n\n200-character alphanumeric."
},
"product_code": {
"type": "string",
"description": "The SKU for the item.\n\n50-character alphanumeric.\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"unit_cost": {
"type": "string",
"description": "Per-unit cost of the item.\n\n10-character decimal. Up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point\nEg: 1234567.89"
},
"quantity": {
"type": "string",
"description": "Number of individual instances of the given item in the shopping cart.\n\nNumeric. 6 characters maximum"
}
},
"type": "object"
},
"description": "Encapsulates the entire array of items in the shopping cart."
},
"subtotal": {
"type": "string",
"description": "Total dollar amount of the shopping cart, before taxes.\n\n10-character decimal up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point.\nEg. 1234567.89"
},
"tax": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Dollar amount of taxes.\n\n10-character decimal up to 7 digits (dollars) + decimal point (.) + 2 digits (cents) after the decimal point.\nEg: 1234567.89"
},
"description": {
"type": "string",
"description": "Describes type of tax being applied. \n\n50-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"rate": {
"type": "string",
"description": "Percentage tax rate charged.\n\nMust be a number with up to 3 decimal places.\nEg: xx or xx.x or xx.xx or xx.xxx"
}
},
"description": "Contains information related to taxes charged on the items in the shopping cart"
}
}
},
"contact_details": {
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "Customer first name.\n\n30-character alphanumeric"
},
"last_name": {
"type": "string",
"description": "Customer last name.\n\n30-character alphanumeric"
},
"email": {
"type": "string",
"description": "Customer email.\n\n255-character alphanumeric"
},
"phone": {
"type": "string",
"description": "Customer phone number.\n\n30-character alphanumeric"
},
"allow_edit": {
"type": "string",
"description": "Controls customer edits of customer detail fields displayed within the Checkout frame. Optional field.",
"default": "N",
"enum": [
"Y",
"N"
]
}
},
"description": "Customer contact information. This object is returned in the Response to Receipt Request as the Customer Information response object (cust_info)."
},
"shipping_details": {
"type": "object",
"properties": {
"address_1": {
"type": "string",
"description": "Customer shipping address.\n\n50-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"address_2": {
"type": "string",
"description": "Customer shipping address.\n\n50-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"city": {
"type": "string",
"description": "Customer shipping address city. \n\n50-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"province": {
"type": "string",
"description": "Customer shipping address province.\n\n2-character alphanumeric, Country subdivision ISO 3166-2"
},
"country": {
"type": "string",
"description": "Customer shipping address country.\n\n2-character alphanumeric, ISO 3166-1 alpha-2"
},
"postal_code": {
"type": "string",
"description": "Customer shipping address postal code.\n\n20-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\\n"
},
"allow_edit": {
"type": "string",
"description": "Controls customer edits of shipping detail fields displayed within the Checkout frame. Optional field.\n",
"enum": [
"Y",
"N"
],
"default": "N"
}
},
"description": "Customer shipping information."
},
"billing_details": {
"type": "object",
"properties": {
"address_1": {
"type": "string",
"description": "Customer billing address.\n\n50-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"address_2": {
"type": "string",
"description": "Customer billing address.\n\n50-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"city": {
"type": "string",
"description": "Customer billing address city. \n\n50-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"province": {
"type": "string",
"description": "Customer billing address province \n\n2-character alphanumeric, Country subdivision ISO 3166-2"
},
"country": {
"type": "string",
"description": "Customer billing address country\n\n2-character alphanumeric, ISO 3166-1 alpha-2"
},
"postal_code": {
"type": "string",
"description": "Customer billing address postal code.\n\n20-character alphanumeric\nNOTE: Some special characters are not allowed:\n< > $ % = ? ^ \" { } [ ] \\"
},
"allow_edit": {
"type": "string",
"description": "Controls customer edits of shipping detail fields displayed within the Checkout frame. Optional field",
"enum": [
"Y",
"N"
],
"default": "N"
}
},
"description": "Customer billing information."
},
"token": {
"type": "array",
"description": "Array object containing between 1 to 3 pairs of a unique data key and an associated issuer ID, each pair representing an instance of a payment card stored in the Moneris Vault; used for Pay By Token transactions.",
"items": {
"properties": {
"data_key": {
"type": "string",
"description": "Unique identifier for a Vault profile, and used in future Vault financial transactions to associate a transaction with that profile.\n\nData key is generated by Moneris and returned to you in the Receipt object when the profile is first registered.\n\n25-character alphanumeric.\n"
},
"issuer_id": {
"type": "string",
"description": "Unique identifier for the cardholder's stored credentials.\n\nSent back in the response from the card brand when processing a Credential on File transaction.\n\nIf the cardholder's credentials are being stored for the first time, and the issuer ID was returned in the response, you must save the issuer ID on your system to use in subsequent Credential on File transactions (applies to merchant-initiated transactions only).\n\nThe issuer ID must be saved to your systems when returned from Moneris Gateway in the response data, regardless if the value was received or not.\n\nAs a best practice, if the issuer ID is not returned and you received a value of NULL instead, store that value and send it in the subsequent transaction."
}
},
"type": "object"
}
},
"kount_udf": {
"type": "object",
"properties": {
"variable_name_here": {
"type": "string",
"description": "The value for the merchant-defined custom field corresponding to Kount User Defined Field data.\n\nA maximum of 14 fields (pairs of key/- values) are allowed in the preload.\n\n28-character alphanumeric for the key. Must begin with an alpha character.\n255-character alphanumeric for the value\nNOTE: disallowed characters:\n< > $ % = \\? ^ { } [ ] \""
}
},
"description": "Object containing between 1 and 14 pairs of key/values representing Kount User Defined Fields (UDFs). Only available to merchants using Kount Enterprise. \n\nThese UDFs are custom attribute key/value pairs passed to Moneris Checkout during the preload. Moneris Checkout will forward UDFs to Kount as part of risk inquiry. If you are intending to pass this additional UDF data to Kount, you must also create appropriate \"label\" entries in your Kount Agent Web Console (AWC) before passing any values in preload requests. Only pre-configured fields will appear in the portal and be available for review."
}
},
"required": [
"store_id",
"api_token",
"checkout_id",
"txn_total",
"environment",
"action"
]
},
"examples": {
"Preload Request with AVS, CVD and 3DS configured": {
"summary": "Preload Request with AVS, CVD and 3DS configured",
"value": {
"store_id": "store2",
"api_token": "yesguy",
"checkout_id": "chktLHJMN03650",
"txn_total": "50.00",
"environment": "qa",
"action": "preload",
"token": [
{
"data_key": "abc123datakey1",
"issuer_id": "645sddfvdrt4tefd"
},
{
"data_key": "abc123datakey2",
"issuer_id": "645sddfvdrt4tefd"
},
{
"data_key": "abc123datakey3",
"issuer_id": "645sddfvdrt4tefd"
}
],
"ask_cvv": "Y",
"order_no": "Test1234",
"cust_id": "chkt- cust- 0303",
"dynamic_descriptor": "dyndesc",
"language": "en",
"shipping_amount": "200.00",
"recur": {
"bill_now": "true",
"recur_amount": "1.00",
"start_date": "2021-11-21",
"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/item1.jpg",
"description": "two item",
"product_code": "two_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"
},
"kount_udf": {
"CUSTOM_1": "TEST",
"DAYOFWEEK": "Wednesday",
"SHIPFROMPOSTALCODE": "M1M1M1"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful request processing",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "object",
"properties": {
"success": {
"type": "string",
"description": "Denotes whether the Preload request was successful."
},
"ticket": {
"type": "string",
"description": "Identifies the specific Moneris Checkout instance.\n\nOnly returned if success = true"
},
"error": {
"type": "object",
"properties": {
"data": {
"type": "string",
"description": "Describes the specific type of error that occurred as a result of some aspect of the Preload request."
}
},
"description": "Sub-object that encapsulates all errors that occurred as a result of the Preload request.\n\nOnly returned if success = false"
}
},
"description": "Top level response object."
}
},
"required": [
"response"
]
},
"examples": {
"OK": {
"summary": "OK",
"value": {
"response": {
"success": "true",
"ticket": "1585G9G9GIKKGGGIGIOG09G9OGKGJFKFJFNjuit8g9"
}
}
},
"Validation Failed": {
"summary": "Validation Failed",
"value": {
"response": {
"success": "false",
"error": {
"billing_details": {
"data": "billing address must be set when AVS is enabled"
}
}
}
}
},
"Missing Billing Details for AVS request": {
"summary": "Missing Billing Details for AVS request",
"value": "\"response\": {\n \"success\": \"false\",\n \"error\": {\n \"billing_details\": {\n \"data\": \"billing address must be set when AVS is enabled\"\n },\n \"recur\": {\n \"start_date\": \"Invalid date\"\n }\n }\n}\n}"
}
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {}
}
}
},
"description": "Bad Request"
}
},
"parameters": [],
"operationId": "post_preload"
}
}
},
"x-readme": {
"explorer-enabled": false
}
}
```