Void 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 void a transaction means that the previously authorized/held amount from a previous auth transaction will be released back to the cardholder's bank account from his own bank side, as it was kept on hold there. 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

Void requests are available for ONLY authenticated Auth transactions that are NOT fully captured yet.

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 void request, you have to pass a tran_type that MUST be void which handed via the method and the transaction reference of the original authenticated Auth transaction that you want to void, 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 void transaction, as shown below:

{
     "tran_ref": "TST2509502044803",
     "previous_tran_ref": "TST2016700000692",
     "tran_type": "Void",
     "cart_id": "cart_11111",
     "cart_description": "Void 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"
 }