My Profile_


Hosted Solutions Connection

System and Skill Requirements

In order to use Hosted Pay Page your system will need to have the following:

  1. A web server capable of sending and receiving an HTML Post/Get

As well, you will need to have the following knowledge and/or skill-set:

  1. Knowledge of creating an HTML webpage and posting forms.
  2. Knowledge of iframes
  3. If you are selling more than 1 item you will need some knowledge of a client-side scripting language (JavaScript, PHP . . .) to calculate a final charge amount.
  4. If you wish to create your own custom receipts, and perform transaction verification you will need knowledge of a server-side scripting language (PHP, Perl, ASP . . .)

The Merchant Resource Center Hosted Pay Page Configuration Tool

Before you can send a transaction to the Hosted Pay Page you will need to configure several settings through the Moneris Gateway Merchant Resource Centre (MRC). You can log into the MRC test environment or your production environment at the following links. 

Canada
QA https://esqa.moneris.com/mpg/          
Production https://www3.moneris.com/mpg/
United States
QA https://esplusqa.moneris.com/usmpg/
Production https://esplus.moneris.com/usmpg

A.    Hosted Solutions Setup Steps 

Hosted Payment Page - You will need to follow these steps.

  1. Login to your Moneris Gateway Merchant Resource Center
  2. Click on ‘Admin on the Menu
  3. Click on ‘Hosted PayPage Config’ in the sub-menu
  4. Generate a New configuration
  5. Configure your Hosted Paypage configuration
  6. Do the required development as outlined here
  7. Test your solution in the test environment
  8. Activate your production store
  9. Create and configure your production Hosted Pay Page store in the production Merchant Resource Centre
  10. Make the necessary changes to move your solution from the test environment into production

Hosted Tokenization – You will need to follow these steps.

  1. Login to your Moneris Gateway Merchant Resource Centre:
  2. Click on ‘Admin on the menu.
  3. Click on ‘Hosted Tokenization’ in the sub-menu.
  4. Enter the source domain page.  This is the address of the main outer page that sends the transaction to Moneris.
  5. Click the button “Create Profile”
  6. Make a note of the Profile ID that gets generated since this will need to be included in your HTML iFrame code.
  7. Do the required development as outlined here
  8. Test your solution in the test environment
  9. Activate your production store
  10. Create and configure your product Hosted Tokenization store in the production Merchant Resource Centre
  11. Make the necessary changes to move your solution from the test environment into production

Hosted Vault – You will need to follow these steps.

  1. Login to your Moneris Gateway Merchant Resource Center
  2. Click on ‘Vault’ on the menu
  3. Click on ‘Hosted Vault Config’ in the sub-menu
  4. Generate a New configuration
  5. Configure your Hosted Vault Profile
  6. Do the required development as outlined here
  7. Test your solution in the test environment
  8. Activate your production store
  9. Create and configure your production Hosted Vault Configuration in the production Merchant Resource Centre
  10. Make the necessary changes to move your solution from the test environment into production as outlined in this document

B.    Hosted Solutions Configuration Steps

Generate new hpp_key

This allows you to change the Hosted Pay Page Token (hpp_key).  Both the “ps_store_id” and “hpp_key” are to be kept secure, though if security were to be compromised, you may generate a new “hpp_key” without having to create a completely new configuration.   Please note that after clicking “Generate new HPP key” that your current key will cease to work immediately – there is also no way to retrieve or revert to the old key.



https://esplusqa.moneris.com/usmpg/
https://esplusqa.moneris.com/usmpg

Basic Configuration

Description

Add a description to easily identify this Hosted Pay Page configuration. This is especially useful when maintaining more than one Hosted Pay Page configuration.

Transaction Type

This defines what type of transaction will be processed.

Purchase: The cardholder will be charged immediately and funds will be deposited next business day.  This is used if your goods and services are shipped/provided within 24 hours.

Preauthorization: The funds will be locked but will not be settled until a Capture is performed.  The Capture will need to be performed via the Merchant Resource Centre or via an API.  Preauthorization (PreAuth) is used if the goods and services are not shipped/provided within 24 hours.

 

