My Profile_


Hosted Paypage Process Flow

 

Outlined above is the basic Hosted Pay Page flow which allows a cardholder to process a transaction.  There are 2 options available:

  1. This option is for merchants that choose to have the response sent back to them in either a POST or GET format so that they may build the receipt themselves, as well as store the response variables as needed.
  2. This option is for merchants that choose to have Moneris generate the receipt.

 

The steps required to achieve this are as follows:

  1. The customer arrives on the merchant’s website (application). At this point the merchant must determine the amount of the transaction and also collect any additional data.
  2. Once the cardholder is ready to pay, the merchant’s checkout page will submit an HTTP form POST to the Moneris Hosted Pay Page (HPP).  At this time, the customer will be redirected from the merchant’s website to the Moneris Hosted Pay Page URL.  For details on the HTTP form POST, please refer to section 9 of this document which outlines the mandatory and optional fields that may be sent to the Hosted Pay Page.

 

Option A

  1. On the Hosted Pay Page, the cardholder will fill in their secure payment details such as their card number and submit the transaction.  At this time, Moneris will process the transaction and then build a response to send back to the merchant in a POST or GET format to the Response URL provided in the Hosted Pay Page Configuration as described in 7B above.
  2. Once the merchant receives the response details they must provide a receipt to the customer and then may store these details for future purposes such as reporting or tracking.

 

Option B

  1. On the Hosted Pay Page, the cardholder will fill in their secure payment details such as their card number and submit the transaction.  At this time, Moneris will process the transaction and then display a receipt to the customer. 
  2. Once the customer is ready to continue they will then be redirected back to the merchant’s website to Response URL provided in the Hosted Pay Page Configuration as described in 7B above.

Hosted Paypage Credit Card Purchase or Preauthorization

A Purchase verifies funds on the customer’s card, removes the funds and prepares them for deposit into the merchant’s account

Canada Code Sample

<FORM METHOD="POST" ACTION= https://esqa.moneris.com/HPPDP/index.php >

     <INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="AF4Fs1024">

     <INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="Hsjh4GSr4g">

     <INPUT TYPE="HIDDEN" NAME="charge_total" VALUE="1.00">

     <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->

    <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

</FORM>

<!-- Optional Item Details Sample -->
<!--The code below will set the cust_id, order_id, and the lang as well as add gst, pst, hst and shipping cost details for display in the receipt.-->


<input type="hidden" name="cust_id" VALUE="invoice: 123456-12-1">

<input type="hidden" name="order_id" VALUE="oid43333">

<input type="hidden" name="lang" VALUE="fr-ca">

<input type="hidden" name="gst" VALUE="0.80">

<input type="hidden" name="pst" VALUE="0.70">

<input type="hidden" name="hst" VALUE="1.50">

<input type="hidden" name="shipping_cost" VALUE="4.99">

<INPUT TYPE="hidden" name="eci" VALUE="1">



<!-- Shipping and Billing Address Sample -->

<!-- The code below will set the billing and shipping details so they may be stored in the Merchant Resource Centre. Also, depending on the Hosted Pay Page configuration, these fields may also be included in the response and receipt. -->

<INPUT TYPE="HIDDEN" NAME="bill_first_name" VALUE="John">
<INPUT TYPE="HIDDEN" NAME="bill_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="bill_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="bill_address_one" VALUE="101 Main St">
<INPUT TYPE="HIDDEN" NAME="bill_city" VALUE="Smallville">
<INPUT TYPE="HIDDEN" NAME="bill_state_or_province" VALUE="NT">
<INPUT TYPE="HIDDEN" NAME="bill_postal_code" VALUE="Z1Z 1Z1">
<INPUT TYPE="HIDDEN" NAME="bill_country" VALUE="Canada">
<INPUT TYPE="HIDDEN" NAME="bill_phone" VALUE="555-555-5555">
<INPUT TYPE="HIDDEN" NAME="bill_fax" VALUE="555-555-6666">

<INPUT TYPE="HIDDEN" NAME="ship_first_name" VALUE="Jen">
<INPUT TYPE="HIDDEN" NAME="ship_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="ship_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="ship_address_one" VALUE="150 Lakeshore Rd">
<INPUT TYPE="HIDDEN" NAME="ship_city" VALUE="Springfield">
<INPUT TYPE="HIDDEN" NAME="ship_state_or_province" VALUE="IL">
<INPUT TYPE="HIDDEN" NAME="ship_postal_code" VALUE="234567">
<INPUT TYPE="HIDDEN" NAME="ship_country" VALUE="USA">
<INPUT TYPE="HIDDEN" NAME="ship_phone" VALUE="333-555-5555">
<INPUT TYPE="HIDDEN" NAME="ship_fax" VALUE="333-555-6666">



                

Mandatory Values

Variable Name Type Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  Identifies the configuration for the Hosted Pay Page.

hpp_key

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  This is a security key that corresponds to the ps_store_id.

charge_total

hidden

Final purchase Amount - no $, must include 2 decimal places
(i.e. 3.00)

This amount must be higher  than the Convenience Fee Amount


Optional Variables – Transaction Details

Variable Name

Type

Description

cust_id

hidden

This is an ID field that can be used to identify the client, commonly used for student #s, policy #s, client name or invoice #s. Can not be more than 50 chars.

order_id

hidden

MUST be unique per transaction and be no more than 50 chars.
System will generate if excluded.

lang

hidden

This defines what language the Hosted Pay Page and the receipts will be in:

en-ca = English

fr-ca = French

If the tag is not included the hosted Pay Page will default to English.

gst

hidden

This is where you would include Goods and Services Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

pst

hidden

This is where you would include Provincial Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

hst

hidden

This is where you would include Harmonized Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

shipping_cost

hidden

This is where you would include shipping charges, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

note

text

This is any special instructions that you or the cardholder might like to store.  Can not be more than 50 chars.

email

text

Customer’s email address.  This address will be used for the email receipts.   Can not be

more than 50 chars.  If you have chosen to send an email receipt to the cardholder this field must be included.

eci

hidden

If using the Hosted Pay Page to integrate an internal order management system for Mail/Telephone Orders, send an eci value of 1.

If the Hosted Pay Page supports VbV/MCSC, the eci generated by VbV/MCSC will override the value passed in.


Optional Variable - Item Details

Where "n" is an alphanumeric value less than 10 characters long, unique to each item. For each item all five variables should be included. These items will be stored in the Merchant Resource Centre and will be included in the email receipt if “Include Line Item Details” is selected in the Email Receipt Configuration and will be displayed on the payment page if “Display Items Details” is selected in the Appearance Configuration.

Variable Name

Type

Description

idn

hidden

Product Code - SKU (max 10 chars)

descriptionn

hidden

Product Description - (max 15 chars)

quantityn

hidden

Quantity of Goods Purchased - (max - 4 digits)

pricen

hidden

Unit Price - (max - "7"."2" digits, i.e. min 0.00 & max 9999999.99)

subtotaln

hidden

Quantity X Price of Product - (max - "7"."2" digits,

i.e. min 0.00 & max 9999999.99)

 NOTE: you must send a quantityn > 0 or the item will not be added to the item list.


Shipping and Billing Address Variables

Note: Each of the fields below is alphanumeric and can not be more than 30 characters.

Variable Name

Type

ship_first_name

text

ship_last_name

text

ship_company_name

text

ship_address_one

text

ship_city

text

ship_state_or_province

text

ship_postal_code

text

ship_country

text

ship_phone

text

ship_fax

text


Variable Name

Type

bill_first_name

text

bill_last_name

text

bill_company_name

text

bill_address_one

text

bill_city

text

bill_state_or_province

text

bill_postal_code

text

bill_country

text

bill_phone

text

bill_fax

text

Response Fields

Variable Name

Size/Type

Description

response_order_id

50 / an

order_id specified in request or generated by Hosted Pay Page

response_code

3 / an

Transaction Response Code

< 50: Transaction approved

>= 50: Transaction declined

NULL: Transaction was not sent for authorization

 

If you would like further details on the response codes that are returned please see the Response Codes.

date_stamp

yyyy-mm-dd

Processing host date stamp

time_stamp

##:##:##

Processing host time stamp

bank_approval_code

8 / an

Authorization code returned from the issuing institution

result

1 / num

1 = approved ,  0 = declined, incomplete

trans_name

an

Type of transaction that was performed

purchase: cardholder was billed immediately

preauth: funds were locked on the card – a capture will need to be performed to have the funds deposited into merchant’s account (see Merchant Resource Centre User’s Guide).  A PreAuth transaction must be reversed if it is not to be captured. To reverse the full amount of the PreAuth, please use the Capture transaction with a dollar amount of “0.00”.

cavv_purchase: similar to purchase but a VBV/MCSC authentication attempt was made.

cavv_preauth: similar to preauth but a VBV/MCSC authentication attempt was made.

idebit_purchase: similar to purchase but the transaction was performed using INTERAC Online

 

cardholder

40 / an

Cardholder’s name

charge_total

n.nn (2dec)

Amount of the transaction

 

 

 

card

2 / alpha

Credit Card Type

M = Mastercard

V = Visa

AX =  American Express

DC = Diners Card

NO = Novus / Discover

SE = Sears

f4l4

####***####

First 4 and last 4 digits of the card #

message

100 / an

Response description returned from issuing institution or from eSELECTplus if there is a system error.

iso_code

2 / num

ISO response code

bank_transaction_id

18 / num

The reference number is an 18 character string that references the terminal used to process the transaction as well as the shift, batch and sequence number.

This data is typically used to reference transactions on the host systems and must be displayed on any receipt presented to the customer. This information should be stored by the merchant. The following illustrates the breakdown of this field where "660123450010690030” is the reference number returned in the message, "66012345" is the terminal id, "001" is the shift number, "069" is the batch number and "003" is the transaction number within the batch.

 

