My Profile_


Hosted Vault Page Add Credit Card

This transaction creates a new credit card profile, and generates a unique data key which can be obtained from the response.This data key is the profile identifier that all future financial Vault transactions will use to associate with the saved information.

The Hosted Vault Page supports several types of payments (i.e. Credit card, ACH). These can be configured using the Configuration Tool in the Merchant Resource Center. The payment types that are able to be chosen and configured for the Hosted Vault Page are dependent on the Moneris merchant account. Each payment type requires certain data to be sent. There are two possible ways of managing multiple payment types.

  1. The first method is to create one Hosted Vault configuration that supports all payment types and send all the required variables for each of the payment types in the request. The HVARU page will then allow the client/cardholder to choose which payment type they prefer. The registration response will include the chosen payment type.
  2. The second method is to create a separate Hosted Vault configuration for each of the supported payment types. This allows the user to select the payment type on the merchant’s website and the merchant then only sends the relevant data to the relevant Hosted Vault configuration. For example, create a separate configuration for credit card and another for ACH; when the cardholder chooses ACH from the available payment types on the merchant’s website the merchant then submits ACH relevant data to the ACH configuration.

Canada Code Sample

Below is a sample of the HVARU add account request using only the required variables. 

<FORM METHOD="POST" ACTION="https://esqa.moneris.com/HPPDP/index.php" >
      <INPUT TYPE="HIDDEN" NAME="res_id" VALUE="QRZX9qa002">
      <INPUT TYPE="HIDDEN" NAME="res_key" VALUE="resTTJYGTDLNB">
      <INPUT TYPE="HIDDEN" NAME="cc_crypt_type" VALUE="7">
      <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->
      <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">

<!-- The code below will set the optional fields.  These are details that will identify the customer’s profile -->
<INPUT TYPE="HIDDEN" NAME="cust_id" VALUE="invoice: 123456-12-1">
<INPUT TYPE="HIDDEN" NAME="phone" VALUE ="416 555 1212">
<INPUT TYPE="TEXT" NAME="email" VALUE="john.smith@moneris.com">
<INPUT TYPE="TEXT" NAME="note" VALUE="All deliveries go to back door">
<INPUT TYPE="HIDDEN" NAME="lang" VALUE="fr-ca">

<!-- The code below will send 3 rvar’s in the request so that they may be returned in the response or displayed on the merchant’s email receipt. -->
<INPUT TYPE="HIDDEN" NAME="rvar1" VALUE="TWO">
<INPUT TYPE="HIDDEN" NAME="rvar_monkey" VALUE="monkeys are funny">
<INPUT TYPE="HIDDEN" NAME="rvar_123" VALUE="abc">

</FORM>

                

Mandatory Variables

Variable Name

Type

Description

 

form

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

res_id

hidden

Provided by Moneris Solutions – Hosted Vault Configuration Tool

res_key

hidden

Provided by Moneris Solutions – Hosted Vault Configuration Tool

cc_crypt_type

hidden

Electronic Commerce Indicator (ECI) consists of 1 digit.

Possible values are:

1 - Mail Order/Telephone Order - Single

2 - Mail Order/Telephone Order - Recurring

3 - Mail Order/Telephone Order - Instalment

7 - Electronic Transaction with SSL


Optional Variables

Variable Name

Type

Description

lang

hidden

This defines what language the Hosted Vault Page will be in:

en-ca = English

fr-ca = French

If the tag is not included the Hosted Vault Page will default to English.

cust_id

50 A/N

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.

 

IT IS STRONGLY RECOMMENDED TO ALWAYS SEND A CUST_ID TO UNIQUELY IDENTIFY YOUR CLIENTS.

phone

20 A/N

This is the cardholder’s phone number

email

100 A/N

This is where you would include the cardholder’s email address should you wish to have an email receipt sent to them.  Can not be more than 50 chars.

note

100 A/N

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

 Note: Request fields allow the following characters: a-z A-Z 0-9 _ - : . @ $ = /

Optional Variables – “rvar” Variables

Where "n" is an alphanumeric value less than 10 characters long, unique to each rvar variable.  The data sent in the rvar variables will NOT be stored in the Merchant Resource Center.  These fields will be echoed back in the transaction response – in a GET or POST method.  Also, they may be sent in the email receipt to the merchant if “Include 'rvars' in merchant email” is selected in the Email Receipt Configuration.


Variable Name

Type

Description

rvarn

hidden

If these extra variables are sent in the request, they will be echoed back in the response (if GET or POST have been selected for the Response Method).  Commonly used for session ID’s.  These variables must begin with “rvar” and then contain any alphanumeric string (i.e. rvar1, rvarname, rvarMyVariable).


Response Fields

Variable Name

Size/Type

Description

data_key

max 50 / an

The unique key to identify the client.  This is the ID that will be used for subsequent transactions for the account, such as an update.

