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 (framed) parameter. "framed" is one of the optional parameters of the request, which allows you to host the payment page in an embed frame within your site page itself.

  

 For more information please check our How to not redirect my customers to an external payment page? (iFrame/Embedded Mode)solution article.


Be aware that ApplePay, SamsungPay, and Tappy payment methods DO NOT operate in the iFrame mode



In this article, you will be going to know:

Specifications 


  • Framed


    The Parameter Tag/Nameframed
    JSON Example
    { "framed":true }
    Generic
    Data TypeBOOLEAN 
    Required
    ❌
    Validation Rules
    • true or false



  • Framed Return Top

      

    The Parameter Tag/Nameframed_return_top
    JSON Example
    {  "framed_return_top": true }
    Generic
    Data TypeBOOLEAN 
    Required
    ❌
    Validation Rules
    • true or false





  • Framed Return Parent


    The Parameter Tag/Nameframed_return_parent
    JSON Example
    { "framed_return_parent": true }
    Generic
    Data TypeBOOLEAN 
    Required
    ❌
    Validation Rules
    • true or false




  • Framed Message Target

    The Parameter Tag/Name
    		framed_message_target
    JSON Example

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

    Generic

    Data Type
    		URI
    Required
    		❌
    Validation Rules
    • A valid HTTPS website URL



Usage Workflow


Along with the required parameters mentioned in our Step 3 - PT2 API Endpoints | Initiating the payment solution article, you may need to set the "framed" as shown below:

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",
  "framed": true,
  "framed_return_parent": true,
  "framed_return_top": true
}
JavaScript



Sample Response Payload

   

{
  "tran_ref": "TST2231101374414",
  "tran_type": "Sale",
  "cart_id": "CART#1001",
  "cart_description": "Description of the items/services",
  "cart_currency": "USD",
  "cart_amount": "500.00",
  "tran_currency": "",
  "tran_total": "0",
  "return": "none",
  "redirect_url": "https://secure-egypt.paytabs.com/payment/page/599***D7",
  "serviceId": 2,
  "profileId": 987654,
  "merchantId": 123456,
  "trace": "PMNT0404.6368BC3D.000BAF4C"
}
JavaScript

The Expected Parameter Behaviors


To enable the framed mood, you need at least use the framed property. The other properties (framed_return_top, framed_return_parent) are optional to control the reload/redirect behavior. To preview the payment page within your page instead of redirecting to the payment page.



Now you can use the redirect_url within the HTML iframe tag to embed the payment link in your site as shown below:


<iframe src="https://sec******.paytabs.com/payment/page/599******0AC4EB3D4B8B5948324" width="" height=""></iframe>




The expected behaviors according to the passed value are:



  • Passing a true framed_return_top


    Indicates whether to reload the whole page on redirections or just reload the current frame




  • Passing a true framed_return_parent


    Indicates whether to reload the main base (could be div or another iFrame tag) that contained the payment page framed element.
       

  • Passing a valid HTTPS URI in framed_message_target
        

    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. 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. You can learn more by clicking here.
       



  • Using redirect URL from none farmed request


    If you tried a redirect_url that belongs to none-framed transactions, the server would display this error "paytabs.com refused to connect", as shown below: