Skip to main content

Request/Response: Transaction Reference (tran_ref)

Be Aware Of

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

The tran_ref parameter in the PayTabs acts as a unique transaction reference identifier. It serves as an important reference point for querying transaction details and managing your transaction processes such as refunds, reversals and captures.

A clear understanding of the key parameter tran_ref will enable you to effectively manage your transactions and address any issues that you or your customers might encounter.



How this parameter could benefit you?​

Here are some scenarios to help you understand when to use the parameter parameter:

  • Unique Transaction Reference:

    The tran_ref serves as a unique reference for each transaction, that important for tracking and managing your transactions, also this can be used between the merchant and customer communications or between merchant and PayTabs team communications.

  • Query Transactions:

    You can use the "tran_ref" to retrieve a a full detailed information about a specific transaction via Query Transactions.

  • Manage Existing Transactions:

    The "tran_ref" allows merchants to manage transactions, including:

    • Refund: Process partial (if supported) or full refunds for a transaction.
    • Void: release a transaction amount that has not yet been captured.
    • Capture: Finalize a transaction that was previously authorized.
  • Facilitates Efficient Payment Processes:

    Ensures seamless integration for managing transactions, enhancing merchant control and flexibility, and aids in resolving payment issues efficiently by linking all actions to a specific transaction reference.



Limitations​

  • Once you initiate a Payment Page will create a [Temporary] transaction, and the transaction ref will be returned within the response. The transaction state would be changed to [Permanent] after any action taken by the user (customer).

    After the Payment Page expiration time elapsed, which is 20 minutes, if no action had been taken from the user side, the page would be expired, and the transaction would be considered deleted from the PayTabs system.


How to Use?​

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

  • You have to initiate a payment using any of the Integration Types Supported by PayTabs..

  • Once the payment is completed whether it is authorized, canceled, declined, etc you will get the transaction reference within payment response or you can find in the dashboard.

    {
                "tran_ref": "TST2234701408XXX"
    }
  • then you can store it for any further follow-up transaction related to this referance.
Warning

[Temporary] transactions CAN NOT be found on the PayTabs Dashboard, or by using query transaction request, and will be handled as an invalid transaction ref.

Please check the following possible HTTPs error responses:

If you use a temporary or invalid transaction with Query transaction you will get the error: 400 Bad Request. 

{
    "code": 113,
    "message": "Transaction not found",
    "trace": "PMNTXXXX.6769XXXX.0005XXXX"
}


Parameter Specifications​

  • tran_ref

    Parameter
    tran_ref
    DescriptionIndicates the Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref]
    Data TypeSTRING
    Required✘
    Sample
    {
        "tran_ref": "TST2234701408XXX"
    }

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": {{profile_id}},
    "cart_type": "sale",
    "tran_class": "ecom",
    "cart_id": "CART#1001",
    "cart_description": "Unique order reference00",
    "cart_amount": 25000.2,
    "cart_currency": "SAR"
]
}

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 redirect URL. This means you have initiated a correct payment request/page successfully.

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4818688",

  3. Next, you should embed this url inside your checkout page directly using the needed mark up tags

  4. After this, your customer would proceed normally with payment by providing his card information, and he will be able to do that withing your story as you can see below:

  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.