Moneris Host Transaction identifier

transactionKey

100/an (optional)

This is an encrypted string that is returned when using the transaction verification feature.  There is no need to decrypt the string.  It needs to be passed back to eSELECTplus to verify the authenticity of the transaction.

Ticket

an

The value returned from the preload data request.

rvarn

optional

These extra variables can be sent in the request and will be echoed back in the response. These variables must begin with “rvar” and then contain any alphanumeric string (i.e. rvar1, rvarname, rvarMyVariable). If they are not posted in the request, they will not be included in the response.

eci

1/num

Electronic Commerce Indicator that was sent with the transaction.

Possible values are:

Crypt Type

TVisa/MCSC DefinitionsT

5

- Fully authenticated

- There is a liability shift and the merchant is protected from chargebacks.

6

- VBV/MCSC has been attempted

- VBV -There is a liability shift and the merchant is protected from chargebacks

-MCSV –No liability shift and the merchant is not protected from chargebacks.

7

- Non-VBV/MCSC transaction

- Merchant is no longer protected from chargebacks

txn_num

20/an

Gateway Transaction identifier. This value is required if merchant decides to send automated captures, voids or refunds through an API.

avs_response_code

1/an

Indicates the address verification result.  To test AVS you must create a configuration in “store5” and use that configuration for testing. 

cvd_response_code

1/an

Indicates the CVD validation result. To test CVD you must create a configuration in “store5” and use that configuration for testing.

cavv_result_code

1 / an

The Cardholder Authentication Verification Value (CAVV) is a value that allows VisaNet to validate the integrity of the VbV transaction data.  These values are passed back from the issuer to the merchant after the VbV/SecureCode authentication has taken place.

For example:  If the ECI returned is a “6” and the result code is a "B", it becomes liable for chargeback.  Please see appendix F for the CAVV result codes table

is_visa_debit

boolean

A value of ‘true’ or ‘false’ is sent back which indicates if the card provided by the cardholder was a Visa Debit card.

 


The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Special Error Codes

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur.  The source URL will be included in the error.  Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request.  This may occur if unsupported characters were included in one of the posted fields.   

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information.  The ps_store_id and/or hpp_key did not match an existing store. 

N/A

Card Issuer returned corrupt data.  Unable to proceed with the transaction.  Please return to the site where you initiated the transaction and try again.  Your card has not been charged. – There is no code generated and a blank page is loaded with the above information.  This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.


Convenience Fee Response Codes

Code

Message / Description

Code

Message / Description

973

Unable to locate merchant CF details

977

Invalid amount

978

Failed CF transaction

984

Data error: (optional: field name)

987

Invalid transaction

Null

Error: Malformed XML


Hosted Paypage with Recurring Billing

Verifies funds on the customer’s card, removes the funds and prepares them for deposit into the merchant’s account.Recurring Billing allows you to set up payments whereby Moneris automatically processes the transactions and bills customers on your behalf based on the billing cycle information you provide.

This is often used for subscriptions, memberships or any time a fixed amount is charged at a regular interval. 

Things to consider:

  • To avoid shifting, do not set the start_date after the 28th if the recur_unit is month. To set the billing date for the last day of the month, set recur_unit to eom.

Below is a sample of the HTML to initiate a recurring transaction – this must be sent as part of a basic Hosted Pay Page request that includes: hpp_key, ps_store_id and charge_total.  This transaction will bill the amount sent in charge_total immediately (using the example above charge_total=”1.00”)   Then commencing June 1st 2006 (assuming a date in the future) the card will be billed $4.00 every 2 weeks, 26 times (one year)

Canada Code Sample


<input type="hidden" name=doRecur value ="1"> 
<input type="hidden" name=recurUnit value ="week"> 
<input type="hidden" name=recurStartDate value="2006/06/01">
<input type="hidden" name=recurNum value="26">
<input type="hidden" name=recurStartNow value ='true'>
<input type="hidden" name=recurPeriod value='2'>
<input type="hidden" name=recurAmount value='4.00'>

                

Mandatory Values for Recurring Billing

Variable Name Type

Description

doRecur

hidden

1 = initiate a Recurring transaction, anything else will not initiate a recurring transaction

recurUnit

hidden

Must be “day”, “week” “month” or “eom”.  This is the base unit for the recurring interval.

recurPeriod

hidden

Numeric value.  The period is used in conjunction with recurUnit to determine the interval between payments. 

 

Example: recurUnit= “month” and recurPeriod = “12” the charge will be billed once every twelve months.   If recurUnit= “week” and recurPeriod = “1” the charge will be billed once a week.    If recurUnit = “eom” and recurPeriod = “3” the charge will be billed every 3 months (on the last day of the month).

 

Please note that the total duration of the recurring billing transaction should not exceed 5-10 years in the future.

recurStartDate

hidden

Must be in the format “YYYY/MM/DD” – this determines the date of the first charge.  This date must be in the future – it cannot be the date the transaction is sent (Please see recurStartNow to bill card holder immediately). 

recurStartNow

hidden

“true” / “false”  This will charge the transaction immediately and then initiate recurring billing to commence on the recurStartDate. 

 

Example: to charge a card immediately (assuming the date is May 9 2006) and then bill every month thereafter:

recurStartNow = “true”

recurStartDate = “2006/05/09”  - set the date 1 month after the present

recurUnit = “month”

recurPeriod = “1”

recurAmount

hidden

Amount to charge on a recurring basis - no $, must include 2 decimal places
(i.e. 3.04).  This can vary from the charge_total.  If using recurStartNow charge_total is used for the immediate transaction and recurAmount is used for every transaction in the future. 

 

Example: A member is joining halfway through May 2006 – you would like to bill the remaining half of the month ($20.00) and then bill them on the first day of the month every month for the full month ($40.00) starting June 1st 2006.

charge_total=”20.00”

recurAmount=”40.00”

recurStartNow=”true”

recurStartDate=”2006/06/01”

recurUnit=”month”

recurPeriod=”1”

recurNum

hidden

The number of times to process the recurring charge.   

 

Example:  if you are billing a client monthly for one year recurNum=”12”

 

We advise against setting a period of longer than 5 years.  The suggested maximum should be calculated using your recurUnit and recurPeriod settings over a 5 year period. 

 

Example: If you would like to bill a client indefinitely you should set the recurNum to be approximately 5 years in the future – so if you are billing once a month recurNum=”60” (12 x 5)  or if you are billing every two weeks recurNum = “130” (26 x 5)  

Recur Billing Response Fields

Variable Name

Size/Type

Description

recur_result

true

Indicates the Recurring Billing result.

true: The Recurring Billing transaction was successfully registered

Any response other than “true” indicates that the recurring billing transaction was not properly registered.


Hosted Paypage Process Flow with Data Preload


Outlined above is the Hosted Pay Page flow with the Data Preload feature implemented.

 

The steps required to achieve this are as follows:

  1. The customer arrives on the merchant’s website (application). At this point the merchant must determine the amount of the transaction and also collect any additional data.
  2. Once the cardholder is ready to pay, the merchant’s checkout page will submit an HTTPS POST using a server side programming language to the Moneris Hosted Pay Page (HPP) sending over all of the transaction data. NOTE: the cardholder will not be redirected yet.
  3. The Hosted Pay Page (HPP) will store this transaction data and respond back to the merchant’s site by sending an XML response containing a ticket number.
  4. The merchant’s checkout site will need to collect this response data, and build a new form POST to the Moneris Hosted Pay Page. At this time, the customer will be redirected from the merchant’s website to the Moneris Hosted Pay Page URL.
  5. On the Hosted Pay Page, the cardholder will fill in their secure payment details such as their card number and submit the transaction. At this time, Moneris will process the transaction and build a response.
  6. Once the merchant receives the response details they must provide a receipt to the customer and then may store these details for future purposes such as reporting or tracking.

Hosted Paypage with Data Preload

The Data Preload feature allows merchants to preload transaction data into the Hosted Pay Page through a direct server to server request. The Hosted Pay Page then returns an XML response containing a “ticket”. The ticket is then sent with the ps_store_id through the shopper’s browser in a request to the Hosted Pay Page.  The Hosted Pay Page will then link the preloaded data to the browser request by using the ticket information after which the process will proceed as a regular Hosted Pay Page transaction. In a typical shopping cart checkout experience you must manage and ensure that preload requests correspond to the correct shopper’s browser session.

The Preload Process:

  1. Preload Data Request
  2. Handling the Preload Response
  3. Proceed to Hosted Pay Page
  4. Normal Hosted Pay Page Process

Step 1 – Preload Data Request

The fields below need to be sent via an HTTPS POST using a server side programming language such as .NET, Java, and PHP. Other optional variables could also be passed in this step, such as order ID, customer ID, billing and shipping information, etc.

Mandatory Values

Variable Name

Description

URL’s to POST to

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool

hpp_key

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool

hpp_preload

Blank value. This is used to indicate that the transaction is a preload transaction

charge_total

Amount to charge, must be have 2 decimal places

order_id

(Optional) Merchant defined unique transaction identifier - must be unique for every transaction attempt.

Characters allowed for Order ID: a-z A-Z 0-9 _ - : . @ spaces

Note: only the last 10 characters of the Order ID will appear in the Moneris Merchant Direct report


Step 2 - Handling the Preload Response:

After you send the preload data request to Moneris you will receive an XML response with: the hpp_id, the ticket, the order_no, and the response code. The combination of the hpp_id, ticket, and the order ID will uniquely identify this particular set of preloaded data with what’s stored already on the Moneris side. To make this work you must ensure the shoppers browser session is linked to the correct ticket. A sample of the data preload Response is shown below. 

Data Preload Response values

Variable Name

Description

hpp_id

