Purchase with Payment Token
Overview
Hosted Tokenization allows your customers to input credit card numbers directly on your website in a secure frame controlled by Moneris.
Accepting customer payments by using the Moneris Hosted Tokenization and the Moneris server-to-server APIs allows you to avoid compliance burdens for Payment Card Industry (PCI) standards.
Hosted Tokenization allows your customers to input credit card numbers directly on your website in a secure frame controlled by Moneris; this allows the rest of your website to maintain the look and feel you choose. Upon customer submission the tokenization frame captures the sensitive credit card data and returns a temporary “token” to your server allowing you to proceed with payment via our API.
1. Hosted Tokenization Setup
You will need to follow these steps.
- Login to your Moneris Merchant Resource Centre:
- Click on ‘Admin’ on the menu.
- Click on ‘Hosted Tokenization’ in the sub-menu.
- Enter the source domain page. This is the address of the main outer page that sends the transaction to Moneris.
- Click the button “Create Profile”
- Make a note of the Profile ID that gets generated since this will need to be included in your HTML iFrame code.
- Do the required development as outlined here
- Test your solution in the test environment
- Activate your production store
- Create and configure your product Hosted Tokenization store in the production Merchant Resource Centre
- Make the necessary changes to move your solution from the test environment into production
Moneris Merchant Resource Centre (MRC)
2. Getting Temporary Token
To get a temporary token you will need to send a request to Moneris from within an IFrame.
A sample code is illustrated below.
Note that the Profile ID in the HTML link below will need to be replaced with your own Profile ID, which you can configure the MRC as described here.
Note
The src and postMessage URL will need to be updated to the appropriate QA or production URL listed below.
environment URL QA https://esqa.moneris.com/HPPtoken/index.php Production https://www3.moneris.com/HPPtoken/index.php
Required variables
| Variable Name | Definition |
|---|---|
| Id | Required - Provided by the Hosted Tokenization profile configuration tool in the MRC. |
| css_body | Required - CSS applied to the body. By default, margin and padding is set to zero |
| css_textbox | Required - CSS applied to all text boxes in general. |
Optional variables
| Variable Name | Definition |
|---|---|
| pmmsg | Recommended - Forces form to only accept message of 'tokenize'. |
| css_textbox_pan | Optional - CSS applied to the pan text box specifically. |
| enable_exp | Optional - Must be set to 1 for expiry date text box to be displayed (Format: MMYY) |
| css_textbox_exp | Optional - CSS applied to the expiry date text box specifically. |
| enable_cvd | Optional - Must be set to 1 for CVD text box to be displayed |
| css_textbox_cvd | Optional - CSS applied to the CVD text box specifically. |
| display_labels | Optional – 0 for no labels, 1 for traditional labels, 2 for place holder labels. |
| css_input_label | Optional – CSS for input labels |
| css_label_pan | Optional – CSS for card number label |
| css_label_exp | Optional – CSS for expiry date label |
| css_label_cvd | Optional – CSS for CVD label |
| pan_label | Optional – text for card number label (default is “Card Number”) |
| exp_label | Optional – text for expiry date label (default is “Expiry Date”) |
| cvd_label | Optional – text for CVD label (default is “CVD”) |
| enable_exp_formatting | Optional - Formatting applied to expiry date field to display a slash between month and year (Format: MM/YY). Must be set to 1 to enable formatting. |
| enable_cc_formatting | Optional - Formatting applied to credit card number based on the card type (Format: Visa - 4242 4242 4242 4242, MC - 5454 5454 5454 5454, Amex - 333 666666 55555) |
Response Fields
| Field | Description |
|---|---|
| responseCode | Indication whether the page-loading or card-submission was successful or why it failed. Please note, if expiry text box or CVD text box are enabled, the returned responseCode value will be in the form of a list (e.g. [“944”,”943”]), since there may be more than one failure. For example, in the case where both the card number entered and expiry date are invalid. If only the card number text box is displayed, the responseCode will be returned in the form of a string. |
| errorMessage | Description of failure (This is a very generic description – see “responseCode Definitions” below for specific error code results). |
| bin | BIN range of the submitted card number. Provides merchant ability to determine the card type and perform any card-specific processing. |
| dataKey | Tokenized card number. This is what is used with the Vault API transaction |
Response Code Definitions
| Response Code | Definition |
|---|---|
| 001 | Successful creation of temporary token |
| 940 | Invalid profile id (on tokenization request) |
| 941 | Error generating token |
| 942 | Invalid Profile ID, or source URL |
| 943 | Card data is invalid (not numeric, fails mod10, we will remove spaces) |
| 944 | Invalid expiration date (mmyy, must be current month or in the future) |
| 945 | Invalid CVD data (not 3-4 digits) |
Code sample
<html>
<head>
<title>Outer Frame - Merchant Page</title>
<script>
function doMonerisSubmit() {
var monFrameRef = document.getElementById('monerisFrame').contentWindow;
monFrameRef.postMessage('tokenize', 'https://mpg1t.moneris.io/HPPtoken/index.php');
// Change link according to table above
return false;
}
var respMsg = function (e) {
var respData = eval("(" + e.data + ")");
document.getElementById("monerisResponse").innerHTML = e.origin + " SENT " + " - " +
respData.responseCode + "-" + respData.dataKey + "-" + respData.errorMessage;
document.getElementById("monerisFrame").style.display = 'none';
}
window.onload = function () {
if (window.addEventListener) {
window.addEventListener("message", respMsg, false);
} else {
if (window.attachEvent) {
window.attachEvent("onmessage", respMsg);
}
}
}
</script>
</head>
<body>
<div>Hosted Tokenization Demo</div>
<div id="monerisResponse"></div>
<iframe
id="monerisFrame"
src="https://mpg1t.moneris.io/HPPtoken/index.php?id=ht1TTK3NZLJ82PE&pmmsg=true&css_body=background:white;margin:0 0 0 6px;padding:0;color:darkgray;&css_textbox=font-size:0.975rem;float:left;border-width:0;margin:0 0 0 4px;padding:0;height:30px;&css_textbox_pan=width:180px;&enable_exp=1&css_textbox_exp=width:70px;&enable_cvd=1&css_textbox_cvd=width:50px;&display_labels=2&exp_label=MMYY"
frameborder="0"
style="width: calc(100% - 10px); height: 60px;">
</iframe>
<input type="button" onClick="doMonerisSubmit()" value="submit iframe">
</body>
</html>3. Receiving Temporary Token Response
var respMsg = function (e) {
var respData = eval("(" + e.data + ")");
document.getElementById("monerisResponse").innerHTML = e.origin + " SENT " + " - " +
respData.responseCode + "-" + respData.dataKey + "-" + respData.errorMessage;
document.getElementById("monerisFrame").style.display = 'none';
// Your token will be in the field: respData.dataKey
// From this point you can post the token to another page that will process the payment.
}Note
Describes how to receive the response from the Hosted Tokenization page containing the temporary token
4. Processing the Payment
To charge the card using the temporary token you will need to utilize our API to Create Payment with the temporary token as the payment method.
In the POST /payments request, include the “paymentMethodData” object with the following parameters:
- "paymentMethodType" with a value of "TEMPORARY_TOKEN",
- “temporaryToken” with a value matching the token provided by the Hosted Tokenization service
For details on the API, refer to:
Navigate to Purchase Navigate to Pre-Authorization & Completion
Additional Information
Learn more with the API Definitions
Peruse the endpoints, request/response formats, and authentication methods covered in this scenario.
Updated 14 days ago