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

Add the postMessageHost parameter to your iframe URL. 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. Contains error reason.
`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.

Field-level validation events are also sent as JSON objects with {field, validationResult} for each field as the user interacts with the form.

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/');

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.

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",
  "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.

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

Guides

Concepts

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

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

​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

Next Steps