The ps_store_id is returned as the hpp_id in the XML response.

Variable Name

ticket

The unique value assigned to the preload transaction

order_id

The order_id that was sent in the preload request; if no order id is sent in the preload request then a unique Order ID will be assigned by the Moneris system.

response_code

Transaction Response Code

    < 50: data successfully loaded

    >= 50: data not loaded


Step 3 - Proceed to Hosted Pay Page

Upon receiving confirmation from the user that they are ready to proceed, you would then redirect the shopper via an HTTPS post with the variables below to the Moneris Hosted Pay Page.

Proceed to Hosted Paypage Fields

Variable Name

Description

URL’s to POST to

 

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

hpp_id

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool

hpp_preload

Blank value. This is used to indicate that the transaction is a preload transaction

ticket

A value returned by the preload request which helps identify the transaction

Note: Other optional variables should not be sent, only the above variables should be sent in this request.

Step 4 - Normal Hosted Pay Page Process

At this point the user will reach the Hosted Pay Page where they will enter their credit card information on a secure Moneris website. After the user completes their payment they can then be sent to a merchant generated receipt page and the result of the transaction can be recorded in the merchants order management system (if applicable). If the cardholder does not proceed with charging the credit card at this point then the ticket will become invalid. A new preload request will have to be created if the cardholder wishes to checkout.

Canada Code Sample

A sample of the data preload Response displayed on our server in XML format

Valid Response:
<?xml version="1.0" standalone="yes"?>
<response>
      <hpp_id>4YAHJqa002</hpp_id>
	<ticket>hppEzskxQTZe8DbO80ga</ticket>
	<order_id>hpp_test_1</order_id>
	<response_code>1</response_code>
</response>

Payment Button HTML code sample

<FORM METHOD="POST" ACTION="https://esqa.moneris.com/HPPDP/index.php">
<INPUT TYPE="HIDDEN" NAME="hpp_id" VALUE="4YAHJqa002">
<INPUT TYPE="hidden" NAME="hpp_preload" >
<INPUT TYPE="hidden" NAME="ticket" VALUE="hppEzskxQTZe8DbO80ga">
<INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">
</FORM>

                

Hosted Paypage Process Flow with Asynchronous Transaction Response

Outlined above is the Hosted Pay Page flow with the Asynchronous Transaction Response feature enabled.

 

The steps required to achieve this are as follows:

  1. The customer arrives on the merchant’s website (application). At this point the merchant must determine the amount of the transaction and also collect any additional data.
  2. Once the cardholder is ready to pay, the merchant’s checkout page will submit an HTTP form POST to the Moneris Hosted Pay Page (HPP).  At this time, the customer will be redirected from the merchant’s website to the Moneris Hosted Pay Page URL.  For details on the HTTP form POST, please refer to section 9 of this document which outlines the mandatory and optional fields that may be sent to the Hosted Pay Page.  On the Hosted Pay Page, the cardholder will fill in their secure payment details such as their card number and submit the transaction.  At this time, Moneris will process the transaction and build a response.
  3. Two responses will be sent out
    1. Moneris will perform a server to server POST of the response data to the Async Response URL provided in the Hosted Pay Page Configuration as described in section 7B of this document.
    2. Moneris will also send an additional response back to the merchant in a POST or GET format to the Response URL provided in the Hosted Pay Page Configuration as described in section 7B of this document.  The customer will also be redirected back to the merchant’s website to this same Response URL.
  4.  
    1. Once the merchant receives the Asynch response details they may store these details for future purposes, such as reporting, as well as use it to compare against the response received in step 3B above.
    2. Once the merchant receives the response details they must provide a receipt to the customer and then may store these details for future purposes such as reporting or tracking. They may also at this time compare this response to the one received in step 3A above to verify the accuracy of the data.

Hosted Paypage with Asynchronous Transaction Response

The Asynchronous Transaction Response feature will perform a server to server POST of the response data as a secondary method of getting the response data. This does not replace the normal transaction response which will still be sent through the browser as a POST or a GET. This is a supplementary feature that can be used to verify/validate the browser response. If this feature is enabled in the Hosted Pay Page Configuration this POST will automatically be sent back to the Async Response URL once the transaction processing is complete. Once the merchant receives this response data, it may be used to compare to and verify the original response. Please see below for a sample of the data preload Response displayed on our server in XML format and a sample PHP script used to read the Asynch Transaction Response.

Canada Code Sample

 // sample of the data preload Response displayed on our server in XML format:

xml_response=
<response>
<response_order_id>mhp13150144643p28</response_order_id>
<bank_transaction_id>660035510010258730</bank_transaction_id>
<response_code>025</response_code>
<iso_code>00</iso_code>
<bank_approval_code>784810</bank_approval_code>
<time_stamp>14:47:45</time_stamp>
<date_stamp>2013-05-31</date_stamp>
<trans_name>purchase</trans_name>
<message>APPROVED           * APPROVAL           =</message>
<charge_total>1.00</charge_total>
<cardholder>test</cardholder>
<card_num>3735***5005</card_num>
<card>AX</card>
<expiry_date></expiry_date>
<result>1</result>
</response>

//sample PHP script used to read the Asynch Transaction Response. 

 <?php
// Recieve the response from the Moneris server
$response = $_REQUEST["xml_response"];

/* remove <?xml version=\'1.0\' standalone=\'yes\'?> 
   from the string of XML before trying to parse the XML */ 
$position = strpos($response, "?>");
$length = strlen($response);
$response = substr ($response, $position+2, $length );

// create an array of results
$xml = simplexml_load_string($response);
foreach($xml->children() as $child)
{
	$receipt[$child->getName()] = $child;
}

// Prepare to write the results to the log file
$timestamp = date("H:i:s d/m/y", time());
$results  = $timestamp . "\r\n";
$results  .=  "Response Order ID: " . $receipt["response_order_id"] . "\r\n";
$results  .=  "Bank Transaction ID: " . $receipt["bank_transaction_id"] . "\r\n";
$results  .=  "Response Code: " . $receipt["response_code"] . "\r\n";
$results  .=  "ISO Code: " . $receipt["iso_code"] . "\r\n";
$results  .=  "Bank Approval Code: " . $receipt["bank_approval_code"] . "\r\n";
$results  .=  "Time Stamp: " . $receipt["time_stamp"] . "\r\n";
$results  .=  "Date Stamp: " . $receipt["date_stamp"] . "\r\n";
$results  .=  "Transaction Name: " . $receipt["trans_name"] . "\r\n";
$results  .=  "Message: " . $receipt["message"] . "\r\n";
$results  .=  "Charge Total: " . $receipt["charge_total"] . "\r\n";
$results  .=  "Cardholder Name: " . $receipt["cardholder"] . "\r\n";
$results  .=  "Card Number: " . $receipt["card_num"] . "\r\n";
$results  .=  "Card Type: " . $receipt["card"] . "\r\n";
$results  .=  "Expiry Date(YYMM): " . $receipt["expiry_date"] . "\r\n";
$results  .=  "Result: " . $receipt["result"] . "\r\n";

//write the results to the log file
$logFile = "async_log.txt";
$fh = fopen($logFile, 'a') or die("can't open file");
fwrite($fh, $results);
fclose($fh);


                

Hosted Paypage Process Flow with Transaction Verification


Outlined above is the Hosted Pay Page flow with the Transaction Verification feature enabled.