response_code

3 / an

Transaction Response Code

< 50: Transaction approved

>= 50: Transaction declined

NULL: Incomplete registration - Profile registration was not attempted

date_stamp

yyyy-mm-dd

Processing host date stamp

time_stamp

##:##:##

Processing host time stamp (24 hour clock)

result

4 / an

0, 1 or null

payment_type

an

This identifies what type of payment was registered.  Possible values are:

cc = Credit Card

cardholder

40 / an

Card Holder’s name as entered on the Hosted Vault Page.

f4l4

####***####

First 4 and last 4 digits of the card #

expiry_date

4 / num

This will return the expiry date in the format of YYMM as entered on the Hosted Vault Page.

message

100 / an

Response description returned from Moneris Gateway.

cust_id

50 / num

This is the cust_id that was passed in the account registration request.

transactionKey

100 / an (optional)

This is a string returned when using the transaction verification feature.  It must be passed back to Moneris Gateway to verify the authenticity of the transaction.

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.

avs_response_code

1/an

Please refer to the AVS and CVD Response code guide for possible responses

cvd_response_code

1/an

Please refer to the AVS and CVD Response code guide for possible responses

res_success

4 / a

True: Card registered

False: Card failed registration

Null: Incomplete registration


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 Vault Page Update Credit Card

This transaction updates a Vault profile (based on the data key) to contain credit card information. All information contained within a credit card profile is updated as indicated by the submitted fields. This will update a profile to contain Credit Card information by referencing the profile's unique data_key. If the profile which is being updated was already a Credit Card profile, by use of the Hosted Vault Page all payment details (credit card number & expiry date) will be updated. If interested in updating any of the fields except the card number, please refer to the Vault Update Credit Card API. If however the profile was of a different payment type (ie: ACH), the old profile will be deactivated and the new Credit Card information will be associated with the data_key.

Things to consider:

If the Vault profile currently contains ACH payment details, then this transaction will update the token to contain Credit Card payment details and all ACH specific data, such as ACH Information, will be overwritten.

The Hosted Vault Page supports several types of payments (i.e. credit card & ACH). These can be configured using the Configuration Tool in the Merchant Resource Center. The payment types that are supported are dependent on the Moneris merchant account. Each payment type requires certain data to be sent. There are two possible ways of managing multiple payment types.

  1. The first method is to create one Hosted Vault configuration that supports all payment types. This will allow the cardholder to choose and change which payment type they wish to use on the Account Update screen. The response will include the chosen payment type.
  2. Alternatively, a separate configuration can be created for each payment type. This will allow the merchant more control over which payment types the client may choose, by calling the profiles for each payment type directly. Using this features merchants can control whether clients may change between payment types once an account is created. The required variables must be sent to the Hosted Vault Page depending on what payment types are supported by the configuration being called.

Canada Code Sample

<!-- Below is a sample of a HVARU update request using only the required variables. -->

<FORM METHOD="POST" ACTION="https://esqa.moneris.com/HPPDP/index.php" >
      <INPUT TYPE="HIDDEN" NAME="res_id" VALUE="QRZX9qa002">
      <INPUT TYPE="HIDDEN" NAME="res_key" VALUE="resTTJYGTDLNB">
      <INPUT TYPE="HIDDEN" NAME="data_key" VALUE="123QWERTY123qwerty">
      <INPUT TYPE="HIDDEN" NAME="cc_crypt_type" VALUE="7">
      <!--MORE OPTIONAL VARIABLES CAN BE DEFINED HERE -->
      <INPUT TYPE="SUBMIT" NAME="SUBMIT" VALUE="Click to proceed to Secure Page">
<!-- The code below will send 3 rvar’s in the request so that they may be returned in the response or displayed on the merchant’s email receipt. -->
<INPUT TYPE="HIDDEN" NAME="rvar1" VALUE="TWO">
<INPUT TYPE="HIDDEN" NAME="rvar_monkey" VALUE="monkeys are funny">
<INPUT TYPE="HIDDEN" NAME="rvar_123" VALUE="abc">
</FORM>

                

Mandatory Variables

Variable Name

Type

Description

 

form

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

res_id

hidden

Provided by Moneris Solutions – Hosted Vault Configuration Tool

res_key

hidden

Provided by Moneris Solutions – Hosted Vault Configuration Tool

cc_crypt_type

hidden

Electronic Commerce Indicator (ECI) consists of 1 digit.

Possible values are:

1 - Mail Order/Telephone Order - Single

2 - Mail Order/Telephone Order - Recurring

3 - Mail Order/Telephone Order - Instalment

7 - Electronic Transaction with SSL


Optional Variables

Variable Name

Type

Description

lang

hidden

This defines what language the Hosted Vault Page will be in:

en-ca = English

fr-ca = French

If the tag is not included the Hosted Vault Page will default to English.

cust_id

