Refund Transaction

To refund a transaction means to return/transfer back a transaction amount from your bank account to the customer's bank account. It will be logged as a new separated transaction with this type, and it will be related to the previous "Sale" or "Capture" transaction. In this manual, we walk you through how to use and manage the mentioned endpoint.

Refund request is available ONLY for those Authenticated Sale transactions or Authenticated Capture transactions. In which the tran_type MUST be “refund”, and the requested transaction id to be refunded MUST be passed to the tran_ref parameter in the request.

you should know

Through out the article we will use the transaction types clarified in ourWhat is the "tran_type" (transaction type)?solution article.

---

The Endpoint and Related Postman Collection

In this tutorial, we will rely on the PayTabs Refund Transaction API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access fromhere. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST	{{domain}}/payment/request

Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

KSA

https://secure.paytabs.sa/payment/request

UAE

https://secure.paytabs.com/payment/request

Egypt

https://secure-egypt.paytabs.com/payment/request

Oman

https://secure-oman.paytabs.com/payment/request

Jordan

https://secure-jordan.paytabs.com/payment/request

Kuwait

https://secure-kuwait.paytabs.com/payment/request

Global

https://secure-global.paytabs.com/payment/request

---

The Minimum Required Parameters

To initiate a Refund payment request, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below:

Parameter	Data Type	Min	Max	Required
tran_ref	STRING			✘
	Indicates the Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref]
	{ "tran_ref": "TST2234701408XXX" }

---

Sample Request Payloads

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.

be aware of

Refund request is ONLY available for successfully Authorized (A) transactions.

{
    "profile_id": 703XX,
    "tran_type": "refund",
    "tran_class": "ecom",
    "cart_id": "CART#10001",
    "cart_currency": "SAR",
    "cart_amount": 99.99,
    "cart_description": "Refund reason",
    "tran_ref": "TST2016700000XXX"
}

be aware of

Be aware that the tran_type MUST be Refund.

---

Sample Response Payloads

{
    "tran_ref": "TST2105900091XXX",
    "previous_tran_ref": "TST2016700000XXX",
    "tran_type": "Refund"
    "cart_id": "CART#10001",
    "cart_description": "Refund reason",
    "cart_currency": "SAR",
    "cart_amount": "99.99",
    "tran_currency": "SAR",
    "tran_total": "99.99",
    "customer_details": {
        "name": "Technical Support",
        "email": "[email protected]",
        "phone": "+966 55 xxxxxx6",
        "street1": "address street",
        "city": "Jeddah",
        "state": "Makkah",
        "country": "SA",
        "zip": "22230"
    },
    "payment_result": {
        "response_status": "A",
        "response_code": "036501",
        "response_message": "Authorised",
        "acquirer_message": "00:Approved",
        "acquirer_rrn": "42550903****",
        "transaction_time": "2024-09-11T09:01:51Z"
    },
    "payment_info": {
        "payment_method": "MasterCard",
        "card_type": "Credit",
        "card_scheme": "MasterCard",
        "payment_description": "5500 00## #### 5559",
        "expiryMonth": 12,
        "expiryYear": 2026
    },
    "user_defined": {
        "udf1": "UDF1 Test",
        "udf2": "UDF2 Test",
        "udf3": "UDF3 Test",
        "udf4": "UDF4 Test",
        "udf5": "UDF5 Test",
        "udf6": "UDF6 Test",
        "udf7": "UDF7 Test",
        "udf8": "UDF8 Test",
        "udf9": "UDF9 Test"
    },
    "serviceId": 1,
    "profileId": 703XX,
    "merchantId": 46XXX,
    "trace": "PMNT****.6769****.0005****"
}