Payment Methods  

This defines which Payment Methods the Hosted Pay Page will allow, for example, one or all of the methods listed below. The Payment Methods available depend on the store's set-up and these may include Credit Cards, INTERAC Online or Gift Cards.

 

Credit Card: This will offer the customer the option of paying with their credit card once they reach the Hosted Pay Page. Please note, when the customer chooses to pay with a credit card, as opposed to INTERAC Online or Gift Cards, the transaction type that will be processed will be the one defined in the default 'Transaction Type' section above.  

 

Interac Online: This will offer the customer the option of being forwarded to their online banking to approve the transaction.  The funds will be debited directly from their bank account. Please note, all INTERAC Online transactions using the Hosted Pay Page will be processed as purchase transactions, there are also unique receipt requirements for INTERAC Online transactions

 

Gift Cards: This will offer the customer the option of using up to two gift cards as part of the transaction.  All gift card transactions will be processed as purchase transactions.  The customer will have the option to check their gift card balance on the Hosted Pay Page.

 

Response Method

This determines how the transaction response will be handled.

 

Moneris Gateway will generate a receipt: Once the transaction is processed Moneris Gateway will generate and display a receipt page based on the Pay Page Appearance and Response Data configurations.

 

Sent to your server as a POST:  Moneris Gateway will use an HTTP POST to send the transaction responses to your web server so that you can customize the receipt or so that other processes may be initiated on your site.

 

Sent to your server as a POST containing XML:  Moneris Gateway will use an HTTP POST to send the transaction responses back to your web server so that you can customize the receipt or so that other processes may be initiated on your site.  The response will be in XML format that will need to be parsed.

 

Sent to your server as a GET:  Moneris Gateway will redirect the cardholder to a URL on your server and attach the response as a URL encoded query string at the end of the URL so that you can customize the receipt or so that other processes may be initiated on your site. Please note that there are limitations imposed by the browser and operating system on the length of a query string.

 

 

note

When handling the response (POST or GET), you must be able to dynamically parse the data.  In the future, new variables may be added and the order of the response variables may change. 

Approved URL 

If you have chosen to create your own receipt (in Response Method) you will need to specify the URL where the transaction response will be returned when it is approved.  All URLs need to be complete – www.example.com is not sufficient – a proper URL is http://www.example.com/response.php – If a URL is missing or improperly typed it may result in a 404 error or a looping page.

 

Declined URL

If you have chosen to create your own receipt (in Response Method) you will need to specify the URL where the transaction response will be returned when it is declined.  This can be the same as the Approved URL.  All URLs need to be complete – www.example.com is not sufficient – a proper URL is http://www.example.com/response.php – If a URL is missing or improperly typed it may result in a 404 error or a looping page.

 

note

Click on the “Save Changes” button to save the existing configuration.   If the configuration is not saved the current Hosted Pay Page ID (ps_store_id) and Token (hpp_key) will be deleted after approximately 15 minutes.

Enhanced Cancel

 

If you have chosen to use the Enhanced Cancel feature, a full response will be returned to the Declined URL with a response code of '914' and a message of ‘cancelled by cardhol



Pay Page Appearance

Colours and Styles:

The following fields define the colour scheme that is to be used for the Hosted Pay Page as well as the receipts.   The colours must be defined in 6 character hex – there is a hex colour chart available by clicking on “Hex Colour Chart” button.


Background Colour

This defines the background colour of the page.

 

Font Style

This defines what font group will be used for the Hosted Pay Page.  We have defined three groups – Arial/Helvetica/SansSerif, Times New Roman/Times/Serif and Courier New/Courier/Mono.

Primary Text Colour

This defines the colour for the majority of the text on the Hosted Pay Page.  This must be legible on the chosen background colour.

 

Company Name Colour  

This defines the colour that will be used for your company name. 

 

Header and Footer Highlight Colour:

This defines the colour that will be used for a highlight bar that will appear below the company name and at the bottom of the Pay Page. 

 