50 A/N

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.

 

IT IS STRONGLY RECOMMENDED TO ALWAYS SEND A CUST_ID TO UNIQUELY IDENTIFY YOUR CLIENTS.

phone

20 A/N

This is the cardholder’s phone number

email

100 A/N

This is where you would include the cardholder’s email address should you wish to have an email receipt sent to them.  Can not be more than 50 chars.

note

100 A/N

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

 Note: Request fields allow the following characters: a-z A-Z 0-9 _ - : . @ $ = /

Optional Variables – “rvar” Variables

Where "n" is an alphanumeric value less than 10 characters long, unique to each rvar variable.  The data sent in the rvar variables will NOT be stored in the Merchant Resource Center.  These fields will be echoed back in the transaction response – in a GET or POST method.  Also, they may be sent in the email receipt to the merchant if “Include 'rvars' in merchant email” is selected in the Email Receipt Configuration.


Variable Name

Type

Description

rvarn

hidden

If these extra variables are sent in the request, they will be echoed back in the response (if GET or POST have been selected for the Response Method).  Commonly used for session ID’s.  These variables must begin with “rvar” and then contain any alphanumeric string (i.e. rvar1, rvarname, rvarMyVariable).


Response Fields

Variable Name

Size/Type

Description

data_key

max 50 / an

The unique key to identify the client.  This is the ID that will be used for subsequent transactions for the account, such as an update.

response_code

3 / an

Transaction Response Code

< 50: Transaction approved

>= 50: Transaction declined

NULL: Incomplete registration - Profile registration was not attempted

date_stamp

yyyy-mm-dd

Processing host date stamp

time_stamp

##:##:##

Processing host time stamp (24 hour clock)

result

4 / an

0, 1 or null

payment_type

an

This identifies what type of payment was registered.  Possible values are:

cc = Credit Card

cardholder

40 / an

Card Holder’s name as entered on the Hosted Vault Page.

f4l4

####***####

First 4 and last 4 digits of the card #

expiry_date

4 / num

This will return the expiry date in the format of YYMM as entered on the Hosted Vault Page.

message

100 / an

Response description returned from Moneris Gateway.

cust_id

50 / num

This is the cust_id that was passed in the account registration request.

transactionKey

100 / an (optional)

This is a string returned when using the transaction verification feature.  It must be passed back to Moneris Gateway to verify the authenticity of the transaction.

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.

avs_response_code

1/an

Please refer to the AVS and CVD Response code guide for possible responses

cvd_response_code

1/an

Please refer to the AVS and CVD Response code guide for possible responses

res_success

4 / a

True: Card registered

False: Card failed registration

Null: Incomplete registration


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 Vault Page with Transaction Verification Request

In order to perform a Transaction Verification it is essential that you configure the Hosted Vault configuration accordingly.  If the Hosted Vault is properly configured you will receive a variable in a 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.  The transaction verification request should be performed using server to server communication rather than sending the request through the browser.   Transaction Verification can only be performed once on a given transaction, and it can only be performed within 15 minutes of the original transaction.  

Once Moneris Gateway receives the transaction verification request we match 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 created in the format defined in the “Security Features” portion of the Hosted Paypage configuration.  Please see the table below for a list of possible Transaction Verification statuses.


The transaction verification must be performed using a server to server request.  The verification should not be sent through the browser.  

Canada Code Sample

Below is a sample of the Transaction Verification Request (This is just a sample for quick testing, the verification should be performed as a server to server request.)

<FORM ACTION="https://esqa.moneris.com/HPPDP/index.php" method="POST">
<INPUT TYPE="hidden" NAME="res_id" VALUE="QRZX9qa002">
<INPUT TYPE="hidden" NAME="res_key" VALUE="resTTJYGTDLNB">
<INPUT TYPE="hidden" NAME="transactionKey" VALUE="SADF98AF78ADSFUASDF987">
<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>
<data_key>123QWER123QWER123</data_key>
<response_code>1</response_code>
<status>Valid - Registered</status>
<transactionKey>SADF98AF78ADSFUASDF987</transactionKey>
</response>

Invalid Response:
<?xml version="1.0" standalone="yes"?>
<response>
      <response_code>995</response_code>
      <status>Invalid</status >
            <transactionKey>SADF98AF78ADSFUASDF987</transactionKey>
</response>

                

Response Fields

Variable Name

Size/Type

Description

data_key

50 / an

data_key of the original transaction

response_code

3 / an

Transaction Response Code from the original transaction

< 50: Transaction approved

>= 50: Transaction declined

NULL: Incomplete registration - Profile registration was not attempted

transactionKey

100/varchar

The transactionKey from the request

status

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-Registered : The account add/update was successfully validated

Invalid-Reconfirmed : The transactionKey provided has already been validated

Invalid : Unable to validate request

Invalid referrer URL: Invalid referrer URL

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