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.


Note that ApplePay payment method does not operate in iFrame modes



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





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.


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