Section Divider Colour

The Hosted Pay Page will be divided into several sections depending on what is displayed.  A colour bar is used to define the information.  This defines the colour of the Primary Bar.

 

Section Divider Text Colour

Occasionally the primary colour bar will contain text – this defines the colour of the text that will appear in the Primary Bar.  Please ensure that the text is legible.

 

Subsection Divider Colour

The Hosted Pay Page can be divided into several sub-sections depending on what is displayed.  A colour bar is used to define the information.  This defines the colour of the secondary bar that may subdivide information.

 

Subsection Divider Text Colour

Occasionally the Subsection Divider will contain text – this defines the colour of the text that will appear in the Subsection Divider.  Please ensure that the text is legible.

 


Hosted Pay Page Data Fields 

The following “Display” fields define what is to be displayed on the Hosted Pay Page where the cardholder enters their card information.  Some fields are required to be sent by the merchant, others can be set as input boxes on the Hosted Pay Page.  We do not check for completion or validity of the information input therefore we suggest that it be passed from the merchant to us

Display Item Details

This field indicates whether a listing of items purchased, taxes and shipping costs is to be displayed.  In order to display this information it is required that it be sent in the transaction request.  Please see request variables to properly send this data.

 

Display Customer Details

This includes several supplemental data fields that the merchant may pass to the Hosted Pay Page such as a Customer Id, a Customer Email Address, and an additional data field referred to as the Note data.

 

Display Billing Address

This field indicates whether the client’s billing information is to be displayed.  In order to display this information it is required that it be sent in the transaction request.  Please see request variables to properly send this data.

 

Display Shipping Address

This field indicates whether the client’s shipping information is to be displayed.  In order to display this information it is required that it be sent in the transaction request.  Please see request variables to properly send this data.

 

Disable Address Input Boxes

This disables the input boxes so that the cardholder cannot alter/add information in the Address, Note and Email fields.  When the input boxes are disabled the data will appear as text.

 

Display Merchant Name

This field indicates whether the Merchant Name should also be displayed on the Hosted Pay Page. The name that will be displayed is the official Merchant Name that Moneris Solutions has associated with the account and the name that the cardholder will see on their credit card statement. It is mandated by industry regulations that the merchant name be displayed on any checkout pages and receipts, but this field may be omitted if the Hosted Pay Page will be loaded within a frame that already displays the merchant name. If you choose to load the Hosted Pay Page within a frame, you are then required to have an SSL certificate.

 


Buttons

The following fields define what is to be displayed and the functionality of the buttons located on the Hosted Pay Page and the receipt, if it is to be generated by Moneris Gateway.

Cancel Button Text

This configures the text that is to appear on the cancel button.  The cancel button appears on the credit card input page and allows the cardholder to return to your site if they do not wish to complete the transaction.

 

Cancel Button URL

This configures the URL associated with the cancel button.  The cancel button appears on the credit card input page and allows the cardholder to return to your site if they do not wish to complete the transaction.  All URLs need to be complete – www.example.com is not sufficient – the proper URL is http://www.example.com – If a URL is missing or improperly typed it may result in a 404 error or a looping page.

 

Continue Button Text

This configures the text that is to appear on the continue button.  The continue button appears on the receipt page that is generated if the option in “Response Methods” is chosen, otherwise this field will be hidden.  The continue button allows the client to return to your site after completing a transaction.

 

Continue Button URL

This configures the URL associated with the continue button.  The continue button appears on the receipt page that is generated if the option in “Response Methods” is chosen, otherwise this field will be hidden.  All URLs need to be complete – www.example.com is not sufficient – the proper URL is http://www.example.com – If a URL is missing or improperly typed it may result in a 404 error or a looping page.

 

Hide Continue Button

This configures whether the continue button is to appear in the receipt page or not.  We do not advise hiding the continue button.

 


Hosted Pay Page Input Fields

The following section defines what input fields are to be displayed on the Hosted Pay Page. When an input field is included, it will automatically be mandatory for the customer to fill it in.  

