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 Credit Cards, Visa Debit, and MasterCard Debit.
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.
|
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 by referencing the profile's unique data_key. The Hosted Vault Page will update both the card number and card expiry date on file. If interested in updating any of the fields except the card number, please refer to the Vault Update Credit Card API.
<!-- 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.
|
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.
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.
|