Skip to main content

Request: Iframe Mode (framed, framed_return_parent, framed_return_top, framed_message_target)

Warning

This parameter ONLY working with those integration types (Hosted Payment Page, Invoices(Payment Endpoint)).

With our iFrame Mode feature, you can enhance the checkout experience by keeping customers on your site throughout the payment process. Instead of redirecting them to a separate payment page, you can embed the hosted payment page directly within your site using an iframe HTML tag, providing a seamless and integrated experience.

Furthermore with customizing the hosted payment page to match your website’s design, ensuring consistency with your brand while maintaining a secure payment environment. iFrame Mode offers a smoother, more cohesive experience for your customers by eliminating the need for redirection during checkout. For more details about how to customize the UI please check How to customize the PayPage (Hosted Payment Page) UI?

How these parameters could benefit you?​

Here are some scenarios to help you understand when to use the iframe mode:

  • Seamless Integration with Checkout Page: This helps to increase conversion rates by keeping the customer within the same checkout flow, minimizing distractions.

  • Improved Control Over Customer Navigation: By ensuring that customers are redirected to a main page after payment, it keeps them focused on your site and reduces abandonment.

  • Enhanced User Experience: Keeping the payment within the same page makes the experience smoother, reducing frustration and improving transaction completion rates.

  • Flexible Redirection Options: Provides the flexibility to redirect customers as needed, aligning the checkout flow with your business strategy.

  • Maintaining Parent Page Stability: Prevents disruptions by avoiding unnecessary reloads, helping maintain the consistency and reliability of your website during transactions.

  • Efficient Response Handling: Helps streamline the backend process by efficiently handling payment responses, ensuring quick updates and reducing potential delays.

Limitations​

Unfortunately, not all payment methods support this feature due to their business/security flow. So here are the payment methods that support this feature. If you want a specific payment method that is not listed below, you will have to use our hosted payment page with redirecting mode.

  • What are the payment methods that support the iFrame mode exclusively?
    • All Types of Cards (such as MasterCard, Mada, Meeza ... etc)
    • UnionPay
    • STC Pay
    • ValU
    • Meeza QR
    • Aman

How to Use?​

In order for you to start using the iFrame Mode feature, you kindly need to follow the below simple steps:

  • Within the initiation of the request payload of the payment page/link in Step 3 via any of the supported integration types by this feature, you will use the optional parameter framed within the main request payload itself as shown below:

    {
        .
        .
        "framed":true
        .
        .
    }

  • Once you post your request, you will receive a response that includes a redirect URL like the following:

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",

  • Finally, you will need to embed this URL inside your checkout page using the iframe tag, as this is crucial for your customer to proceed through the payment process. You may need to check the customer experience after in the coming Expected Payment Flow Behavior.

Parameter Specifications​

Framed
Parameter
framed
DescriptionIndicates whether to preview the payment page within the current check page instead of redirection or not. If ✔, preview the redirect URL sent in the response in '<iframe>' HTML tag, which will preview the whole payment page within this frame.
To know more about this parameter please click here.
Data TypeBOOLEAN
Required✘
Sample
{
    "framed":true
}
framed_return_top
Parameter
framed_return_top
DescriptionIndicates whether to reload the whole page on redirections or just reload the current frame.
To know more about this parameter please click here.
Data TypeBOOLEAN
Required✘
Sample
{
    "framed_return_top": true
}
framed_return_parent
Parameter
framed_return_parent
DescriptionIndicates whether to reload the main base (could be div or another iFrame tag) that contained the payment page framed element.
To know more about this parameter please click here.
Data TypeBOOLEAN
Required✘
Sample
{
    "framed_return_parent": true
}
framed_message_target
Parameter
framed_message_target
DescriptionIf you didn't have a return URL, 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
Data TypeURI
Required✘
Validation RulesA valid HTTPS website URL of your domain (the recipient) that will receive the event. In order for the event to be dispatched, this domain must match exactly (including scheme, hostname, and port).
Sample
{
    "framed_message_target": 'https://MERCHANT_WEBSITE.COM' 
}

Request & Response Payloads Samples​

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

{
    "profile_id": {{profile_id}},
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_description": "Description of the items/services",
    "cart_id": "Unique order reference00",
    "cart_amount": 25000.2,
    "cart_currency": "SAR",
    "framed":true,
    "framed_return_top": true,
    "framed_return_parent": true,
    "framed_message_target": "https://MERCHANT_WEBSITE.COM"



}

Expected Payment Flow Behavior​

  1. As mentioned above in the How to use? section, As a merchant you would initiate a payment request per the above Specifications, same as the sample codes mentioned in the samples section above.

    • This behavior is about passing framed only.Additionally, let's assume that our Onboarding link is the return URL. ( just to show exact behavior)
      {
          .
          .
          "framed":true,
          "return" : "https://site.paytabs.com/Onboarding/Technical-Onboarding.html",
          .
          .
      }

    • Then, you will receive a response that includes redirect URL. This means you have initiated a correct payment request/page successfully.

      "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",

    • Next, you should embed this url inside your checkout page directly using the needed mark up tags

      <iframe src="https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688" width="" height="" >  </iframe>

    • Then,Then customer can proceed normally and adding his card information. However he can see the payment page embed in a frame like that( size of frame is depending on width and height you provide)
      single framed view
    • Then, he will be redirected to his issuer bank 3DS/OTP page to authenticate the used card, inside the iframe

    • After, the customer the payment and passes the 3Ds step, the return page will be shown inside the frame

      single framed view
      If no return URL passed you will see PayTabs default page. inside the frame like this

      single framed view

    • Finally, you will be able to see his transaction on your merchant dashboard, whether it's accepted/authorized or not.

      transaction view

      transaction view

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.