Display CVD input

This defines whether the Hosted Pay Page should include the prompt for the Card Validation Digits (CVD). If this input field is displayed on the Hosted Pay Page it is then mandatory that the cardholder complete this data. This input field only applies to MC, VISA, AmEx and other Credit Card plans that support CVD transactions.  

 

Display AVS input

This defines whether the Hosted Pay Page should include the prompt for the Address Verification Service (AVS) details. If these input fields are displayed on the Hosted Pay Page it is then mandatory that the cardholder complete this data. These input fields only apply to MC, VISA, AmEx and other Credit Card plans that support AVS transactions.  


Logos

This section defines what logos will appear on the payment page. Please note that credit card logos are for display only and will not affect what card types you are able to accept. To begin accepting a new card type, please contact the Service Centre at 1-866-319-7450.   

Credit Card Logos

Allows you to select which logos should appear on the Hosted Pay Page. Check off the appropriate logos; Visa, MasterCard, American Express, Diners, Discover, Sears, JCB. Visa Debit  


Note: Click on the "Save Appearance Settings" button to apply these appearance settings to the Hosted Pay Page. If the appearance configuration is not saved these fields will be returned to their last known saved configuration.




Response/Receipt Data

Click on the “Configure Response Fields” button to specify what additional fields you wish to have returned in the transaction response or displayed on the response receipt.

New to this version is the ability to pass back line items, shipping and billing data that previously had to be passed in as “rvar” in order to be returned to the merchant.  We still strongly advise storing customer details on the merchant’s server before passing them to the Hosted Pay Page.

Response/Receipt Field Configuration

Return Line Item Details

All line item details will be returned to the response URL in the same manner they were passed to the Hosted Pay Page in the request.

 

Return Shipping Details

All shipping details will be returned to the response URL in the same manner they were passed to the Hosted Pay Page in the request.

 

Return Billing Details

All billing details will be returned to the response URL in the same manner they were passed to the Hosted Pay Page in the request.

 

Return Other Customer Fields

Fields such as cust_id, email, and note will be returned to the response URL in the same manner they were passed to the Hosted Pay Page in the request.

 

Return ECI value

The ECI value that was used during transaction processing will be returned to the response url.  This is used to determine the result of a VBV/MCSC transaction.  It is strongly encouraged to review all orders even when it appears a VBV/MCSC authentication was successful or attempted.

note

The ECI (crypt type) value sent in a follow-on transaction request must reflect the ECI value received from the Preauthorization.

 

Example: if the ECI value received from the preauthorization is "5", then the subsequent API capture request must also have it’s ECI (crypt type) set to “5”.

 

Return the txn_number

The txn_number for the transaction number is returned in the response.  This allows automation of captures, voids and refunds through the use of an API.

 

Return the VbV Result Code

The VbV result code value from Visa will be returned to the response url.  This is used to determine the validity of the VbV transaction data.  It is strongly encouraged to review this for all VbV transactions.

 

Return a Visa Debit card indicator.

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

Return AVS data

The Address Verification data entered by the cardholder on the Hosted Pay Page will be returned to the response url.

 


Asynchronous Transaction Response

Perform asynchronous data post 

This must be checked for asynchronous data post to be enabled.  When the asynchronous data post is enabled the Hosted Pay Page 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 supplementary and can be used to verify/validate the browser response. 

If you have enabled the asynchronous data post within your production Hosted Pay Page configuration, you will need to specify the response URL in (HTTPS) format.  Self signed certificates will be accepted, but an HTTP address will not work.

 

note

If you send characters that are not supported in any of the variables, the extra transaction details may not be stored, displayed or returned in the response.

 

The order_id allows the following characters:  a-z A-Z 0-9 _ - : . @ spaces

All other request fields allow the following characters: a-z A-Z 0-9 _ - : . @ $ = / 

 

If you are using accents they must be sent as html entities (é = é)  If these are being sent as GET please note that they must be URL encoded.

 

