This guide explains how to securely trigger a submit action in CellPoint Digital Velocity's Hosted Payment Page (HPP) iframe directly from your own parent page, and it describes the workflow and benefits of this integration. The HPP iframe supports external submission via the postMessage, allowing the parent page to programmatically trigger the payment form submission.

This has several benefits:

• Secure handling of submit requests – Only trusted parent origins are allowed, preventing unauthorized submits from unknown sources.
• Message validation – Every request must carry a pre-agreed secure message key.
• Seamless integration – Merchants can initiate an iframe submit without altering internal iframe code, so this process integrates seamlessly into merchant-hosted pages.
• Consistent experience – This integration avoids UI conflicts and ensures uniform submit handling across all environments.
• Flexibility - With this setup, the merchant can submit the iframe from their own page either by using the internal Pay button or exclusively via parent page control.

Security Model

To maintain a secure integration, the following controls are enforced:

• Origin Validation
  • Only allowlisted parent domains can trigger submission.
  • Requests from non-allowlisted origins are ignored.
• Secure Message Key
  • The parent page must include a predefined token ('postMessageToken') in its message.
  • Only messages with this token will trigger submission.
• Iframe Isolation
  • The merchant must not directly access or manipulate the iframe DOM.
  • The only supported mechanism is postMessage.
• Environment Coverage
  • The merchant must provide all parent origins for QA, UAT, and Production to prevent rejection during testing or live usage.

Workflow

When using external submission, the workflow is as follows:

1. Trigger submit - The merchant's page sends a submit request to the HPP iframe.

2. Message validation - The iframe listens for the incoming message and validates it by confirming the following:

   • The origin is in the allowlist.
   • The secure message token matches 'postMessageToken'.

3. Payment submission - After validation, the iframe triggers the payment submission process and behaves as if the user has clicked the Pay button manually. The payment request is securely submitted via HPP.

Prerequisites

Ensure you have fulfilled the following prerequisites before using external submission:

• Embed HPP iframe - Follow the steps in the Iframe Integration Guide to embed the CellPoint Digital HPP iframe on your page.
• Share parent origins - Share all parent origins for the allowlist with your CellPoint onboarding support representative.
• Receive postMessageToken - During the onboarding process, CellPoint securely shares the value of postMessageToken with you by email.
• Test flow - Test your flow in SIT/UAT before enabling it in Production.

Integration

Call the following function to send a submit request to the HPP iframe, using the secure message token you received from CellPoint Digital as the value of postMessageToken:

function callSubmit() {
  const hppFrame = document.getElementById('app'); // iframe id
  if (hppFrame?.contentWindow) {
    hppFrame.contentWindow.postMessage(
      'postMessageToken', // secure message key
      '*'                  // target origin
    );
  } else {
    console.error('Iframe not accessible or not found.');
  }
}