Skip to main content

Void Transaction

PayTabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.

void a transaction means that the previously authorized/held amount from a previous auth transaction (that reserved but not yet transferred to the merchant acquirer bank) will be released back to the cardholder's bank account from his own bank side, as it was kept on hold there. In this manual, we walk you through how to use and manage the mentioned endpoint.

Void requests are available for ONLY Authenticated Authorized transactions that are not fully captured yet.

To process a void request, tran_type should be void, and the transaction reference of the original auth transaction that you want to void should be passed in the tran_ref parameter.

you should know

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

be aware of

Be aware that Void request is ONLY available for successfully Authorized Auth (A) transactions that not captured yet.

and that the tran_type MUST be Void.


be aware of

An authorized ( Auth ) transaction remains on hold at the customer’s bank for a limited period, which varies by issuing bank but typically ranges between 7 to 14 days.

If neither a capture nor a void request is performed before this period ends, the authorized amount is automatically released back to the customer’s account by the bank.




In this tutorial, we will rely on the PayTabs Void Transaction API Endpoint, mentioned on the PayTabs API endpoints postman collection, which you can access fromhere. he endpoint will need to be accessed with the mentioned HTTP request via the below URL endpoint:

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.

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


The Minimum Required Parameters​

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

ParameterData TypeMinMaxRequired
profile_id
INT

STRING		Accept only valid profile number.✔
The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article. To know more about this parameter please click here.
{
 "profile_id": 987654
}
tran_type
STRING

Valid string from this enum list:

sale auth void release capture refund register		✔
The identification of the type of the transaction. in the response payload it's returned in the sucess only 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.
{
 "tran_type": "sale"
}
tran_class
STRING

Valid string from this list

ecom recurring moto		✔
The identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article.
To know more about this parameter please click here.
{
 "tran_class": "ecom"
}
cart_id
STRING164✔
Indicates the cart/order id at the merchant end, it should be a unique value at the merchant end. to easily relate the PayTabs transaction to.
at the response payload it's returned in sucess only
To know more about this parameter please click here.
{
 "cart_id": "CART#10001"
}
cart_description
STRING1128✔
Indicates the cart/order description at the merchant end,it should be something descrips the reason of the transaction at the merchant end, to easily relate the PayTabs transaction to.
at the response payload it's returned in success only
To know more about this parameter please click here.
{
 "cart_description": "Description of the items/services"
}
cart_currency
STRING1128✔
Indicates the transaction currency, which the customer will be charged with.
To know more about this parameter please click here.
{
 "cart_currency": "SAR"
}
cart_amount
int|float|string0.019999999999.99✔
Indicates the amount of the transaction the customer is about to be charged. Both min and max values are subjected to the merchant transaction limits.
if param donation_mode is true, cart_amount is not required and will be ignored
at the response payload it's returned in sucess only
To know more about this parameter please click here.
{
 "cart_amount": 500.99
}
ParameterData TypeMinMaxRequired
tran_ref
STRING✘
Indicates the Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref]
at the response payload it's returned in success only
{
 "tran_ref": "TST2234701408XXX"
}


Sample Request/Response Payloads​

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, 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": 83061,
  "tran_type": "void",
  "tran_class": "ecom",
  "cart_id": "CART#10001",
  "cart_currency": "SAR",
  "cart_amount": 200,
  "cart_description": "Cart Description",
  "tran_ref": "TST2234701408XXX"
}


Expected Flow Behavior​

Reaching this stage, you are now able to initiate a Void Transaction, which is handled as a follow-up transaction. A void can only be performed against successful Authorization (AUTH) transactions. The void process releases the authorized amount back to the customer’s account before it is captured.

  1. Initial Authorization Transaction:

    1. The merchant first initiates an Authorization transaction using the payment APIs, regardless of the API integration type (e.g., Invoices, Hosted Payment Page, etc.).

    2. Upon successful authorization, a transaction reference (tran_ref) is returned.

    3. The authorized amount is temporarily held on the customer’s account and has not yet been captured.

    4. The merchant must securely store this transaction reference for any future follow-up actions.

  2. Preparing for a Void:

    1. Void transactions are allowed only for transactions of typeAuthorization (AUTH) that have not yet been captured.

    2. The previously saved tran_ref is required to initiate the void request.

    3. The void request must include all required parameters as defined in theMinimum Required Parameters.

  3. Initiating the Void Request:

    The merchant sends a void request using the follow-up Void API, using the mentionedendpoint, and passes the original authorization transaction reference along with the required details.


  4. Successful Void Scenario:

    1. In the happy-path scenario, the void is processed successfully. The system releases the authorized amount, returning it to the customer’s account, and the authorization hold is removed.


    2. At this point, you will see the void transaction response as described above. For more details, refer to theSample Request/Response Payload.


    3. Below is a sample from the dashboard showing how a voided transaction appears:

      Voided Transaction Sample

  5. Void Failure Scenarios:

    A void request may fail under certain conditions. Common reasons include:


    • The authorization has already been captured.

    • The authorization has expired, means the amount no longer held on customer bank acount.

    • Transaction type not Auth.

    In these cases, the void request is rejected and a detailed failure reason is returned in the response, allowing the merchant to take the appropriate action.

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.