Skip to main content

Request/Response: Cart Description (cart_description)

Warning

This parameter ONLY working with those integration types (Hosted Payment Page, Managed Form, Own Form, and Invoices).

In the evolving landscape of online payments, clarity and detailed information are crucial. PayTabs introduces the required cart_description parameter, designed to enhance the transaction experience for users. This feature allows merchants to provide a detailed description of the items or services in the shopping cart, ensuring a transparent and informative payment process.
Instead of processing transactions with vague or incomplete information, the cart_description parameter enables merchants to specify the contents of the cart clearly. This transparency helps in maintaining accurate records, reducing disputes, and providing a seamless payment experience.

By understanding the key parameters such as cart_description, businesses can effectively integrate this feature to cater to their operational needs and enhance the customer experience.

How this parameter could benefit you?​

The cart_description parameter is essential for ensuring a smooth and organized transaction process. Here’s how it can benefit you:

  • Enhanced Transparency: By providing a detailed description of the items or services in the shopping cart, the cart_description parameter ensures that customers have a clear understanding of what they are purchasing. This transparency helps in building trust and reducing disputes.

  • Accurate Record-Keeping: Including detailed descriptions in transactions helps maintain accurate records. This is crucial for accounting, auditing, and resolving any potential discrepancies that may arise.

  • Improved Customer Experience: Clear and detailed descriptions enhance the customer experience by providing all necessary information upfront. This reduces confusion and increases customer satisfaction.

  • Better Reporting and Analysis: The cart_description parameter allows for more detailed reporting and analysis of sales data. You can gain insights into which products or services are performing well, helping you make informed business decisions.

  • Compliance with Regulations: Providing detailed descriptions can help ensure compliance with various regulatory requirements related to transaction transparency and consumer protection.

Name but a few different Businesses/Industries that can benefit from this API parameter:

  • E-commerce Platforms: Online retailers can use the cart_description parameter to provide detailed descriptions of products in the shopping cart, enhancing transparency and improving the customer shopping experience.

  • Subscription Services: Companies offering subscription-based models, such as streaming services or software providers, can benefit by using the cart_description to detail the contents of subscription packages, ensuring customers understand what they are paying for.

  • Travel and Hospitality: Travel agencies, airlines, and hotels can specify detailed descriptions for bookings, including flight details, accommodation specifics, and package inclusions, ensuring a clear and informative booking process.

  • Healthcare Providers: Clinics and hospitals can use the cart_description to detail the services provided, such as consultations, treatments, and diagnostics, ensuring accurate billing and clear communication with patients.

  • Education Institutions: Schools and universities can benefit by using the cart_description to manage payments for tuition, course materials, and other fees, providing a clear and organized payment process for students and parents.

  • Event Management Companies: Event organizers can specify detailed descriptions for ticket sales, sponsorships, and merchandise, ensuring a smooth and organized payment process for various events and activities.

  • Non-Profit Organizations: Charities and non-profits can use the cart_description to manage donations, event registrations, and other transactions, providing clear and detailed information to donors and participants.

Limitations​

  • Mandatory Inclusion: This parameter must be included in every payment creation request. Omitting this parameter will result in the failure of the request.

  • Duplicate Request Error: If the same details (cart_description, cart_description, cart_currency, profile_id) are duplicated within less than 2 minutes, it will cause a duplicate request error. This is a safeguard to prevent accidental double charges or duplicate transactions.

How to Use?​

In order for you to start use the cart_description parameter, you kindly need to follow the below simple steps:

  • Within the initiation of the request payload of the payment page as mentioned in Step 3 via regardless the integration types, you will MUST use the mandatory parameter cart_description within the main request payload itself as shown below. You need also to ensure that all required parameters are included and correctly formatted.

    {
        ...
        "cart_amount": "Description of the items/services",
        ....
    }

  • Once you post your request, you will receive a response that includes the cart_description as well:

    Warning

    Only in "Invoices" integration type (via the invoice endpoint), you will NOT receive the cart_description in the response, as mentioned in theInvoices - Step 3 | Initiate the payment manual.

    {
        ...
        "cart_amount": "Description of the items/services",
        ....
    }

  • Depending on the integration type and the request, not within all the payments life cycle, you will will need to redirect the customer to the payment page or any other external links for either authenticate the cardholder via the 3D Secure or other needed actions.
    You may need to check his customer experience after in the coming Expected Payment Flow Behavior.

Parameter Specifications​

  • cart_description

    Parameter
    cart_description
    DescriptionIndicates the cart/order description at the merchant end, to easily relate the PayTabs transaction to.
    To know more about this parameter please click here.
    Data TypeSTRING
    Required✔
    Min1
    Max128
    Sample
    {
         "cart_id": "CART#10001"
    }

Request & Response Payloads Samples​

The below sample request payload will show you how you can pass the above-mentioned required parameter, 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": "79010",
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "cart_1",
    "cart_currency": "SAR",
    "cart_amount": 12.3,
    "cart_description": "Description of the items/services",
    "paypage_lang": "en",
    "customer_details": {
       "name": "FirstName LastName",
       "email": "[email protected]",
       "phone": "9771555555555",
       "street1": "street2",
       "city": "dubai",
       "state": "dubai",
       "country": "AE",
       "zip": "54321"
    },
    "shipping_details": {
        "name": "FirstName LastName",
        "email": "[email protected]",
        "phone": "971555555555",
        "street1": "street2",
        "city": "dubai",
        "state": "dubai",
        "country": "AE",
        "zip": "54321"
    }
}

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 the same cart_description you passed in the request payload, along with the redirect URL. This means you have initiated a correct payment request/page successfully.

    {
        "cart_description": "Description of the items/services",
        .
        .
        "redirect_url": "https://secure.paytabs.com/payment/page/52E5B6B*************B4818688",
        .
        .
    }

  3. Next, you should redirect your customer to this URL so the payment process can be finalized.

  4. After this, your customer would proceed normally with payment by choosing the preferred payment method (if available), and providing his card information.

    Payment Page

  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.