PostMessage Notifications

The postMessage mechanism enables secure cross-domain communication between your page and the embedded PCI Booking iframe. It works with the Card Entry Form, Card Display, and CVV capture forms. Use postMessage to:

Know when the iframe is ready.
Validate the form programmatically from your page.
Submit the form programmatically.
Receive tokenization results without a page redirect.
Resize the iframe dynamically based on form content.
Intercept card details before tokenization for custom approval logic.

Setup

postMessageHost is a required parameter on every card entry form request, whether or not you use the postMessage features below - see Request Card Entry Form. Set it to your page’s origin (URL-encoded):

https://service.pcibooking.net/api/payments/capturecard?sessionToken=YOUR_TOKEN&postMessageHost=https%3A%2F%2Fwww.yoursite.com

On your page, listen for messages from the iframe:

window.addEventListener('message', function(event) {
  if (event.origin !== 'https://service.pcibooking.net') return;
  console.log('Received:', event.data);
});

Events from the Iframe

Event	Format	Description
`ready`	String	Iframe loaded and ready for input.
`valid`	String	Form passed validation.
`invalid`	String	Form has validation errors.
`frameDimensionsChanged:{width}:{height}`	String	Iframe dimensions changed. Use this to resize the iframe element on your page.
`CardSubmitSuccess`	JSON object	Card tokenized successfully. Contains card info (masked number, type, expiration).
`CardSubmitFailure`	JSON object	Tokenization failed. `{ "reason": "..." }` - a human-readable string built from the underlying API error (HTTP status + message), not a structured error code. Also fires on a real-card rejection at capture time and on a 3DS fingerprint/challenge failure, not just on request-level errors.
`ThreeDsChallengeLoaded`	String	3DS challenge iframe loaded.
`OTPdisplayed`	JSON object	OTP entry form displayed (for 3DS or form charge).
`OTPsubmitted`	JSON object	OTP submitted by the user.
`CustomValidation`	JSON object	Masked card details sent before tokenization when `useCustomValidation=true`. See Custom Validation below.

CardSubmitSuccess is a single message and its payload is the card data (masked number, type, expiration, token) - there is no earlier, separate message carrying card data before it. If you’re seeing partial card fields arrive before CardSubmitSuccess, that’s CustomValidation firing (only happens when useCustomValidation=true), not a second success signal.

Field-level validation events are also sent as JSON objects with {field, validationResult} for each field as the user interacts with the form. For most fields, validationResult is a string with the failure reason:

{
  "field": "[field_name]",
  "validationResult": "[validation_failure_reason]"
}

For an invalid card number, validationResult is a structured object detailing which checks failed:

{
  "field": "cardNumber",
  "validationResult": {
    "card_type": {
      "name": "Visa",
      "pattern": { },
      "valid_length": [ 16, 13 ]
    },
    "valid": false,
    "luhn_valid": true,
    "length_valid": false
  }
}

card_type - the detected card brand, its number pattern, and the valid lengths for that brand
luhn_valid - whether the number passes the Luhn checksum
length_valid - whether the number length is valid for the detected brand
valid - the overall result

Commands to the Iframe

Your page can send commands to the iframe:

Command	Format	Description
`validate`	String	Trigger form validation. The iframe responds with `valid` or `invalid`.
`submit`	String	Submit the form programmatically.

var iframe = document.getElementById('card-form').contentWindow;
iframe.postMessage('validate', 'https://service.pcibooking.net/');

A typical single-submit-button flow, where your page validates its own fields and the card form together:

Receiving Results via PostMessage

To receive tokenization results via postMessage instead of a redirect, add submitWithPostMessage=true to your iframe URL. On success, the iframe sends a CardSubmitSuccess message containing the token details. On failure, it sends CardSubmitFailure with the error.

If your success/failure URL resolves to a private or local network address from the cardholder’s browser (common with split-horizon DNS on corporate networks), Chrome’s Private Network Access policy blocks the iframe’s redirect to it, with the error “The connection is blocked because it was initiated by a public page to connect to devices or servers on your local network.” The tokenization itself still succeeds - only the redirect back to your page is blocked.Fix: switch to the postMessage flow above instead of relying on the redirect. Listen for CardSubmitSuccess/CardSubmitFailure on your parent page (submitWithPostMessage=true), read the token/card details directly from that message’s payload, and perform your own client-side navigation from there - this is in-browser JS communication, not a network request, so PNA does not apply to it.

Dynamic Iframe Resizing

When the form content changes (e.g. validation errors appear), the iframe sends frameDimensionsChanged:{width}:{height}. Use this to resize the iframe:

window.addEventListener('message', function(event) {
  if (event.origin !== 'https://service.pcibooking.net') return;

  if (typeof event.data === 'string' && event.data.startsWith('frameDimensionsChanged')) {
    var parts = event.data.split(':');
    var iframe = document.getElementById('card-form');
    iframe.style.width = parts[1] + 'px';
    iframe.style.height = parts[2] + 'px';
  }
});

Custom Validation

Custom validation lets your page inspect card details before tokenization and approve or reject the submission. Enable it by adding useCustomValidation=true to the iframe URL. When the cardholder submits the form, the iframe pauses tokenization and sends a CustomValidation message with masked card details:

{
  "messageType": "CustomValidation",
  "cardType": "Visa",
  "lastDigits": "0068",
  "leadingDigits": "41111111",
  "expirationYear": "2029",
  "expirationMonth": "4",
  "ownerID": "098876765",
  "ownerName": "John Doe",
  "cardDigitCount": 16,
  "cvvDigitCount": 3
}

Your page has 3 seconds to respond. If no response is received, tokenization proceeds automatically.

Approving

iframe.postMessage({
  action: 'customValidationResponse',
  success: true
}, 'https://service.pcibooking.net/');

Rejecting

iframe.postMessage({
  action: 'customValidationResponse',
  success: false,
  message: 'AMEX cards are not accepted'
}, 'https://service.pcibooking.net/');

When rejected, the form displays the message as a validation error and the cardholder can correct their input or try a different card.

Use Cases

Restrict accepted card types or BIN ranges before tokenization.
Check card details against your business rules (e.g. reject corporate cards, enforce expiry minimums).
Log or audit card submissions before they are tokenized.

Live Demo

See the postMessage mechanism in action on our card capture demo page. Open your browser’s developer console to watch the messages exchanged between the parent page and the iframe as you interact with the form.

Next Steps

Hosted Card Entry Form

Set up the card entry form iframe.

Capture Cards Overview

All tokenization methods.

Stylesheets

Customize the look of your card entry form.

Card Entry Form Callback

API reference for form callback notifications.

Start Here

Getting Started

Concepts

Guides

Capture Cards

Payments Library

Manage Tokens

Use Tokens

Account Configuration

Additional Functions

Reference

Support

PostMessage Notifications

Setup

Events from the Iframe

Commands to the Iframe

Receiving Results via PostMessage

Dynamic Iframe Resizing

Custom Validation

Approving

Rejecting

Use Cases

Live Demo

Next Steps

Hosted Card Entry Form

Capture Cards Overview

Stylesheets

Card Entry Form Callback

​Setup

​Events from the Iframe

​Commands to the Iframe

​Receiving Results via PostMessage

​Dynamic Iframe Resizing

​Custom Validation

​Approving

​Rejecting

​Use Cases

​Live Demo

​Next Steps

Hosted Card Entry Form

Capture Cards Overview

Stylesheets

Card Entry Form Callback

Setup

Events from the Iframe

Commands to the Iframe

Receiving Results via PostMessage

Dynamic Iframe Resizing

Custom Validation

Approving

Rejecting

Use Cases

Live Demo

Next Steps