Also, please note that if the response is to be sent as a GET the extra transaction details may not always be properly returned.  This is due to limitations imposed by the browser and operating system on the length of a query string.

 

 

note

Click on the “Save Response Settings” button to apply these chosen additional fields to the transaction response.   If the response configuration is not saved these fields will be returned to their last known saved configuration.  Next, click on the “Return to main configuration” button to continue with your Hosted Pay Page configuration setup.

Email Receipts

 

Click on “Configure Email Receipts” to specify email receipt conditions and appearance. 

 

note

New to this version. All emails are now sent in HTML and text format. This change will allow recipient’s email client to display their receipt in their default preferred format. This will allow better formatting for customer receipts which will accommodate both web and mobile receipts.

 

Although we are sending in both HTML and text format, the card holder will only receive one receipt.

 

All emails now come from the moneris.com mail server vs. the www3.moneris.com mail server which had been identified as being a problem for certain spam filters.

Receipt Conditions

Send email to cardholder if transaction approves

This defines whether a receipt is to be e-mailed to the cardholder if the transaction approves.  If this option is selected, but the cardholder’s e-mail address is not sent in the POST, then the receipt will not be emailed out.  Please refer to Section 8 – Other Transaction Details for an example of how to send the cardholder’s email address (“email”) in the request.

 

Send email to cardholder if transaction declines

This defines whether a receipt is to be e-mailed to the cardholder if the transaction declines.  If this option is selected, but the cardholder’s e-mail address is not sent in the POST, then the receipt will not be emailed out.  Please refer to Section 8 – Other Transaction Details for an example of how to send the cardholder’s email address (“email”) in the request.

 

Send email to merchant if transaction approves

This defines whether a receipt is to be e-mailed to the merchant if the transaction approves.  If this option is selected, but the merchant’s e-mail address is not provided in the “Merchant email address” field, then the receipt will not be emailed out. 

 

Send email to merchant if transaction declines

This defines whether a receipt is to be e-mailed to the merchant if the transaction declines.  If this option is selected, but the merchant’s e-mail address is not provided in the “Merchant email address” field, then the receipt will not be emailed out. 

Include 'rvar' in merchant email

“rvar”s can be a series of variables/values that will be echoed back in the transaction response.  This field indicates whether these fields are to be included in the email to the merchant.  They will NOT be included in the email to the client.  If this option is selected, but the merchant’s e-mail address is not provided in the “Merchant email address” field, then the “rvar”s will not be e-mailed to the merchant. 

 

Merchant email address

This field allows you to provide the e-mail address you want all the Merchant Email Receipts to be sent to, as defined in the 3 options mentioned above.  Only one e-mail address may be provided.

 

Receipt Appearance

Include Line Item Details

This field indicates whether a listing of items purchased, taxes and shipping costs is to be displayed.  In order to display this information it is required that it be sent in the transaction request.  Please see request variables to properly send this data.

 

Include Billing Details

This field indicates whether the client’s billing information is to be displayed.  In order to display this information it is required that it be sent in the transaction request.  Please see request variables to properly send this data.

 

Include Shipping Details

This field indicates whether the client’s shipping information is to be displayed.  In order to display this information it is required that it be sent in the transaction request.  Please see request variables to properly send this data.

 

Include Customer Details

This will include the cust_id, client email address, and the note field data.

 

Email Text

New to version 3 of the Hosted Pay Page is the ability to add a short message that will appear at the top of the email receipts.  There is a 255 character limit and the characters supported are limited to letters, numbers and the following characters ‘ # @ _ , - . and space and enter (newline).

 

note

If you send characters that are not supported in any of the variables, the extra transaction details may not be stored or included in the email receipt.

 

The order_id allows the following characters:  a-z A-Z 0-9 _ - : . @ spaces

 

All other request fields allow the following characters: a-z A-Z 0-9 _ - : . @ $ = / 

 

note

Click on the “Save Email Settings” button to apply these chosen Email Receipt settings to the Hosted Pay Page.   If the Email Receipt configuration is not saved these fields will be returned to their last known saved configuration.  Next, click on the “Return to main configuration” button to continue with your Hosted Pay Page configuration setup.


