Setup Guide

Configuring Merchant Resource Center

The Hosted Tokenization Configuration Tool, part of the Merchant Resource Center, is where you create and manage a profile for your hosted payment solution. Creating and configuring this profile are the first two steps in integrating Hosted Tokenization with your system.

Follow these steps to configure your Merchant Resource Center.

Getting a Temporary Token

To obtain a temporary token, send a request to Moneris from within an iframe. In the following example, replace ${profileID} with the Profile ID you received when configuring the Merchant Resource Center.

Setup

<iframe 
  id="monerisFrame"
  src="https://esqa.moneris.com/HPPtoken/index.php?
    id=${profileID}&
    pmmsg=true&
    enable_exp=1&
    enable_cvd=1&
    display_labels=1"
  style="border: 0;"
  width="200"
  height="200">
</iframe>

<input type="button" onclick="doMonerisSubmit()" value="Submit iframe request">

Request

Implement the function that sends the tokenization request from within the iframe.

function doMonerisSubmit() {
  const monerisFrame = document.getElementById("monerisFrame");
  const monerisFrameWindow = monerisFrame?.contentWindow;

  if (!monerisFrameWindow) {
    return false;
  }

  monerisFrameWindow.postMessage("tokenize", "https://esqa.moneris.com");
}

Response

The response returns a JSON object with the following four fields:

Examples

{
  "dataKey": "ot-tAZSNHEDV4t4Rn6bonrripHm4",
  "bin": "545454",
  "responseCode": "001"
}

{
  "dataKey": "ot-tAZSNHEDV4t4Rn6bonrripHm4",
  "bin": "545454",
  "responseCode": [ "001" ]
}

{
  "errorMessage": "invalid data",
  "responseCode": [ "943" ]
}

{
  "errorMessage": "invalid data",
  "responseCode": [ "945", "943", "944" ]
}

Using a Temporary Token to Process a Payment

Forwarding Temporary Token

To charge the card using the temporary token you will need to send the token to a page on your site that implements the Moneris Vault API. First, we'll need to read it from the iframe response by adding a message event listener.

const monerisDomain = "https://esqa.moneris.com"; // Use "https://www3.moneris.com" for prod

window.addEventListener("message", function(event) {
  // A security check that only accepts messages from the trusted Moneris domain.
  if (event.origin !== monerisDomain) return;

  try {
    const response = typeof event.data === "string" ? JSON.parse(event.data) : event.data;
    const responseCodes = Array.isArray(response.responseCode)
      ? response.responseCode
      : [response.responseCode];

    // Handle a successful response:
    if (responseCodes.includes("001")) {
      // dataKey is the temporary token representing the card number.
      const dataKey = response.dataKey;

      // Pass the token to your payment processing page.
      processPayment(dataKey);
    } else {
      // Handle validation errors
      console.log(
        "Credit card validation failed with Moneris response code(s): " + responseCodes.join(", ")
      );
    }
  } catch (error) {
    console.error("Failed to parse message from Moneris.", error);
  }
});

Processing the Payment

To charge the card using the temporary token you will need to pass the token to a page the implements the Moneris Vault API. The Vault feature allows merchants to create customer profiles, edit those profiles, and use them to process transactions without having to enter financial information each time. Customer profiles store customer data essential to processing transactions. Vault supports both administrative transactions and financial transactions.

• Administrative transactions: these transactions manage stored payment profiles in the Vault and do not move funds. They are used to maintain customer payment information. Administrative transactions are used for tokenization and profile management, and the resulting data key is later used for payment processing.
• Financial transactions: these transactions use the stored Vault data key to process payments and involve the movement or authorization of funds. Financial transactions use the tokenized card information stored in Vault, eliminating the need to resubmit card details while maintaining PCI compliance.

For more details on the Vault API please refer to the Vault API documentation. The following are examples of transactions that can be performed with your token:

• Purchase with Vault ( API | Batch )
• Pre-Authorization with Vault ( API | Batch )
• Card Verification with Vault ( API )
• Vault Add Token ( API )

Testing a Hosted Payment Solution

How to Test a Solution

A testing environment is available while you integrate your site with Moneris Gateway. The test environment is available 24/7; however, because it is a development environment, 100% availability is not guaranteed. Other merchants also use this environment, so you may see transactions, user IDs, and Hosted Tokenization configurations that you did not create.

As a courtesy to other testers, use only the transactions, users, and configurations that you created when processing refunds, changing passwords, or testing other functions.

The test environment is designed to replicate production behavior as closely as possible. A key difference is that test transactions are not sent to the live authorization network, so issuer responses are simulated. To emulate approval, decline, and error scenarios, specific transaction variable values are required.

In the test environment, approval and decline behavior is based on the penny value of the amount field. For example, transactions for $9.00 or $1.00 are approved because the .00 penny value maps to an approval response. Transactions in the test environment should not exceed $10.00. This limit does not apply in production.

Test Cards

When testing, you can use the following card numbers with any future expiry date.

Test Card Numbers

Moving to Production

After you create and configure your profile, and complete development and testing, you are ready to move your solution to production.

Configure a Store for Production

Once you have activated your store, the next step is to point your store to the production host with the following steps:

1. Update your HTML form action URL from QA: https://esqa.moneris.com/HPPtoken/index.php to Production: https://www3.moneris.com/HPPtoken/index.php.
2. Update profile_id to your production profile id value.

In production, access the Merchant Resource Center at https://www3.moneris.com/mpg. Use the store administrator ID created during activation, then create additional users as required.

Compliance Considerations

PCI DSS requirements may vary depending on your payment integration and implementation. Review the compliance requirements applicable to your organization before going live. For more information, see the Compliance page.