Skip to main content

Request: Theme select (config_id)

Warning

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


This article explains how to select a specific theme for payments using the config_id parameter during the initiation of the payment. The config_id corresponds to a particular theme, allowing the merchant to choose from the themes listed on their PayTabs dashboard and apply the desired theme by passing the appropriate config_id

How this parameter could benefit you?​

Here are some scenarios to help you understand when to use the config_id parameter:

  • Customization: The config_id parameter allows you to fully customize the payment page according to your branding and design preferences by selecting a specific theme from your PayTabs dashboard.

  • Themed Experience: Merchants can create a unique payment experience for customers by offering different visual themes for different campaigns, product categories, or marketing initiatives.

  • Multiple Themes for Different Use Cases: By using different config_id values, merchants can tailor the payment page for specific use cases (e.g., promotions, seasonal sales, or regional preferences) without the need for creating separate payment pages.

  • Brand Consistency: Ensure that the payment page aligns with your website’s look and feel, maintaining a consistent brand identity across all customer touchpoints.

  • Ease of Implementation: Once themes are created in the PayTabs dashboard, merchants can easily switch between them by simply passing the relevant config_id during the payment initiation, streamlining the process of applying themes.

  • Improved Customer Experience: Providing a visually cohesive and on-brand payment page can enhance customer trust and improve conversion rates, as users feel more comfortable completing transactions in a familiar environment.

  • Flexibility for A/B Testing: Merchants can experiment with different themes to see which one results in higher conversion rates or better customer engagement, optimizing the payment experience.

  • Look and Feel: The PayTabs payment page can be customized to match the look and feel of your online store. While the payment page will still have a different URL, it will function in the same way as a hosted payment page.

  • Avoid Redirecting Technical Issues: Embedding the payment page helps you avoid issues like the SameSite Cookie problem. This issue can cause the session to be cleared when a customer is redirected back to your store after payment, potentially disrupting the transaction process.

Limitations​

While the config_id parameter offers several benefits, there are some limitations to consider:

  • Restricted to Predefined Themes: The config_id parameter is limited to selecting from predefined themes available in the PayTabs dashboard. Merchants are not able to create or apply fully custom themes beyond those provided by PayTabs.

  • Dependency on PayTabs Dashboard: Merchants must rely on the themes configured in the PayTabs dashboard. Custom themes, or themes created outside of the dashboard, cannot be applied to the payment page via the config_id parameter.

How to Use?​

In order for you to start use the config_id 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 config_id within the main request payload itself as shown below:

    {    
        .
        .
        "config_id": 2202
        .
        .
    }

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

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

  • Finally, you will need to redirect your customer to this URL for them to proceed with the payment process. The customer will be directed to the payment page where they will see the desired theme based on the selected config_id. You may want to check the customer experience in the upcoming section on Expected Payment Flow Behavior.

Parameter Specifications​

  • config_id

    Parameter
    config_id
    DescriptionAllows you to choose between your list of themes that have been created on your PayTabs dashboard. This chosen theme will be applied to the created payment page.
    Data TypeINT
    Required✘
    Validation RulesValid Theme ID (from PayTabs dashboard)
    Sample
    {
        "config_id": 2202
    }


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": 1800XXX,
    "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",
    "config_id": 2202
}

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.


  2. 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",

  3. Next, you should redirect your customer to the payment page displayed using the theme ID you have used ( you can have multiple theme and pass the needed config_id ) using this steps:
    • Navigate to Developers
    • PayPage Configuration
    • PayPage Settings (Themes).
    • then choose the desired id

    transaction view

    be aware of
    Note that the checked theme as in the following Screenshot, is the default one, means that if you didn't pass any config_id, the default will work

    transaction view

  4. After this, your customer would proceed normally with payment by providing his card information and press the PAY NOW button.

  5. Then, he will be redirected to his issuer bank 3DS/OTP page to authenticate the used card

  6. Finally, he would be redirect to a success/error page accordingly. By this time, 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.