> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.

# PostMessage Notifications

> Control and receive events from the PCI Booking card entry iframe using postMessage. Form submission, validation, resizing.

The postMessage mechanism enables secure cross-domain communication between your page and the embedded PCI Booking iframe. It works with the [Card Entry Form](/capture-cards/hosted-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:

```javascript theme={null}
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.                                       |

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
{
  "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

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

### Rejecting

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Hosted Card Entry Form" icon="book" href="/capture-cards/hosted-card-entry-form">
    Set up the card entry form iframe.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All tokenization methods.
  </Card>

  <Card title="Stylesheets" icon="palette" href="/account-setup/stylesheets">
    Customize the look of your card entry form.
  </Card>

  <Card title="Card Entry Form Callback" icon="code" href="/api-reference/tokenize-cards/card-entry-form-callback">
    API reference for form callback notifications.
  </Card>
</CardGroup>