The steps required to achieve this are as follows:

  1. The customer arrives on the merchant’s website (application). At this point the merchant must determine the amount of the transaction and also collect any additional data.
  2. Once the cardholder is ready to pay, the merchant’s checkout page will submit an HTTP form POST to the Moneris Hosted Pay Page (HPP). At this time, the customer will be redirected from the merchant’s website to the Moneris Hosted Pay Page URL. For details on the HTTP form POST, please refer to section 9 of this document which outlines the mandatory and optional fields that may be sent to the Hosted Pay Page. On the Hosted Pay Page, the cardholder will fill in their secure payment details such as their card number and submit the transaction. At this time, Moneris will process the transaction and build a response.
  3. Moneris will redirect the customer back to the merchant’s website as well as send the response back to the merchant in a POST or GET format to the Response URL provided in the Hosted Pay Page Configuration as described in section 7B of this document.
  4. Once the merchant receives the response details they may provide a receipt to the customer at this time and then may store these details for future purposes such as reporting or tracking.
  5. Once of the fields returned in the response (step #3 above) is the transactionKey. The merchant may now send this transactionKey back to the Moneris Hosted Pay Page using another HTTP form POST. For details on the transaction verification POST, please refer to section 18 below.
  6. Once the Moneris Hosted Pay Page receives this transactionKey it will look up the details we have on file for this transaction and send the amount, response code and message back to the merchant in one of the following formats: POST, GET, key/value pairs, or display XML on our server. This response will be sent to the Transaction Verification Response URL provided in the Hosted Pay Page Configuration as described in section 7B of this document. Note: the merchant may set the Response URL (step 3) and Transaction Verification URL (step 6) to be one and the same or set 2 different URLs.
  7. Once the merchant receives the additional transaction verification response details, they may now display a receipt to the customer (if this was not yet done in step 4 above) and also compare this response to the one received in step 3 above to verify the accuracy of the original response data.

Hosted Paypage with Transaction Verification Request

In order to perform a Transaction Verification it is essential that you configure the Hosted Pay Page accordingly. If the Hosted Pay Page is properly configured you will receive a variable in the GET or POST response called “transactionKey”.  It is advised that you log the initial transaction response and then compare the Transaction Verification response to ensure authenticity.  You can use a redirect (for example, onLoad=”submit”) or any other method to submit the request.  We suggest automating the Transaction Verification and not using a button to submit the information.   Transaction Verification can only be performed once on a given transaction, and it can only be performed within 15 minutes of the original transaction.

Canada Code Sample

//Below is a sample of the transaction Verification Request:

<FORM NAME=VERIFY ACTION="https://esqa.moneris.com/HPPDP/verifyTxn.php">
<INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="qampg">	
<INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="hpPu7yr4Hn5k">
<INPUT TYPE="HIDDEN" NAME="transactionKey" VALUE="SDGJSGI4ujwrlsfGSGsjhlfhs5lsffs4h">
<INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to perform verification">
</FORM>


//Below is a sample of the Transaction Verification Response displayed on our server in XML format

Valid Response:
<?xml version="1.0" standalone="yes"?>
<response>
      <order_id>ord-140708-1705</order_id>
	<response_code>27</response_code>
	<amount>15.00</amount>
	<txn_num>381038-0_7</txn_num>
	<status>Valid-Approved</status>
	<transactionKey>agtA20RwCQ60y3jA49KlaxTMYSQdS4</transactionKey>
</response>

Invalid Response:
<?xml version="1.0" standalone="yes"?>
<response>
	<order_id>ord-140708-1705</order_id>
	<response_code>994</response_code>
	<amount>null</amount>
	<txn_num>381038-0_7</txn_num>
	<status>Invalid-ReConfirmed</status>
	<transactionKey>agtA20RwCQ60y3jA49KlaxTMYSQdS4</transactionKey>
</response>

                

Mandatory Transaction verification request values


Variable Name

Type

Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

hpp_id

hidden

Provided by Moneris Solutions – Hosted Paypage Configuration Tool

hpp_key

hidden

Provided by Moneris Solutions – Hosted Paypage Configuration Tool

transactionKey

hidden

This is returned in the transaction response.


Once Moneris Gateway receives the transaction verification request we decrypt the key, then verify and log the request. A transaction verification response is then returned with the transaction information and a status.  This response is sent in the format, and to the URL, defined in the “Security Features” portion of the Hosted Paypage configuration.  Please see the table below for a list of possible Transaction Verification statuses.

Transaction Verification Response Fields

Variable Name

Size/Type

Description

order_no

50 / an

order_no of the original transaction

response_code

3 / an

Transaction Response Code from the original transaction

< 50: Transaction approved

>= 50: Transaction declined

NULL: Transaction was not sent for authorization

amount

n.nn (2dec)

This is the amount of the original transaction (i.e. min 0.01 & max 9999999.99)

txn_num

20 / an

Gateway Transaction identifier from the original transaction.

message

an

This is the value to check to see if the transaction has been properly validated. Below is a list of possible replies and their meaning.

 

Valid-Approved : The transaction was Approved and successfully validated

Valid-Declined : The transaction was Declined and successfully validated

 Transaction Verification Error Codes

Code

Message / Description

991

Invalid referrer URL - <referrer url>: Referring URL does not match what is listed in the “Security Features” portion of the Hosted Pay Page configuration, validation failed. The source URL will be returned.

994

Invalid – Reconfirmed: The transaction has already been confirmed, validation failed.

995

Invalid: Not a valid confirmation request. Either the transaction doesn’t exist or the request is older than 15 minutes, validation failed.

Error Codes

The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur. The source URL will be included in the error. Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request. This may occur if unsupported characters were included in one of the posted fields.

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information. The ps_store_id and/or hpp_key did not match an existing store.

N/A

Card Issuer returned corrupt data. Unable to proceed with the transaction. Please return to the site where you initiated the transaction and try again. Your card has not been charged. – There is no code generated and a blank page is loaded with the above information. This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.


Hosted Paypage with Convenience Fee

The Convenience Fee program was designed to allow merchants to offer the convenience of an alternative payment channel to the cardholder at a charge. This applies only when providing a true "convenience" in the form of an alternative payment channel outside the merchant's customary face-to-face payment channels. The convenience fee will be a separate charge on top of what the consumer is paying for the goods and/or services they were given, and this charge will appear as a separate line item on the consumer’s statement.

Canada Code Sample

<FORM METHOD="POST" ACTION= https://esqa.moneris.com/HPPDP/index.php >

     <INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="AF4Fs1024">

     <INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="Hsjh4GSr4g">

     <INPUT TYPE="HIDDEN" NAME="charge_total" VALUE="1.00">

     <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->

    <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

</FORM>

<!-- Optional Item Details Sample -->
<!--The code below will set the cust_id, order_id, and the lang as well as add gst, pst, hst and shipping cost details for display in the receipt.-->


<input type="hidden" name="cust_id" VALUE="invoice: 123456-12-1">

<input type="hidden" name="order_id" VALUE="oid43333">

<input type="hidden" name="lang" VALUE="fr-ca">

<input type="hidden" name="gst" VALUE="0.80">

<input type="hidden" name="pst" VALUE="0.70">

<input type="hidden" name="hst" VALUE="1.50">

<input type="hidden" name="shipping_cost" VALUE="4.99">

<INPUT TYPE="hidden" name="eci" VALUE="1">



<!-- Shipping and Billing Address Sample -->

<!-- The code below will set the billing and shipping details so they may be stored in the Merchant Resource Centre. Also, depending on the Hosted Pay Page configuration, these fields may also be included in the response and receipt. -->

<INPUT TYPE="HIDDEN" NAME="bill_first_name" VALUE="John">
<INPUT TYPE="HIDDEN" NAME="bill_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="bill_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="bill_address_one" VALUE="101 Main St">
<INPUT TYPE="HIDDEN" NAME="bill_city" VALUE="Smallville">
<INPUT TYPE="HIDDEN" NAME="bill_state_or_province" VALUE="NT">
<INPUT TYPE="HIDDEN" NAME="bill_postal_code" VALUE="Z1Z 1Z1">
<INPUT TYPE="HIDDEN" NAME="bill_country" VALUE="Canada">
<INPUT TYPE="HIDDEN" NAME="bill_phone" VALUE="555-555-5555">
<INPUT TYPE="HIDDEN" NAME="bill_fax" VALUE="555-555-6666">

<INPUT TYPE="HIDDEN" NAME="ship_first_name" VALUE="Jen">
<INPUT TYPE="HIDDEN" NAME="ship_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="ship_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="ship_address_one" VALUE="150 Lakeshore Rd">
<INPUT TYPE="HIDDEN" NAME="ship_city" VALUE="Springfield">
<INPUT TYPE="HIDDEN" NAME="ship_state_or_province" VALUE="IL">
<INPUT TYPE="HIDDEN" NAME="ship_postal_code" VALUE="234567">
<INPUT TYPE="HIDDEN" NAME="ship_country" VALUE="USA">
<INPUT TYPE="HIDDEN" NAME="ship_phone" VALUE="333-555-5555">
<INPUT TYPE="HIDDEN" NAME="ship_fax" VALUE="333-555-6666">



                

Mandatory Values

Variable Name Type Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  Identifies the configuration for the Hosted Pay Page.

hpp_key

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  This is a security key that corresponds to the ps_store_id.

charge_total

hidden

Final purchase Amount - no $, must include 2 decimal places
(i.e. 3.00)

This amount must be higher  than the Convenience Fee Amount


Optional Variables – Transaction Details

Variable Name

Type

Description

cust_id

hidden

This is an ID field that can be used to identify the client, commonly used for student #s, policy #s, client name or invoice #s. Can not be more than 50 chars.

order_id

hidden

MUST be unique per transaction and be no more than 50 chars.
System will generate if excluded.

lang

hidden

This defines what language the Hosted Pay Page and the receipts will be in:

en-ca = English

fr-ca = French

If the tag is not included the hosted Pay Page will default to English.

gst

hidden

This is where you would include Goods and Services Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

pst

hidden

This is where you would include Provincial Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

hst

hidden

This is where you would include Harmonized Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

shipping_cost

hidden

This is where you would include shipping charges, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

note

text

This is any special instructions that you or the cardholder might like to store.  Can not be more than 50 chars.

email

text

Customer’s email address.  This address will be used for the email receipts.   Can not be

more than 50 chars.  If you have chosen to send an email receipt to the cardholder this field must be included.

eci

hidden

If using the Hosted Pay Page to integrate an internal order management system for Mail/Telephone Orders, send an eci value of 1.

If the Hosted Pay Page supports VbV/MCSC, the eci generated by VbV/MCSC will override the value passed in.


Optional Variable - Item Details

Where "n" is an alphanumeric value less than 10 characters long, unique to each item. For each item all five variables should be included. These items will be stored in the Merchant Resource Centre and will be included in the email receipt if “Include Line Item Details” is selected in the Email Receipt Configuration and will be displayed on the payment page if “Display Items Details” is selected in the Appearance Configuration.

Variable Name

Type

Description

idn

hidden

Product Code - SKU (max 10 chars)

descriptionn

hidden

Product Description - (max 15 chars)

quantityn

hidden

Quantity of Goods Purchased - (max - 4 digits)

pricen

hidden

Unit Price - (max - "7"."2" digits, i.e. min 0.00 & max 9999999.99)

subtotaln

hidden

Quantity X Price of Product - (max - "7"."2" digits,

i.e. min 0.00 & max 9999999.99)

 NOTE: you must send a quantityn > 0 or the item will not be added to the item list.


Shipping and Billing Address Variables

Note: Each of the fields below is alphanumeric and can not be more than 30 characters.

Variable Name

Type

ship_first_name

text

ship_last_name

text

ship_company_name

text

ship_address_one

text

ship_city

text

ship_state_or_province

text

ship_postal_code

text

ship_country

text

ship_phone

text

ship_fax

text


Variable Name

Type

bill_first_name

text

bill_last_name

text

bill_company_name

text

bill_address_one

text

bill_city

text

bill_state_or_province

text

bill_postal_code

text

bill_country

text

bill_phone

text

bill_fax

text

Convenience Fee Response Fields

Variable Name

Size/Type

Description

convenience_fee

7.2 / num

Charge the convenience_fee amount.  Please note the ‘convenience_fee’ must be less than the ‘amount’.

cf_fee_rate

 

9 / decimal

The convenience fee rate that has been defined on the merchant’s profile.  For example:

1.00 – a fixed amount or

10.0 - a percentage amount

cf_fee_type

 

AMT / PCT

The type of convenience fee that has been defined on the merchant’s profile.  Available options are:

AMT – fixed amount

PCT – percentage

cf_success

 

true/false

Indicates whether the Convenience Fee transaction processed successfully.

 


The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Special Error Codes

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur.  The source URL will be included in the error.  Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request.  This may occur if unsupported characters were included in one of the posted fields.   

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information.  The ps_store_id and/or hpp_key did not match an existing store. 

N/A

Card Issuer returned corrupt data.  Unable to proceed with the transaction.  Please return to the site where you initiated the transaction and try again.  Your card has not been charged. – There is no code generated and a blank page is loaded with the above information.  This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.


Convenience Fee Response Codes

Code

Message / Description

Code

Message / Description

973

Unable to locate merchant CF details

977

Invalid amount

978

Failed CF transaction

984

Data error: (optional: field name)

987

Invalid transaction

Null

Error: Malformed XML


Hosted Paypage with Interac Online

When Moneris Gateway receives the transaction request the Hosted Paypage will automatically determine whether INTERAC Online is enabled for your store and create a Payment Option screen. Note that INTERAC Online only supports the Purchase transaction. If your default transaction is PreAuth all credit card transactions will be processed as a PreAuth and will need to be subsequently captured, INTERAC Online transactions will be processed as a Purchase and do not require any further action. Note: For an approved response in the QA environment, you can use the data provided here.

Canada Code Sample

<FORM METHOD="POST" ACTION= https://esqa.moneris.com/HPPDP/index.php >

     <INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="AF4Fs1024">

     <INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="Hsjh4GSr4g">

     <INPUT TYPE="HIDDEN" NAME="charge_total" VALUE="1.00">

     <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->

    <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

</FORM>

<!-- Optional Item Details Sample -->
<!--The code below will set the cust_id, order_id, and the lang as well as add gst, pst, hst and shipping cost details for display in the receipt.-->


<input type="hidden" name="cust_id" VALUE="invoice: 123456-12-1">

<input type="hidden" name="order_id" VALUE="oid43333">

<input type="hidden" name="lang" VALUE="fr-ca">

<input type="hidden" name="gst" VALUE="0.80">

<input type="hidden" name="pst" VALUE="0.70">

<input type="hidden" name="hst" VALUE="1.50">

<input type="hidden" name="shipping_cost" VALUE="4.99">

<INPUT TYPE="hidden" name="eci" VALUE="1">



<!-- Shipping and Billing Address Sample -->

<!-- The code below will set the billing and shipping details so they may be stored in the Merchant Resource Centre. Also, depending on the Hosted Pay Page configuration, these fields may also be included in the response and receipt. -->

<INPUT TYPE="HIDDEN" NAME="bill_first_name" VALUE="John">
<INPUT TYPE="HIDDEN" NAME="bill_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="bill_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="bill_address_one" VALUE="101 Main St">
<INPUT TYPE="HIDDEN" NAME="bill_city" VALUE="Smallville">
<INPUT TYPE="HIDDEN" NAME="bill_state_or_province" VALUE="NT">
<INPUT TYPE="HIDDEN" NAME="bill_postal_code" VALUE="Z1Z 1Z1">
<INPUT TYPE="HIDDEN" NAME="bill_country" VALUE="Canada">
<INPUT TYPE="HIDDEN" NAME="bill_phone" VALUE="555-555-5555">
<INPUT TYPE="HIDDEN" NAME="bill_fax" VALUE="555-555-6666">

<INPUT TYPE="HIDDEN" NAME="ship_first_name" VALUE="Jen">
<INPUT TYPE="HIDDEN" NAME="ship_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="ship_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="ship_address_one" VALUE="150 Lakeshore Rd">
<INPUT TYPE="HIDDEN" NAME="ship_city" VALUE="Springfield">
<INPUT TYPE="HIDDEN" NAME="ship_state_or_province" VALUE="IL">
<INPUT TYPE="HIDDEN" NAME="ship_postal_code" VALUE="234567">
<INPUT TYPE="HIDDEN" NAME="ship_country" VALUE="USA">
<INPUT TYPE="HIDDEN" NAME="ship_phone" VALUE="333-555-5555">
<INPUT TYPE="HIDDEN" NAME="ship_fax" VALUE="333-555-6666">



                

Mandatory Values

Variable Name Type Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  Identifies the configuration for the Hosted Pay Page.

hpp_key

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  This is a security key that corresponds to the ps_store_id.

charge_total

hidden

Final purchase Amount - no $, must include 2 decimal places
(i.e. 3.00)

This amount must be higher  than the Convenience Fee Amount


Optional Variables – Transaction Details

Variable Name

Type

Description

cust_id

hidden

This is an ID field that can be used to identify the client, commonly used for student #s, policy #s, client name or invoice #s. Can not be more than 50 chars.

order_id

hidden

MUST be unique per transaction and be no more than 50 chars.
System will generate if excluded.

lang

hidden

This defines what language the Hosted Pay Page and the receipts will be in:

en-ca = English

fr-ca = French

If the tag is not included the hosted Pay Page will default to English.

gst

hidden

This is where you would include Goods and Services Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

pst

hidden

This is where you would include Provincial Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

hst

hidden

This is where you would include Harmonized Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

shipping_cost

hidden

This is where you would include shipping charges, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

note

text

This is any special instructions that you or the cardholder might like to store.  Can not be more than 50 chars.

email

text

Customer’s email address.  This address will be used for the email receipts.   Can not be

more than 50 chars.  If you have chosen to send an email receipt to the cardholder this field must be included.

eci

hidden

If using the Hosted Pay Page to integrate an internal order management system for Mail/Telephone Orders, send an eci value of 1.

If the Hosted Pay Page supports VbV/MCSC, the eci generated by VbV/MCSC will override the value passed in.


Optional Variable - Item Details

Where "n" is an alphanumeric value less than 10 characters long, unique to each item. For each item all five variables should be included. These items will be stored in the Merchant Resource Centre and will be included in the email receipt if “Include Line Item Details” is selected in the Email Receipt Configuration and will be displayed on the payment page if “Display Items Details” is selected in the Appearance Configuration.

Variable Name

Type

Description

idn

hidden

Product Code - SKU (max 10 chars)

descriptionn

hidden

Product Description - (max 15 chars)

quantityn

hidden

Quantity of Goods Purchased - (max - 4 digits)

pricen

hidden

Unit Price - (max - "7"."2" digits, i.e. min 0.00 & max 9999999.99)

subtotaln

hidden

Quantity X Price of Product - (max - "7"."2" digits,

i.e. min 0.00 & max 9999999.99)

 NOTE: you must send a quantityn > 0 or the item will not be added to the item list.


Shipping and Billing Address Variables

Note: Each of the fields below is alphanumeric and can not be more than 30 characters.

Variable Name

Type

ship_first_name

text

ship_last_name

text

ship_company_name

text

ship_address_one

text

ship_city

text

ship_state_or_province

text

ship_postal_code

text

ship_country

text

ship_phone

text

ship_fax

text


Variable Name

Type

bill_first_name

text

bill_last_name

text

bill_company_name

text

bill_address_one

text

bill_city

text

bill_state_or_province

text

bill_postal_code

text

bill_country

text

bill_phone

text

bill_fax

text

Interac Online Response Fields

Variable Name

Size/Type

Description

Trans_name

An

 

Type of transaction that was performed

idebit_purchase: similar to purchase but the transaction was performed using INTERAC Online

ISSNAME

1-30/an

 

Returned for an INTERAC Online transaction.  This field identifies the name of the card issuer.  This data must be displayed on a receipt.

INVOICE

1-20/an

 

Returned for an INTERAC Online transaction.  This field contains the invoice number used to identify the transaction.  This data must be displayed on the receipt.

 

ISSCONF

1-15/an

 

Returned for an INTERAC Online transaction.  This field is the confirmation number returned by the issuing bank.  This data must be displayed on the receipt.


The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Special Error Codes

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur.  The source URL will be included in the error.  Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request.  This may occur if unsupported characters were included in one of the posted fields.   

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information.  The ps_store_id and/or hpp_key did not match an existing store. 

N/A

Card Issuer returned corrupt data.  Unable to proceed with the transaction.  Please return to the site where you initiated the transaction and try again.  Your card has not been charged. – There is no code generated and a blank page is loaded with the above information.  This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.


Note: For an approved response in the QA environment, you can use the data provided here.


Hosted Paypage with ThreatMetrix

The Transaction Risk Management Tool provides additional information to assist in identifying fraudulent transactions. In order to maximize the benefits from the Transaction Risk Management Tool it is highly recommended that you:

  • Carefully consider the business logic and processes that you need to implement surrounding handling the response information the Transaction Risk Management Tool provides.
  • Also implement the other fraud tools available through eSelectplus (e.g. AVS, CVD, Verified by Visa and MasterCard SecureCode).

Canada Code Sample

<FORM METHOD="POST" ACTION= https://esqa.moneris.com/HPPDP/index.php >

     <INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="AF4Fs1024">

     <INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="Hsjh4GSr4g">

     <INPUT TYPE="HIDDEN" NAME="charge_total" VALUE="1.00">

     <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->

    <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

</FORM>

<!-- Optional Item Details Sample -->
<!--The code below will set the cust_id, order_id, and the lang as well as add gst, pst, hst and shipping cost details for display in the receipt.-->


<input type="hidden" name="cust_id" VALUE="invoice: 123456-12-1">

<input type="hidden" name="order_id" VALUE="oid43333">

<input type="hidden" name="lang" VALUE="fr-ca">

<input type="hidden" name="gst" VALUE="0.80">

<input type="hidden" name="pst" VALUE="0.70">

<input type="hidden" name="hst" VALUE="1.50">

<input type="hidden" name="shipping_cost" VALUE="4.99">

<INPUT TYPE="hidden" name="eci" VALUE="1">



<!-- Shipping and Billing Address Sample -->

<!-- The code below will set the billing and shipping details so they may be stored in the Merchant Resource Centre. Also, depending on the Hosted Pay Page configuration, these fields may also be included in the response and receipt. -->

<INPUT TYPE="HIDDEN" NAME="bill_first_name" VALUE="John">
<INPUT TYPE="HIDDEN" NAME="bill_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="bill_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="bill_address_one" VALUE="101 Main St">
<INPUT TYPE="HIDDEN" NAME="bill_city" VALUE="Smallville">
<INPUT TYPE="HIDDEN" NAME="bill_state_or_province" VALUE="NT">
<INPUT TYPE="HIDDEN" NAME="bill_postal_code" VALUE="Z1Z 1Z1">
<INPUT TYPE="HIDDEN" NAME="bill_country" VALUE="Canada">
<INPUT TYPE="HIDDEN" NAME="bill_phone" VALUE="555-555-5555">
<INPUT TYPE="HIDDEN" NAME="bill_fax" VALUE="555-555-6666">

<INPUT TYPE="HIDDEN" NAME="ship_first_name" VALUE="Jen">
<INPUT TYPE="HIDDEN" NAME="ship_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="ship_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="ship_address_one" VALUE="150 Lakeshore Rd">
<INPUT TYPE="HIDDEN" NAME="ship_city" VALUE="Springfield">
<INPUT TYPE="HIDDEN" NAME="ship_state_or_province" VALUE="IL">
<INPUT TYPE="HIDDEN" NAME="ship_postal_code" VALUE="234567">
<INPUT TYPE="HIDDEN" NAME="ship_country" VALUE="USA">
<INPUT TYPE="HIDDEN" NAME="ship_phone" VALUE="333-555-5555">
<INPUT TYPE="HIDDEN" NAME="ship_fax" VALUE="333-555-6666">



                

Mandatory Values

Variable Name Type Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  Identifies the configuration for the Hosted Pay Page.

hpp_key

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  This is a security key that corresponds to the ps_store_id.

charge_total

hidden

Final purchase Amount - no $, must include 2 decimal places
(i.e. 3.00)

This amount must be higher  than the Convenience Fee Amount


Optional Variables – Transaction Details

Variable Name

Type

Description

cust_id

hidden

This is an ID field that can be used to identify the client, commonly used for student #s, policy #s, client name or invoice #s. Can not be more than 50 chars.

order_id

hidden

MUST be unique per transaction and be no more than 50 chars.
System will generate if excluded.

lang

hidden

This defines what language the Hosted Pay Page and the receipts will be in:

en-ca = English

fr-ca = French

If the tag is not included the hosted Pay Page will default to English.

gst

hidden

This is where you would include Goods and Services Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

pst

hidden

This is where you would include Provincial Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

hst

hidden

This is where you would include Harmonized Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

shipping_cost

hidden

This is where you would include shipping charges, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

note

text

This is any special instructions that you or the cardholder might like to store.  Can not be more than 50 chars.

email

text

Customer’s email address.  This address will be used for the email receipts.   Can not be

more than 50 chars.  If you have chosen to send an email receipt to the cardholder this field must be included.

eci

hidden

If using the Hosted Pay Page to integrate an internal order management system for Mail/Telephone Orders, send an eci value of 1.

If the Hosted Pay Page supports VbV/MCSC, the eci generated by VbV/MCSC will override the value passed in.


Optional Variable - Item Details

Where "n" is an alphanumeric value less than 10 characters long, unique to each item. For each item all five variables should be included. These items will be stored in the Merchant Resource Centre and will be included in the email receipt if “Include Line Item Details” is selected in the Email Receipt Configuration and will be displayed on the payment page if “Display Items Details” is selected in the Appearance Configuration.

Variable Name

Type

Description

idn

hidden

Product Code - SKU (max 10 chars)

descriptionn

hidden

Product Description - (max 15 chars)

quantityn

hidden

Quantity of Goods Purchased - (max - 4 digits)

pricen

hidden

Unit Price - (max - "7"."2" digits, i.e. min 0.00 & max 9999999.99)

subtotaln

hidden

Quantity X Price of Product - (max - "7"."2" digits,

i.e. min 0.00 & max 9999999.99)

 NOTE: you must send a quantityn > 0 or the item will not be added to the item list.


Shipping and Billing Address Variables

Note: Each of the fields below is alphanumeric and can not be more than 30 characters.

Variable Name

Type

ship_first_name

text

ship_last_name

text

ship_company_name

text

ship_address_one

text

ship_city

text

ship_state_or_province

text

ship_postal_code

text

ship_country

text

ship_phone

text

ship_fax

text


Variable Name

Type

bill_first_name

text

bill_last_name

text

bill_company_name

text

bill_address_one

text

bill_city

text

bill_state_or_province

text

bill_postal_code

text

bill_country

text

bill_phone

text

bill_fax

text

ThreatMetrix Response Fields

Variable Name

Size/Type

Description

risk_policy_score

 

The sum of all the risks weights from triggered rules within the selected policy in the range [-100…+100].

risk_request_result

 

success – ThreatMetrix was able to process the request successfully

fail_access – ThreatMetrix was unable to process the request due to API verification failing

fail_verification – API query limit reached

fail_incomplete – ThreatMetrix was unable to process the request due to incomplete or incorrect input data

fail_internal_error – ThreatMetrix encountered an error while processing the request

fail_temporarily_unavailable – the request fail because the service is temporarily unavailable

fail_invalid_email_address – the format of the supplied email address was invalid

fail_invalid_telephone_number – the format of the supplied telephone number was invalid

fail_invalid_device_id – the format of the supplied device_id was invalid

fail_invalid_ip_address_parameter – the format of a supplied ip_address parametera

was invalid

risk_reason_code 

 

The codes of the rules verified from the selected policy that have triggered.  Each rule code is returned as a separate name/value pair.

risk_reason_name 

 

The names of rules verified from the selected policy that have triggered.  Each rule name is returned as a separate name/value pair.

risk_reason_message_en

 

An English message description of the rule returned.

risk_reason_message_fr 

 

A French message description of the rule returned. 


The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Special Error Codes

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur.  The source URL will be included in the error.  Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request.  This may occur if unsupported characters were included in one of the posted fields.   

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information.  The ps_store_id and/or hpp_key did not match an existing store. 

N/A

Card Issuer returned corrupt data.  Unable to proceed with the transaction.  Please return to the site where you initiated the transaction and try again.  Your card has not been charged. – There is no code generated and a blank page is loaded with the above information.  This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.


Convenience Fee Response Codes

Code

Message / Description

Code

Message / Description

973

Unable to locate merchant CF details

977

Invalid amount

978

Failed CF transaction

984

Data error: (optional: field name)

987

Invalid transaction

Null

Error: Malformed XML


Hosted Paypage with Gift Purchase

The Purchase transaction is used when the customer presents their gift card at checkout time to pay for goods or services. The funds are then removed from the gift card. 

Canada Code Sample

<FORM METHOD="POST" ACTION= https://esqa.moneris.com/HPPDP/index.php >

     <INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="AF4Fs1024">

     <INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="Hsjh4GSr4g">

     <INPUT TYPE="HIDDEN" NAME="charge_total" VALUE="1.00">

     <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->

    <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

</FORM>

<!-- Optional Item Details Sample -->
<!--The code below will set the cust_id, order_id, and the lang as well as add gst, pst, hst and shipping cost details for display in the receipt.-->


<input type="hidden" name="cust_id" VALUE="invoice: 123456-12-1">

<input type="hidden" name="order_id" VALUE="oid43333">

<input type="hidden" name="lang" VALUE="fr-ca">

<input type="hidden" name="gst" VALUE="0.80">

<input type="hidden" name="pst" VALUE="0.70">

<input type="hidden" name="hst" VALUE="1.50">

<input type="hidden" name="shipping_cost" VALUE="4.99">

<INPUT TYPE="hidden" name="eci" VALUE="1">



<!-- Shipping and Billing Address Sample -->

<!-- The code below will set the billing and shipping details so they may be stored in the Merchant Resource Centre. Also, depending on the Hosted Pay Page configuration, these fields may also be included in the response and receipt. -->

<INPUT TYPE="HIDDEN" NAME="bill_first_name" VALUE="John">
<INPUT TYPE="HIDDEN" NAME="bill_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="bill_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="bill_address_one" VALUE="101 Main St">
<INPUT TYPE="HIDDEN" NAME="bill_city" VALUE="Smallville">
<INPUT TYPE="HIDDEN" NAME="bill_state_or_province" VALUE="NT">
<INPUT TYPE="HIDDEN" NAME="bill_postal_code" VALUE="Z1Z 1Z1">
<INPUT TYPE="HIDDEN" NAME="bill_country" VALUE="Canada">
<INPUT TYPE="HIDDEN" NAME="bill_phone" VALUE="555-555-5555">
<INPUT TYPE="HIDDEN" NAME="bill_fax" VALUE="555-555-6666">

<INPUT TYPE="HIDDEN" NAME="ship_first_name" VALUE="Jen">
<INPUT TYPE="HIDDEN" NAME="ship_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="ship_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="ship_address_one" VALUE="150 Lakeshore Rd">
<INPUT TYPE="HIDDEN" NAME="ship_city" VALUE="Springfield">
<INPUT TYPE="HIDDEN" NAME="ship_state_or_province" VALUE="IL">
<INPUT TYPE="HIDDEN" NAME="ship_postal_code" VALUE="234567">
<INPUT TYPE="HIDDEN" NAME="ship_country" VALUE="USA">
<INPUT TYPE="HIDDEN" NAME="ship_phone" VALUE="333-555-5555">
<INPUT TYPE="HIDDEN" NAME="ship_fax" VALUE="333-555-6666">



                

Mandatory Values

Variable Name Type Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  Identifies the configuration for the Hosted Pay Page.

hpp_key

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  This is a security key that corresponds to the ps_store_id.

charge_total

hidden

Final purchase Amount - no $, must include 2 decimal places
(i.e. 3.00)

This amount must be higher  than the Convenience Fee Amount


Optional Variables – Transaction Details

Variable Name

Type

Description

cust_id

hidden

This is an ID field that can be used to identify the client, commonly used for student #s, policy #s, client name or invoice #s. Can not be more than 50 chars.

order_id

hidden

MUST be unique per transaction and be no more than 50 chars.
System will generate if excluded.

lang

hidden

This defines what language the Hosted Pay Page and the receipts will be in:

en-ca = English

fr-ca = French

If the tag is not included the hosted Pay Page will default to English.

gst

hidden

This is where you would include Goods and Services Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

pst

hidden

This is where you would include Provincial Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

hst

hidden

This is where you would include Harmonized Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

shipping_cost

hidden

This is where you would include shipping charges, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

note

text

This is any special instructions that you or the cardholder might like to store.  Can not be more than 50 chars.

email

text

Customer’s email address.  This address will be used for the email receipts.   Can not be

more than 50 chars.  If you have chosen to send an email receipt to the cardholder this field must be included.

eci

hidden

If using the Hosted Pay Page to integrate an internal order management system for Mail/Telephone Orders, send an eci value of 1.

If the Hosted Pay Page supports VbV/MCSC, the eci generated by VbV/MCSC will override the value passed in.


Optional Variable - Item Details

Where "n" is an alphanumeric value less than 10 characters long, unique to each item. For each item all five variables should be included. These items will be stored in the Merchant Resource Centre and will be included in the email receipt if “Include Line Item Details” is selected in the Email Receipt Configuration and will be displayed on the payment page if “Display Items Details” is selected in the Appearance Configuration.

Variable Name

Type

Description

idn

hidden

Product Code - SKU (max 10 chars)

descriptionn

hidden

Product Description - (max 15 chars)

quantityn

hidden

Quantity of Goods Purchased - (max - 4 digits)

pricen

hidden

Unit Price - (max - "7"."2" digits, i.e. min 0.00 & max 9999999.99)

subtotaln

hidden

Quantity X Price of Product - (max - "7"."2" digits,

i.e. min 0.00 & max 9999999.99)

 NOTE: you must send a quantityn > 0 or the item will not be added to the item list.


Shipping and Billing Address Variables

Note: Each of the fields below is alphanumeric and can not be more than 30 characters.

Variable Name

Type

ship_first_name

text

ship_last_name

text

ship_company_name

text

ship_address_one

text

ship_city

text

ship_state_or_province

text

ship_postal_code

text

ship_country

text

ship_phone

text

ship_fax

text


Variable Name

Type

bill_first_name

text

bill_last_name

text

bill_company_name

text

bill_address_one

text

bill_city

text

bill_state_or_province

text

bill_postal_code

text

bill_country

text

bill_phone

text

bill_fax

text

Gift Card Response Fields

Variable Name

Size/Type

Description

gift_charge_total

7.2 / num

This is the total amount of the Purchase transaction. This must contain 3 digits with two penny values. The minimum value passed can be 0.01 and the maximum 9999999.99

rem_balance

7.2/num

This is the remaining balance on the card after Deactivation. The balance will be in pennies.

display_text

82/an

This is a message that, if present, is to be shown to the customer on the device display. The number of lines in the text is variable (up to a maximum of 10 lines) and each line (except the last line) is terminated with a line feed.

receipt_text

122 /an

This is a message that, if present, is to be printed on the receipt

voucher_text

255/an

If the VoucherType field is non-zero, the text from this field should be printed in the body of the voucher.

ref_num

10/num

This is the unique number that was assigned by the Moneris system to identify the transaction. The maximum value of this parameter is 0xFFFFFFFF (4294967295).   The host can not return reference numbers greater than this value.  If this field is present, it is to be included on the receipt. 

terminal_id

8/num

Identifies the Terminal Identifier which was used to process the transaction.

txn_num

30 / an

Gateway Transaction identifier. This value is required if merchant decides to send automated void/refund through an API.


The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Special Error Codes

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur.  The source URL will be included in the error.  Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request.  This may occur if unsupported characters were included in one of the posted fields.   

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information.  The ps_store_id and/or hpp_key did not match an existing store. 

N/A

Card Issuer returned corrupt data.  Unable to proceed with the transaction.  Please return to the site where you initiated the transaction and try again.  Your card has not been charged. – There is no code generated and a blank page is loaded with the above information.  This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.


Hosted Paypage with Loyalty Purchase

The Purchase transaction is used when the customer presents their gift card at checkout time to pay for goods or services. The funds are then removed from the gift card.

Canada Code Sample

<FORM METHOD="POST" ACTION= https://esqa.moneris.com/HPPDP/index.php >

     <INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="AF4Fs1024">

     <INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="Hsjh4GSr4g">

     <INPUT TYPE="HIDDEN" NAME="charge_total" VALUE="1.00">

     <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->

    <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

</FORM>

<!-- Optional Item Details Sample -->
<!--The code below will set the cust_id, order_id, and the lang as well as add gst, pst, hst and shipping cost details for display in the receipt.-->


<input type="hidden" name="cust_id" VALUE="invoice: 123456-12-1">

<input type="hidden" name="order_id" VALUE="oid43333">

<input type="hidden" name="lang" VALUE="fr-ca">

<input type="hidden" name="gst" VALUE="0.80">

<input type="hidden" name="pst" VALUE="0.70">

<input type="hidden" name="hst" VALUE="1.50">

<input type="hidden" name="shipping_cost" VALUE="4.99">

<INPUT TYPE="hidden" name="eci" VALUE="1">



<!-- Shipping and Billing Address Sample -->

<!-- The code below will set the billing and shipping details so they may be stored in the Merchant Resource Centre. Also, depending on the Hosted Pay Page configuration, these fields may also be included in the response and receipt. -->

<INPUT TYPE="HIDDEN" NAME="bill_first_name" VALUE="John">
<INPUT TYPE="HIDDEN" NAME="bill_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="bill_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="bill_address_one" VALUE="101 Main St">
<INPUT TYPE="HIDDEN" NAME="bill_city" VALUE="Smallville">
<INPUT TYPE="HIDDEN" NAME="bill_state_or_province" VALUE="NT">
<INPUT TYPE="HIDDEN" NAME="bill_postal_code" VALUE="Z1Z 1Z1">
<INPUT TYPE="HIDDEN" NAME="bill_country" VALUE="Canada">
<INPUT TYPE="HIDDEN" NAME="bill_phone" VALUE="555-555-5555">
<INPUT TYPE="HIDDEN" NAME="bill_fax" VALUE="555-555-6666">

<INPUT TYPE="HIDDEN" NAME="ship_first_name" VALUE="Jen">
<INPUT TYPE="HIDDEN" NAME="ship_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="ship_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="ship_address_one" VALUE="150 Lakeshore Rd">
<INPUT TYPE="HIDDEN" NAME="ship_city" VALUE="Springfield">
<INPUT TYPE="HIDDEN" NAME="ship_state_or_province" VALUE="IL">
<INPUT TYPE="HIDDEN" NAME="ship_postal_code" VALUE="234567">
<INPUT TYPE="HIDDEN" NAME="ship_country" VALUE="USA">
<INPUT TYPE="HIDDEN" NAME="ship_phone" VALUE="333-555-5555">
<INPUT TYPE="HIDDEN" NAME="ship_fax" VALUE="333-555-6666">



                

Mandatory Values

Variable Name Type Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  Identifies the configuration for the Hosted Pay Page.

hpp_key

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  This is a security key that corresponds to the ps_store_id.

charge_total

hidden

Final purchase Amount - no $, must include 2 decimal places
(i.e. 3.00)

This amount must be higher  than the Convenience Fee Amount


Optional Variables – Transaction Details

Variable Name

Type

Description

cust_id

hidden

This is an ID field that can be used to identify the client, commonly used for student #s, policy #s, client name or invoice #s. Can not be more than 50 chars.

order_id

hidden

MUST be unique per transaction and be no more than 50 chars.
System will generate if excluded.

lang

hidden

This defines what language the Hosted Pay Page and the receipts will be in:

en-ca = English

fr-ca = French

If the tag is not included the hosted Pay Page will default to English.

gst

hidden

This is where you would include Goods and Services Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

pst

hidden

This is where you would include Provincial Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

hst

hidden

This is where you would include Harmonized Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

shipping_cost

hidden

This is where you would include shipping charges, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

note

text

This is any special instructions that you or the cardholder might like to store.  Can not be more than 50 chars.

email

text

Customer’s email address.  This address will be used for the email receipts.   Can not be

more than 50 chars.  If you have chosen to send an email receipt to the cardholder this field must be included.

eci

hidden

If using the Hosted Pay Page to integrate an internal order management system for Mail/Telephone Orders, send an eci value of 1.

If the Hosted Pay Page supports VbV/MCSC, the eci generated by VbV/MCSC will override the value passed in.


Optional Variable - Item Details

Where "n" is an alphanumeric value less than 10 characters long, unique to each item. For each item all five variables should be included. These items will be stored in the Merchant Resource Centre and will be included in the email receipt if “Include Line Item Details” is selected in the Email Receipt Configuration and will be displayed on the payment page if “Display Items Details” is selected in the Appearance Configuration.

Variable Name

Type

Description

idn

hidden

Product Code - SKU (max 10 chars)

descriptionn

hidden

Product Description - (max 15 chars)

quantityn

hidden

Quantity of Goods Purchased - (max - 4 digits)

pricen

hidden

Unit Price - (max - "7"."2" digits, i.e. min 0.00 & max 9999999.99)

subtotaln

hidden

Quantity X Price of Product - (max - "7"."2" digits,

i.e. min 0.00 & max 9999999.99)

 NOTE: you must send a quantityn > 0 or the item will not be added to the item list.


Shipping and Billing Address Variables

Note: Each of the fields below is alphanumeric and can not be more than 30 characters.

Variable Name

Type

ship_first_name

text

ship_last_name

text

ship_company_name

text

ship_address_one

text

ship_city

text

ship_state_or_province

text

ship_postal_code

text

ship_country

text

ship_phone

text

ship_fax

text


Variable Name

Type

bill_first_name

text

bill_last_name

text

bill_company_name

text

bill_address_one

text

bill_city

text

bill_state_or_province

text

bill_postal_code

text

bill_country

text

bill_phone

text

bill_fax

text



The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Special Error Codes

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur.  The source URL will be included in the error.  Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request.  This may occur if unsupported characters were included in one of the posted fields.   

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information.  The ps_store_id and/or hpp_key did not match an existing store. 

N/A

Card Issuer returned corrupt data.  Unable to proceed with the transaction.  Please return to the site where you initiated the transaction and try again.  Your card has not been charged. – There is no code generated and a blank page is loaded with the above information.  This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.


Hosted Paypage with Loyalty Redemption

Canada Code Sample

<FORM METHOD="POST" ACTION= https://esqa.moneris.com/HPPDP/index.php >

     <INPUT TYPE="HIDDEN" NAME="ps_store_id" VALUE="AF4Fs1024">

     <INPUT TYPE="HIDDEN" NAME="hpp_key" VALUE="Hsjh4GSr4g">

     <INPUT TYPE="HIDDEN" NAME="charge_total" VALUE="1.00">

     <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->

    <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

</FORM>

<!-- Optional Item Details Sample -->
<!--The code below will set the cust_id, order_id, and the lang as well as add gst, pst, hst and shipping cost details for display in the receipt.-->


<input type="hidden" name="cust_id" VALUE="invoice: 123456-12-1">

<input type="hidden" name="order_id" VALUE="oid43333">

<input type="hidden" name="lang" VALUE="fr-ca">

<input type="hidden" name="gst" VALUE="0.80">

<input type="hidden" name="pst" VALUE="0.70">

<input type="hidden" name="hst" VALUE="1.50">

<input type="hidden" name="shipping_cost" VALUE="4.99">

<INPUT TYPE="hidden" name="eci" VALUE="1">



<!-- Shipping and Billing Address Sample -->

<!-- The code below will set the billing and shipping details so they may be stored in the Merchant Resource Centre. Also, depending on the Hosted Pay Page configuration, these fields may also be included in the response and receipt. -->

<INPUT TYPE="HIDDEN" NAME="bill_first_name" VALUE="John">
<INPUT TYPE="HIDDEN" NAME="bill_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="bill_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="bill_address_one" VALUE="101 Main St">
<INPUT TYPE="HIDDEN" NAME="bill_city" VALUE="Smallville">
<INPUT TYPE="HIDDEN" NAME="bill_state_or_province" VALUE="NT">
<INPUT TYPE="HIDDEN" NAME="bill_postal_code" VALUE="Z1Z 1Z1">
<INPUT TYPE="HIDDEN" NAME="bill_country" VALUE="Canada">
<INPUT TYPE="HIDDEN" NAME="bill_phone" VALUE="555-555-5555">
<INPUT TYPE="HIDDEN" NAME="bill_fax" VALUE="555-555-6666">

<INPUT TYPE="HIDDEN" NAME="ship_first_name" VALUE="Jen">
<INPUT TYPE="HIDDEN" NAME="ship_last_name" VALUE="Smith">
<INPUT TYPE="HIDDEN" NAME="ship_company_name" VALUE="Moneris Solutions">
<INPUT TYPE="HIDDEN" NAME="ship_address_one" VALUE="150 Lakeshore Rd">
<INPUT TYPE="HIDDEN" NAME="ship_city" VALUE="Springfield">
<INPUT TYPE="HIDDEN" NAME="ship_state_or_province" VALUE="IL">
<INPUT TYPE="HIDDEN" NAME="ship_postal_code" VALUE="234567">
<INPUT TYPE="HIDDEN" NAME="ship_country" VALUE="USA">
<INPUT TYPE="HIDDEN" NAME="ship_phone" VALUE="333-555-5555">
<INPUT TYPE="HIDDEN" NAME="ship_fax" VALUE="333-555-6666">



                

Mandatory Values

Variable Name Type Description

 

form

https://esqa.moneris.com/HPPDP/index.php  - Development
https://www3.moneris.com/HPPDP/index.php  - Production

ps_store_id

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  Identifies the configuration for the Hosted Pay Page.

hpp_key

hidden

Provided by Moneris Solutions – Hosted Pay Page Configuration Tool.  This is a security key that corresponds to the ps_store_id.

charge_total

hidden

Final purchase Amount - no $, must include 2 decimal places
(i.e. 3.00)

This amount must be higher  than the Convenience Fee Amount


Optional Variables – Transaction Details

Variable Name

Type

Description

cust_id

hidden

This is an ID field that can be used to identify the client, commonly used for student #s, policy #s, client name or invoice #s. Can not be more than 50 chars.

order_id

hidden

MUST be unique per transaction and be no more than 50 chars.
System will generate if excluded.

lang

hidden

This defines what language the Hosted Pay Page and the receipts will be in:

en-ca = English

fr-ca = French

If the tag is not included the hosted Pay Page will default to English.

gst

hidden

This is where you would include Goods and Services Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

pst

hidden

This is where you would include Provincial Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

hst

hidden

This is where you would include Harmonized Sales Tax charged, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

shipping_cost

hidden

This is where you would include shipping charges, should you wish it to be displayed on the items list. (min 0.00 & max 9999999.99)

note

text

This is any special instructions that you or the cardholder might like to store.  Can not be more than 50 chars.

email

text

Customer’s email address.  This address will be used for the email receipts.   Can not be

more than 50 chars.  If you have chosen to send an email receipt to the cardholder this field must be included.

eci

hidden

If using the Hosted Pay Page to integrate an internal order management system for Mail/Telephone Orders, send an eci value of 1.

If the Hosted Pay Page supports VbV/MCSC, the eci generated by VbV/MCSC will override the value passed in.


Optional Variable - Item Details

Where "n" is an alphanumeric value less than 10 characters long, unique to each item. For each item all five variables should be included. These items will be stored in the Merchant Resource Centre and will be included in the email receipt if “Include Line Item Details” is selected in the Email Receipt Configuration and will be displayed on the payment page if “Display Items Details” is selected in the Appearance Configuration.

Variable Name

Type

Description

idn

hidden

Product Code - SKU (max 10 chars)

descriptionn

hidden

Product Description - (max 15 chars)

quantityn

hidden

Quantity of Goods Purchased - (max - 4 digits)

pricen

hidden

Unit Price - (max - "7"."2" digits, i.e. min 0.00 & max 9999999.99)

subtotaln

hidden

Quantity X Price of Product - (max - "7"."2" digits,

i.e. min 0.00 & max 9999999.99)

 NOTE: you must send a quantityn > 0 or the item will not be added to the item list.


Shipping and Billing Address Variables

Note: Each of the fields below is alphanumeric and can not be more than 30 characters.

Variable Name

Type

ship_first_name

text

ship_last_name

text

ship_company_name

text

ship_address_one

text

ship_city

text

ship_state_or_province

text

ship_postal_code

text

ship_country

text

ship_phone

text

ship_fax

text


Variable Name

Type

bill_first_name

text

bill_last_name

text

bill_company_name

text

bill_address_one

text

bill_city

text

bill_state_or_province

text

bill_postal_code

text

bill_country

text

bill_phone

text

bill_fax

text


The Hosted Pay Page is designed to generate special error codes when certain data is incorrect and/or the transaction couldn’t be processed. The table below contains the information regarding the error codes. Each error will be accompanied by a message describing the problem.

Special Error Codes

Code

Message / Description

914

Transaction cancelled by cardholder – The response code indicates that the cardholder pressed the <cancel> transaction button. This response is only returned if the enhanced cancel button functionality is enabled within the Hosted Paypage configuration.

991

Invalid referrer URL - <referrer url> – If the Hosted Pay Page solution is configured to check the referring URL and it is incorrect this error will occur.  The source URL will be included in the error.  Please refer to the “Security Features” portion of the Hosted Pay Page configuration for a list of all Allowed Referring URLs.

992

VBV / Secure Code authentication failed. – This error will occur if your merchant account is configured for VBV/MCSC and the cardholder failed to enter the proper PIN during the authentication process.

993

Data error - unable to store data. – This error will occur if too much request data was passed in the transaction request or if the database failed to store the request.  This may occur if unsupported characters were included in one of the posted fields.   

N/A

Invalid store credentials. – There is no code generated and a blank page is loaded with the above information.  The ps_store_id and/or hpp_key did not match an existing store. 

N/A

Card Issuer returned corrupt data.  Unable to proceed with the transaction.  Please return to the site where you initiated the transaction and try again.  Your card has not been charged. – There is no code generated and a blank page is loaded with the above information.  This error will occur if the cardholder’s issuing bank did not return the correct data in the VbV/MCSC authentication process.