Skip to main content

Request/Response: Cart Amount (cart_amount)

Warning

This parameter behaving the same regardless of the integration type you are using.

In the evolving landscape of online payments, precision and transparency are paramount. PayTabs introduces the required cart_amount parameter, designed to enhance the transaction experience for users. This feature allows merchants to specify the total amount for each shopping cart, ensuring a clear and accurate payment process.
Instead of processing transactions with ambiguous amounts, the cart_amount parameter enables merchants to define the exact amount to be charged. This clarity helps in maintaining accurate records, reducing errors, and providing a seamless payment experience.

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

  • Accurate Billing: By specifying the exact amount to be charged, the cart_amount parameter ensures that customers are billed correctly. This accuracy helps in maintaining trust and satisfaction among your customers.

  • Clear Financial Records: The cart_amount parameter allows for precise tracking of transaction amounts, making it easier to maintain clear and organized financial records. This is essential for accounting and auditing purposes.

  • Enhanced Customer Experience: Providing a clear and accurate cart amount improves the overall customer experience. Customers appreciate transparency in pricing, which can lead to increased loyalty and repeat business.

  • Streamlined Operations: With the cart_amount parameter, you can streamline your payment processes. This makes it easier to handle multiple transactions simultaneously, improving operational efficiency and reducing manual intervention.

  • Better Reporting and Analysis: The cart_amount parameter enables detailed reporting and analysis of sales data. You can generate comprehensive reports that provide insights into sales trends, 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_amount parameter to ensure accurate billing for each shopping cart, enhancing the customer experience and maintaining clear financial records.

  • Subscription Services: Companies offering subscription-based models, such as streaming services or software providers, can benefit by using the cart_amount to manage recurring charges and ensure precise billing for each subscription cycle.

  • Travel and Hospitality: Travel agencies, airlines, and hotels can specify the total amount for bookings, making it easier to manage reservations, cancellations, and modifications, and ensuring a seamless customer experience.

  • Healthcare Providers: Clinics and hospitals can use the cart_amount to track payments for different services, such as consultations, treatments, and diagnostics, ensuring accurate billing and financial management.

  • Education Institutions: Schools and universities can benefit by using the cart_amount 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 the total amount 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_amount to manage donations, event registrations, and other transactions, 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_amount, 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.

  • Transaction Amount Limit: The amount specified by the cart_amount parameter can be subject to a "Transaction Amount Limit" configured in the merchant's account. This limit, if set, restricts the maximum and the minimum amounts that can be processed in a single transaction. You MUST need to be aware of these limits to avoid transaction failures.

How to Use?​

In order for you to start use the cart_amount 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_amount 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": 100,
        ....
    }

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

    Warning

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

    {
        ...
        "cart_amount": 100,
        ....
    }

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

    Parameter
    cart_amount
    DescriptionIndicates the amount of the transaction the customer is about to be charged. Both min and max values are subjected to the merchant transaction limits.
    To know more about this parameter please click here.
    Data TypeDECIMAL
    Required✔
    Min0.01
    Max9999999999.99
    Sample
    {
         "cart_amount": 500.99
    }

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

    {
        "cart_amount": "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.

    Warning

    If the transaction cart_amount falls outside the "Transaction Amount Limit" set in the merchant's account, which defines the maximum and minimum amounts that can be processed in a single transaction, it will result in a transaction failure.

    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.