Refund Transaction

PayTabs provides you with the backend packages that make the integrating with PayTabs payment gateway very easy by providing ready-made classes that handle the payment process.

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 article, we walk you through how to use and manage the below function:

Method Specification

Description	Used to make a direct request.
Since	1.0.0
Required	✔
Signature	/** * @function createPaymentPage * @param {Array} transactionDetails - List of transaction details (Reference, type and class). * @param {Array} cartDetails - Cart details including ID, currency, amount, and description. * @param {methods} callback - Invoked upon the function is successful make the request. */ PayTabs.queryTransaction(transactionDetails, cartDetails, callback);
Sample	PayTabs.queryTransaction( transactionDetails, cartDetails, callback );

Be Aware Of

Refund request is available ONLY for those authenticated Sale transactions or authenticated Capture transactions.

Note

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

---

Method Parameters:

TransactionDetails

Name	transactionDetails
Type	ARRAY
Array Element values:	First transactionReference 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. Type Validation Rules Required String Valid Transaction Reference ✔ transactionType Valid Transaction Reference Type Validation Rules Required enum Define the nature of each transaction like sale, auth, capture, or refund. ✔ transactionClass Identifies the class of transaction being processed, such as Ecom, Moto, and Recurring. Type Validation Rules Required enum Should be <code>ecom</code> <b><u>ONLY</u></b ✔
Description	Array of transaction details elements (Reference, type and class)
Default	-
Required	✔
Example	let transactionDetails = [ transaction.ref, transaction.typ, transaction.cls ];

---

CartDetails

Name	cartDetails
Type	ARRAY
Array Element values:	First cart_id Indicates the cart/order id at the merchant end to easily relate the transaction to. Type Min Max Required String 1 64 ✔ Second cart_currency Indicates the transaction currency, which the customer will be charged with. Noting that this currency must be configured first on your PayTabs account to accept payment with. Type Validation Rules Required String Must be in ISO Alpha-3 Format. ✔ Third cart_amount Indicates the amount the customer is about to be charged with. Both min and max values are subjected to the merchant transaction limits. Type Min Max Required Decimal 0.01 9999999999.99 ✔ Fourth cart_description Indicates the cart/order description at the merchant end to easily relate the transaction to. Type Min Max Required String 1 128 ✔
Description	This is the second parameter of the queryTransaction() function, which handles the payment cart details (e.g ID, Currency, etc).
Default	-
Required	✔
Example	let cartDetails = [ cart.id, cart.currency, cart.amount, cart.description ];

---

Callback

Name	callback
Type	Method
Description	A callback function invoked upon the successful of the request.
Default	-
Required	✔
Example	let transactionCreated = function ($results){ console.log($results); }

---

Sample Request:

To process a refund request, you have to pass a tran_type that MUST be refund which handed via the method and the transaction reference of the original authenticated Sale or Capture transaction that you want to refund, as shown in the below sample:

PayTabs.queryTransaction(
    transactionDetails,
    cartDetails,
    callback
);

---

Sample Response Payload:

The response PayTabs will send to you will be a JSON object that contains the full details regarding this refund transaction, as shown below:

{
     "tran_ref": "TST2509502044803",
     "previous_tran_ref": "TST2016700000692",
     "tran_type": "Refund",
     "cart_id": "cart_11111",
     "cart_description": "Refund reason of the items/services.",
     "cart_currency": "SAR",
     "cart_amount": "500.00",
     "tran_currency": "SAR",
     "tran_total": "500.00",
     "customer_ref":"CUST0101",
     "customer_details": {
          "name": "Technical Support Team",
          "email": "[email protected]",
          "phone": "+966 55 xxxxxx6",
          "street1": "address street",
          "city": "Jeddah",
          "state": "Makkah",
          "country": "SA",
          "zip": "12345"
           "ip": "156.221.244.35"
      },
     "payment_result": {
         "response_status": "A",
         "response_code": "G40178",
         "response_message": "Authorised",
         "transaction_time": "2022-12-14T15:53:58Z"
     },
     "payment_info": {
         "payment_method": "Visa",
         "card_type": "Credit",
         "card_scheme": "Visa",
         "payment_description": "4000 00## #### 0002",
         "expiryMonth": 12,
         "expiryYear": 2026
     },
     "serviceId": 1,
     "paymentChannel": "Transaction API",
     "merchant_id": 31000,
     "profile_id": 81000,
     "trace": "PMNT0402.67F0E000.00108000"
 }