Skip to main content

Request/Response: Transaction Type (tran_type)

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 precision are essential. PayTabs introduces the tran_type parameter, one of the required/must parameters & designed to streamline and specify transaction types for users. This feature allows merchants to define the nature of each transaction, ensuring a seamless and accurate payment process.
Instead of a generic transaction process, the tran_type parameter enables merchants to categorize transactions as sale, authorization, capture, or refund. This categorization provides clarity and control over the payment flow, enhancing the overall transaction experience.

You Should Know

To know more about our supported different transaction types, you may need to check our What is the "tran_type" (transaction type)? solution article.

By understanding the key parameters such as tran_type, businesses can effectively integrate this feature to cater to their operational needs and improve transaction management.

How this parameter could benefit you?​

The tran_type parameter is essential for defining the nature of each transaction, and its benefits are substantial:

  • Enhanced Transaction Clarity: By specifying the transaction type (e.g., sale, authorization, capture, or refund), you can ensure that each transaction is processed correctly and efficiently. This clarity helps in reducing errors and misunderstandings.

  • Improved Financial Management: With clear transaction types, your financial records become more organized. This makes it easier to track and reconcile transactions, leading to better financial management and reporting.

  • Streamlined Operation: The tran_type parameter allows for streamlined operations by categorizing transactions appropriately. This helps in automating processes and reducing manual intervention, saving time and resources.

  • Increased Security: By defining transaction types, you can implement specific security measures for each type. For example, authorizations can have different security protocols compared to refunds, enhancing overall transaction security.

  • Regulatory Compliance: Properly categorizing transactions helps in maintaining compliance with financial regulations and standards. This reduces the risk of non-compliance and potential penalties.

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

  • Retail and E-commerce: Online stores can use the tran_type parameter to manage sales, authorizations, captures, and refunds efficiently, ensuring smooth and accurate transaction processing for various product categories and customer segments.

  • Hospitality and Travel: Hotels, airlines, and travel agencies can benefit by categorizing transactions for bookings, cancellations, and refunds. This helps in maintaining clear records and providing a seamless experience for travelers.

  • Subscription Services: Companies offering subscription-based models, such as streaming services or software providers, can use different transaction types to handle initial payments, recurring charges, and refunds, enhancing customer satisfaction and operational efficiency.

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

  • Profile-Specific Configuration: The types of transactions available are limited to those configured in the merchant's profile. This means that if a specific transaction type is not set up in your profile, it cannot be used.

  • Acquirer Bank Support: Not all transaction types are supported by every acquiring bank. Some banks may have restrictions on certain types of transactions, such as authorizations or refunds. It's important to verify with your acquiring bank which transaction types are supported.

  • Regulatory Restrictions: Certain transaction types 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 tran_type parameter, you kindly need to follow the below simple steps.
As each different transaction type would have a different payment behavior, you will find two different casinos the DIRECT, in which payment flow no customer engagement is needed, and the Engaging one which requires a customer engagement to complete the payment process.

Engaging transaction types, which requires a customer engagement in the payment flow to complete the process are: sale auth register . Below, is how this parameter is gonna used over these types:

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

    {
        ...
        "tran_type": "sale"
        ....
    }

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

    Warning

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

    {
       ...
       "tran_type": "sale"
       ....
    }

  • Depending on the integration type and the request, not within all the transaction types' 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​

  • tran_type

    Parameter
    tran_type
    DescriptionThe identification of the type of the transaction. To know more about these types please check our What is the "tran_type" (transaction type)? solution article.
    To know more about this parameter please click here.
    Data TypeINT
    Required✔
    Validation Rules

    Valid string from this enum list:

    sale auth void release capture refund register
    Sample
    {
        "tran_type": "sale"
    }

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​

As each different transaction type would have a different payment behavior, you will find two tags DIRECT which indicates that this a direct payment flow no customer engagement is needed, and the Engaging for the other, that requires a customer engagement. Below will show you the payment flow for each:

Engaging

  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.
    However, you will need to pass the value sale within the tran_type parameter.

  2. Then, you will receive a response that includes the same tran_type you passed in the request payload, along with the redirect URL. This means you have initiated a correct payment request/page successfully.

    {
        .
        "tran_type": "sale",
        .
        "redirect_url": "https://secure.paytabs.com/payment/page/52E5B*********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. Once he had a successful payment, the payment amount will be directly charged from his issuer bank account and transferred to the acquirer bank account 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.