Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.
This article is dedicated to the clarification of the Framed message target (framed_message_target) parameter. "framed_message_target" is one of the optional parameters of the request, which allows you when hosting the payment page in an embed frame within your site page itself and with the Paytabs default return page (return: "None"), to receive the message after the payment is done using the javascript, which gives your system the ability to close the iFrame after payment.
For more information please check our solution articles:
- How to not redirect my customers to an external payment page? (iFrame/Embedded Mode).
- Request Parameters | The Framed Mode (framed | framed_return_parent | framed_return_parent).
In this article, you will be going to know:
Specifications
Framed Message Target
The Parameter Tag/Name framed_message_target JSON Example Data Type URI Required ❌Validation Rules - A valid HTTPS website URL
Usage Workflow
Along with the required parameters mentioned in our PT2 API Endpoints | Initiating the payment solution article, you need to set the "framed" as on the article Request Parameters | The Framed Mode while using Paytabs default return page, as on the article Request/Response Parameters | The Return URL (return) You may need to have a listener to check whenever the payment is done to do an action like closing the iFrame, that could be done using the following example:
Sample Request Payload
Sample Response Payload
The Expected Parameter Behaviors
To Listen to the message sent to the default Paytabs return page You need at least to enable the framed mode along with using the "framed_message_target" with your HTTPS URI.
The scenario will go through opening the Paytabs payment page within the iframe, and after the payment, since no return page was set within the request, the customer would be redirected to the Paytabs default return page.
Meanwhile, a message event would be sent to the target URI as set on the parameter "framed_message_target", to receive the message you can use the following sample
<!DOCTYPE html>
<html lang="en">
<head>
<title>iFrame PostMessage</title>
</head>
<body>
<div class="container">
<iframe src="https://secure-egypt.paytabs.com/payment/wr/5EA2DCFF82E51F92B58D61B6ED6ECECF93717313DFCC2EE46FC9165C" frameborder="1" style="width: 100%; height: 600px; border: 1px solid blue;"></iframe>
</div>
</body>
<script>
window.addEventListener("message", function(evt) {
// Check event origin and data:
if (evt.data == 'hppDone' // evt.data must be the string "hppDone"
&& evt.origin == "https://secure-egypt.paytabs.com" // evt.origin must be the domain the payment page is on (e.g. https://secure.paytabs.com)
) {
// alert('Done');
console.log("----------------------- <evt.data> -------------------");
console.log(evt.data);
console.log("----------------------- </evt.data> ------------------");
console.log("----------------------- <evt.origin> -----------------");
console.log(evt.origin);
console.log("----------------------- </evt.origin> ----------------");
console.log("----------------------- <evt> ------------------------");
console.log(evt);
console.log("----------------------- </evt> -----------------------");
// If data and origin match, then take appropriate actions such as closing the iframe and initiating a server side check to verify the transaction results.
}
});
</script>
</html>Note that in the above sample we used the merchant endpoint "https://secure-egypt.paytabs.com" this is why we had checked the evt.origin == "https://secure-egypt.paytabs.com", You need to make sure you are checking the correct Paytabs website accourding to your endpoint, to know more about your endpoint kindly check What is my (Region)/(endpoint URL)?
- Passing a valid HTTPS URI in framed_message_target
- Not Passing the target URL in framed_message_target
Passing a valid HTTPS URI in framed_message_target
As per the above example by passing a valid HTTPS URI, Your system frontend will be able to receive the message event after the redirection to the Paytabs default return page.
Not Passing the target URL in framed_message_target
Your system will not receive any message events after redirection.