Skip to main content

Request/Response: Cart ID (cart_id)

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, precision and organization are crucial. PayTabs introduces the cart_id parameter, designed to streamline and enhance the transaction process for users. This feature allows merchants to assign a unique identifier to each payment and connect it to his cart or order identification, ensuring a seamless and accurate payment experience.
Instead of processing transactions without clear identifiers from his side a part of PayTabs tran_ref, the cart_id parameter enables merchants to track and manage each transaction individually. This unique identifier helps in maintaining organized records, simplifying transaction tracking, and improving overall payment accuracy.

By understanding the key parameters such as cart_id, 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_id parameter is essential for ensuring a smooth and organized transaction process. Here’s how it can benefit you:

  • Enhanced Transaction Tracking: By assigning a unique cart_id to each transaction, you can easily track and manage individual transactions. This helps in maintaining clear and organized records, making it simpler to monitor and reconcile payments.

  • Improved Accuracy: The cart_id parameter ensures that each transaction is uniquely identified, reducing the risk of errors and duplications. This accuracy is crucial for maintaining reliable financial records and providing a seamless customer experience.

  • Streamlined Operations: With a unique identifier for each transaction, you can streamline your payment processes. This makes it easier to handle multiple transactions simultaneously, improving overall operational efficiency.

  • Better Customer Support: In case of any issues or disputes, having a unique cart_id allows for quick and precise identification of the transaction in question. This facilitates faster resolution and enhances customer satisfaction.

  • Detailed Reporting: The cart_id parameter enables detailed reporting and analysis of transactions. You can generate comprehensive reports that provide insights into sales patterns, customer behavior, and other key metrics, helping you make informed business decisions.

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

  • E-commerce Platforms: Online retailers can use the cart_id parameter to uniquely identify each shopping cart, ensuring accurate tracking of customer orders and simplifying inventory management.

  • Subscription Services: Companies offering subscription-based models, such as streaming services or software providers, can benefit by using the cart_id to manage recurring payments and track individual subscription transactions.

  • Travel and Hospitality: Travel agencies, airlines, and hotels can assign unique cart_ids to bookings, making it easier to manage reservations, cancellations, and modifications, and ensuring a seamless customer experience.

  • Healthcare Services: Clinics, hospitals, and other healthcare providers can manage payments for consultations, treatments, and refunds by categorizing transactions appropriately, ensuring accurate billing and financial management.

  • Education and Training: Educational institutions and training centers can use the tran_type parameter to handle payments for tuition, course materials, and refunds, providing a clear and organized payment process for students and parents.

  • Event Management: Event organizers can benefit by categorizing transactions for ticket sales, sponsorships, and refunds, ensuring a smooth and organized payment process for various events and activities.

  • Non-Profit Organizations: Charities and non-profits can manage donations, event registrations, and refunds by using different transaction types, making it easier to track and manage contributions.

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_id, cart_amount, 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_id 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_id within the main request payload itself as shown below. You need also to ensure that all required parameters are included and correctly formatted.

    {
        ...
        "cart_id": "Cart_Id_1",
        ....
    }

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

    Warning

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

    {
        ...
        "cart_id": "Cart_Id_1",
        ....
    }

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

    Parameter
    cart_id
    DescriptionIndicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to.
    To know more about this parameter please click here.
    Data TypeSTRING
    Required✔
    Min1
    Max64
    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_id you passed in the request payload, along with the redirect URL. This means you have initiated a correct payment request/page successfully.

    {
        "cart_id": "Cart Identification",
        .
        .
        "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.