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 and the CVV capture forms. The Card Display form does not send postMessage events. 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).
`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

The form sends CardSubmitSuccess or CardSubmitFailure whenever it runs in an iframe with postMessageHost set. CardSubmitSuccess carries the card token, the masked card number, the card type, the expiry date and the name on the card. It does not carry the 3D Secure result: that is stored on the token, and is also available through the {threeDSecIndication} placeholder in the success URL. Two parameters decide what happens around the message:

success. If you set a success URL, the iframe still redirects to it straight after sending CardSubmitSuccess. To handle the result on your page only, leave success out. The form then stays in place and the message is your only signal.
submitWithPostMessage=true. This removes the form’s own submit button, so your page submits the form with postMessage('submit'), as in the flow above. It does not change whether the redirect happens.

Keep a failure URL even in a postMessage flow: when the card is rejected, the iframe loads that page and your page also receives CardSubmitFailure. Send the form only the documented validate and submit messages. For a complete page that uses this flow with 3D Secure and a charge, see the complete checkout example.

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. Leave the success URL out of the iframe URL, listen for CardSubmitSuccess/CardSubmitFailure on your parent page, 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
}

The card number and security code themselves are never sent to your page. You receive the first eight and last four digits of the card number and the number of digits entered in each field (cardDigitCount, cvvDigitCount), which is enough to apply brand, length and expiry rules but not to verify that the security code is correct. That check can only be made by your payment processor - see Validate a Card. 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 the card entry form demo. All demos are listed on Live Demos. 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

Other messages posted to the form

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

​Other messages posted to the form

​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

Other messages posted to the form

Use Cases

Live Demo

Next Steps