Using window.postMessage()
Using postMessage with PayForm, AccountForm, Hosted Payment Page, or SSO in an iFrame is easy! You just need to add some code within your application to make use of our postMessage call.
Enabling postMessage
Below you will see a code example in Node on how you would build your data packet and construct the url for the form. Notice that we are adding a field "parent_send_message" with a value of 1 to enable postMessage functionality.
Note: This is not applicable in SSO scenario. For SSO scenarios, the postMessage is always sent if the UI is detected to be in an iFrame.
// Your custom ticket hash key
var encryption_key = 'my_ticket_hash_key';
// Sample JSON of the base data:
var data = JSON.stringify({
"id": "xxxxxxxxxxxxxxxxxxxxxxxx",
"parent_send_message": 1 // Adding/setting this field to 1 will enable postMessage
});
// Encrypt the JSON object using the encryption_key
var encrypted_data = CryptoJS.AES.encrypt(data, encryption_key).toString();
// URL encode the encrypted data so it can be sent in the URL
var encoded_data = encodeURIComponent(encrypted_data);
// The endpoint you are using. Could also be "accountform" or "payform"
var endpoint = "hostedpaymentpage";
// Put together the final URL: for displaying in your page
var url = 'https://{sandbox_url}/' + endpoint + '?id={id}&data=' + encoded_data;
// Here is the final URL
console.log(url);
Receiving the Message
In the code sample below, you will see some JavaScript adding an event listener that will log the event object and data that was received from the postMessage() call. This logging is just for testing purposes to allow you to see the structure of the data being received. The console.log calls can be removed when your testing is complete (should be replaced with your actual business logic to process the message or respond to it).
<html>
<head>
</head>
<body>
<!-- Other HTML Here -->
<!-- Add this script tag prior to embedding the iFrame -->
<script>
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
// Make sure the value for allowed matches the domain of the iFrame you are embedding.
var allowed = "https://api.sandbox.domain.com";
// Verify sender's identity
if (event.origin !== allowed) return;
// Add logic here for doing something in response to the message
console.log(event); // for example only, log event object
console.log(JSON.parse(event.data)); // for example only, log JSON data
}
</script>
<!-- include the iframe after the script tag for the event listener -->
<iframe src="https://{sandbox_url}/{payform|accountform|hostedpaymentpage|sso}?id={id}&data={data}"></iframe>
</body>
</html>
Once a successful API call is made inside the iFrame, the iFrame will fire postMessage using the JSON response from the form as the value of the message.
Example Response (AccountForm/PayForm/Hosted Payment Page)
{
"account_holder_name":"Test Test",
"account_number":null,
"account_type":"mc",
"account_vault_api_id":null,
"accountvault_c1":null,
"accountvault_c2":null,
"accountvault_c3":null,
"ach_sec_code":null,
"active":"1",
"billing_address":"123 main st",
"billing_city":null,
"billing_phone":null,
"billing_state":null,
"billing_zip":null,
"card_type":null,
"contact":"contact-2222222222222222",
"contact_id":"contact-2222222222222222",
"created_ts":"2020-08-07T11:47:37-04:00",
"created_user":"11111111-1111-1111-1111-111111111111",
"dl_state":null,
"exp_date":"0626",
"exp_month":"06",
"exp_year":"26",
"expiring_in_months":"68",
"first_six":"545454",
"has_recurring":true,
"is_company":null,
"last_four":"5454",
"location":"location-222222222222222",
"location_id":"location-222222222222222",
"payment_method":"cc",
"routing":null,
"signature":null,
"terms_agree":null,
"title":"CC"
}
Note: This example is intended to show the format of the reponse you can expect. The exact fields will vary depending on which one you are using.
Example Response (SSO iFrame)
{
"method":"PUT",
"model":"accountvault",
"response":{
"account_holder_name":"Test Test",
"account_number":null,
"account_type":"mc",
"account_vault_api_id":null,
"accountvault_c1":null,
"accountvault_c2":null,
"accountvault_c3":null,
"ach_sec_code":null,
"active":"1",
"billing_address":"123 main st",
"billing_city":null,
"billing_phone":null,
"billing_state":null,
"billing_zip":null,
"card_type":null,
"contact":"contact-2222222222222222",
"contact_id":"contact-2222222222222222",
"created_ts":"2020-08-07T11:47:37-04:00",
"created_user":"11111111-1111-1111-1111-111111111111",
"dl_state":null,
"exp_date":"0626",
"exp_month":"06",
"exp_year":"26",
"expiring_in_months":"68",
"first_six":"545454",
"has_recurring":true,
"is_company":null,
"last_four":"5454",
"location":"location-222222222222222",
"location_id":"location-222222222222222",
"payment_method":"cc",
"routing":null,
"signature":null,
"terms_agree":null,
"title":"CC"
}
}
- Values for method will be:
- POST
- PUT
- DELETE
- Values for model will be:
- accountvault
- contact
- recurring
- transaction
- The response field will vary depending on the value for model as it will be the object for that specific model. See the relevant area in the API Reference section for model specific fields
Security concerns
If you do not expect to receive messages from other sites, do not add any event listeners for message events. This is a completely foolproof way to avoid security problems.
If you do expect to receive messages from other sites, always verify the sender's identity using the origin and possibly source properties. Any window (including, for example, http://evil.example.com) can send a message to any other window, and you have no guarantees that an unknown sender will not send malicious messages. Having verified identity, however, you still should always verify the syntax of the received message. Otherwise, a security hole in the site you trusted to send only trusted messages could then open a cross-site scripting hole in your site.
Additional Information
See https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage for more info on postMessage.