Skip to main content

Request/Response: Cart Currency (cart_currency)

Warning

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

n the evolving landscape of online payments, precision and global compatibility are crucial. PayTabs introduces the required cart_currency parameter, designed to enhance the transaction experience for users. This feature allows merchants to specify the currency in which the transaction will be processed, ensuring a seamless and accurate payment process.
Instead of processing transactions with ambiguous currency details, the cart_currency parameter enables merchants to define the exact currency for each transaction. This clarity helps in maintaining accurate records, reducing errors, and providing a seamless payment experience.

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

  • Global Compatibility: By specifying the currency for each transaction, the cart_currency parameter allows you to cater to international customers, enhancing your global reach and customer satisfaction.

  • Clear Financial Records: The cart_currency parameter helps maintain clear and organized financial records by accurately reflecting the currency used in each transaction. This is crucial for accounting and auditing purposes.

  • Enhanced Customer Experience: Providing a clear and accurate currency for transactions enhances the overall customer experience, as customers can see the exact amount they will be charged in their local currency.

  • Simplified Reporting and Analysis: The cart_currency parameter enables detailed reporting and analysis of sales data across different currencies. This helps you understand your sales performance in various markets and make informed business decisions.

  • Compliance with Regulations: Ensuring that transactions are processed in the correct currency helps maintain compliance with financial regulations and standards, reducing the risk of legal issues.

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

  • E-commerce Platforms: Online retailers can use the cart_currency parameter to cater to international customers by allowing transactions in multiple currencies, enhancing the shopping experience and expanding their global reach.

  • Subscription Services: Companies offering subscription-based models, such as streaming services or software providers, can benefit by using the cart_currency to manage recurring charges in the customer's preferred currency, ensuring accurate and consistent billing.

  • Travel and Hospitality: Travel agencies, airlines, and hotels can specify the currency for bookings, making it easier to manage international reservations and providing a seamless experience for travelers.

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

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

  • Event Management Companies: Event organizers can specify the currency for ticket sales, sponsorships, and merchandise, ensuring a smooth and organized payment process for attendees from different countries.

  • Non-Profit Organizations: Charities and non-profits can use the cart_currency to manage donations, event registrations, and other transactions, making it easier to track and manage contributions from international donors.

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_currency, cart_amount, cart_id, 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.

  • Profile-Specific Configuration: The types of currencies available are limited to those configured in the merchant's profile. If a specific currency is not set up in your profile, it cannot be used for transactions.

  • Acquirer Bank Support: Not all currencies are supported by every acquiring bank. Some banks may have restrictions on certain currencies, which could require special agreements or additional documentation. It's important to verify with your acquiring bank which currencies are supported.

  • Regulatory Compliance: Certain currencies may be subject to regulatory restrictions or requirements, depending on the region or industry. Compliance with these regulations is essential to avoid legal issues.

How to Use?​

In order for you to start use the cart_currency 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_currency within the main request payload itself as shown below. You need also to ensure that all required parameters are included and correctly formatted.

    You Should Be Aware Of

    It is not necessary for customers to pay with a card or bank account that matches the cart_currency. The cart_currency parameter defines the currency in which the transaction will be settled. The customer's issuing bank will handle any necessary currency conversion at the applicable exchange rate. This ensures that customers can make payments in their preferred currency, while the transaction is processed in the specified cart_currency.

    {
        ...
        "cart_currency": "SAR",
        ....
    }

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

    Warning

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

    {
        ...
        "cart_currency": "SAR",
        ....
    }

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

    Parameter
    cart_currency
    DescriptionIndicates the transaction currency, which the customer will be charged with.
    To know more about this parameter please click here.
    Data TypeSTRING
    Required✔
    Min1
    Max128
    Validation RulesValid string from the following list: SAR AED BHD EGP EUR GBP HKD IDR INR IQD JOD JPY KWD MAD OMR PKR QAR USD
    Accepts both upper/lower case characters
    Sample
    {
         "cart_currency": "SAR"
    }

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

    {
        "cart_currency": "SAR",
        .
        .
        "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.

    You Should Be Aware Of

    It is not necessary for customers to pay with a card or bank account that matches the cart_currency. The cart_currency parameter defines the currency in which the transaction will be settled. The customer's issuing bank will handle any necessary currency conversion at the applicable exchange rate. This ensures that customers can make payments in their preferred currency, while the transaction is processed in the specified cart_currency.

    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_currency 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.