Security Features

Click on “Configure Security” to add extra security measures to the Hosted Pay Page. 

Referring URL

 

By adding a URL, you specify that you would like us to check whether the transaction is coming from a location (URL) that you allow.  Only POSTs sent from one of the specified URLs will be processed.  (It is possible for the Referring URL to be “spoofed” – this is not a guaranteed method of securing your transactions – but it makes it more difficult). 

 

Add URL

Here you can specify up to ten Referring URLs to a max of 255 characters.  Each URL needs to be complete and at a registered domain – www.example.com is not sufficient – the proper URL is http://www.example.com/index.html (IP addresses are not supported).  After specifying a URL, click on the “Add URL” button to add it to the Allowed URLs list.  Once a URL has been added, the “Remove URL” button will become available.

 

 

note

To verify your Referring URL, you may POST to https://esqa.moneris.com/HPPDP/myurl.php which will display the URL you are posting from.

Transaction Risk Scoring

Enable Transaction Risk Scoring  

This must be checked for transaction risk scoring to be enabled.  When Transaction Risk Scoring is enabled the Hosted Pay Page will automatically generate a “session_id” in the transaction request and send this to ThreatMetrix for device profiling.  When the response is received, Moneris Gateway then replies with the transaction information and the transaction risk score.  Each transaction can only be verified once.  The response to the Transaction Risk Scoring will be sent to your server in the form of a POST or GET only.

 

Card Verification

Enable Card Verification  

This must be checked for a card verification transaction to be performed.  When Card verification is enabled the Hosted Pay page will check the validity of a credit card before it is registered for recurring billing. This will only be performed when 'Bill Now' is set to 'false'.

 

Transaction Verification

Enable Transaction Verification

This must be checked for transaction verification to be enabled.  When Transaction Verification is enabled the Hosted Pay Page will return a “transactionKey” in the transaction response.  When the response is received the fields should be logged and a transaction verification request is sent to Moneris Gateway.  Moneris Gateway then replies with transaction information and whether the transaction was valid or not.  Each transaction can only be verified once and it must be verified within 15 minutes of the original transaction being performed.  This allows you to ensure that the responses sent to your page are not “spoofed” and that you are only receiving the responses once.  If you also intend to check the Referring URL you must ensure that the source of the verification request is in the list of Allowed URLs

.

Response Method

This determines how the transaction verification response will be handled.

 

Sent to your server as a POST:  Moneris Gateway will use an HTTP POST to send the transaction verification responses to your web server so that other processes may be initiated on your site.

 

Sent to your server as a GET:  Moneris Gateway will redirect the cardholder to a URL on your server and attach the transaction verification response as a URL encoded query string at the end of the URL so that other processes may be initiated on your site.

 

Displayed as XML on our server:   Once the transaction verification has been performed Moneris Gateway will generate a page and display an XML string.  This can be used in conjunction with cURL, screen scraping or other such methods.

 

Displayed as key/value pairs on our server:  Once the transaction verification has been performed Moneris Gateway will generate a page and display key value pairs.  This can be used in conjunction with cURL, screen scraping or other such methods.

 

note

When handling the response, you must be able to dynamically parse the data.  In the future, new variables may be added and the order of the response variables may change. 

 

 

Response URL

If you have chosen to have the transaction verification response sent back to you in either a POST or GET (in Response Method) you will need to specify the URL where the transaction response will be returned.  The URL needs to be complete and at a registered domain – www.example.com is not sufficient – a proper URL is http://www.example.com/response.php (IP addresses are not supported).  If a URL is missing or improperly typed it may result in a 404 error or a looping page.  If you have chosen to have Moneris Gateway display an XML string or key/value pairs this field may be left blank.

 

 

note

Click on the “Save Verification Settings” button to apply these chosen additional security features to the Hosted Pay Page.   If the security feature is not saved these fields will be returned to their last known saved configuration.  Next, click on the “Return to main configuration” button to continue with your Hosted Pay Page configuration setup.