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).

Request/Response Parameters | The Return URL (return).

In this article, you will be going to know:


  • Framed Message Target

    The Parameter Tag/Nameframed_message_target
    JSON Example
        "return": "none", 
        "framed": true, 
        "framed_message_target": "https://MERCHANT_WEBSITE.COM"
    Data TypeURI
    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


"profile_id": "987654",
"tran_type": "sale",
"tran_class": "ecom", 
"cart_id": "CART#1001",
"cart_currency": "USD",
 "cart_amount": 500, 
"cart_description": "Description of the items/services",

    "return": "none",
    "framed": true,
    "framed_message_target": "https://MERCHANT_WEBSITE.COM"


Sample Response Payload


    "tran_ref": "TST2312001574403",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "USD",
    "cart_amount": "500",
    "tran_currency": "",
    "tran_total": "0",
    "return": "none",
    "redirect_url": "https://sec****************************2A989D2F4EE5A817AF9B6D4",
    "serviceId": 2,
    "profileId": 987654,
    "merchantId": 123456,
    "trace": "PM****04.64****31.00****C9"

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

    <title>iFrame PostMessage</title>

    <div class="container">
		<iframe src="" frameborder="1" style="width: 100%; height: 600px; border: 1px solid blue;"></iframe>

    window.addEventListener("message", function(evt) {
        // Check event origin and data:
        if ( == 'hppDone' 										// must be the string "hppDone"
			&& evt.origin == ""			// evt.origin must be the domain the payment page is on (e.g.
			) {
            // alert('Done');
			console.log("----------------------- <> -------------------");
			console.log("----------------------- </> ------------------");
			console.log("----------------------- <evt.origin> -----------------");
			console.log("----------------------- </evt.origin> ----------------");
			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.


Note that in the above sample we used the merchant endpoint "" this is why we had checked the evt.origin == "", 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)?

The expected behaviors according to the passed value are

  • 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.