Voids and Refunds API

For a deeper understanding of voids and refunds, including key concepts and considerations, refer to this document.

Considerations per Country

Before using the Voids and Refunds API, keep in mind the following country-specific considerations.

  Argentina

Voids	Refunds
Send the request within 14 days; otherwise, the system automatically voids the transaction.	Request a refund at least 10 minutes after approval and up to 357 days after the transaction. Do not include decimal amounts in refunds. You can request more than one partial refund for payments made through AMEX, Mastercard, Naranja, or Visa. Once approved, PayU transfers the funds to the payer within 30 working days.

  Brazil

Voids

Refunds

Send the request within 7 days; otherwise, the system automatically voids the transaction.

Request a refund at least 10 minutes after approval. For transactions made with PIX, request refunds up to 87 days after the transaction. For card transactions, request refunds up to 172 days after the transaction. You can request more than one partial refund for payments made through AMEX, Elo, Mastercard, PIX, or Visa. Once approved, refunds for PIX transactions are processed immediately. Once approved, refunds for other payment methods take up to 15 working days.

  Chile

Voids

Refunds

Send the request within 3 hours after the transaction; otherwise, the network does not authorize the void. If the void is not accepted or no capture is sent within 7 days, the system automatically voids the transaction.

Request a refund at least 10 minutes after approval and up to 327 days after the transaction. Refunds are also available for transactions processed through WebPay Plus or Redcompra. For prepaid card transactions not processed by WebPay Plus: If you request a refund within the first hour, the financial network may approve or reject it. If you request a refund after the first hour, the financial network automatically rejects it. If the financial network rejects a refund, PayU displays the corresponding error code. Do not include decimal amounts in refunds. Once approved, the payer receives the funds within 8 to 20 working days. You can submit partial refunds for transactions with installments; PayU receives them online but processes them manually due to acquirer restrictions. Follow minimum refund amounts required by the acquiring network: More than 10 CLP for transactions processed by TRANSBANK. More than 50 CLP for transactions processed by KLAP. You can request more than one partial refund for payments made through AMEX, Mastercard, or Visa.

  Colombia

Voids

Refunds

Voids are available only when the 2-step flow is enabled (AUTHORIZATION followed by CAPTURE). In this case, you can cancel an authorization before it is captured. This option is supported only for Visa and MasterCard transactions.

Request a refund at least 10 minutes after approval and up to 357 days after the transaction. The minimum refund amount is 100 COP. If you do not submit the refund request on the same day as the transaction capture (before 9 PM UTC-5), PayU processes it manually instead of attempting it online. Once approved, the payer receives the funds within 15 working days. Request only one partial refund per order. If the customer asks for an additional refund, process it outside of PayU (e.g., through a gift card, discount, or bank transfer). You can also use our Payouts API to send the amount directly from your PayU account balance. This option is only available under the aggregator model and requires requesting the customer’s bank account details each time. This is especially useful for Alternative Payment Methods such as Efecty or PSE. Partial refunds for international credit cards are not available. Partial refunds (only one per order) are available for payments made through AMEX, Codensa, Diners, Mastercard, or Visa.

  Mexico

Voids

Refunds

Send the request at least 10 minutes after authorization and up to 7 days. If you do not send a void or capture within this timeframe, the system automatically voids the transaction.

Request a refund at least 10 minutes after approval. For most transactions, request refunds up to 175 days after the transaction. For transactions processed by Bancomer, request refunds up to 40 days after the transaction. Once approved, the payer receives the funds within 30 working days. Do not include decimal amounts in refunds. You can request more than one partial refund for payments made through AMEX, Mastercard, or Visa.

  Panama

Voids	Refunds
The integration does not support voids for transactions in Panama.	Request a refund at least 10 minutes after approval and up to 357 days after the transaction. Once approved, the payer receives the funds within 8 working days.

  Peru

Voids

Refunds

Follow the maximum timeframe allowed by each payment network: Visa: 21 days → If you do not send a void or capture, the system auto-captures the transaction. Mastercard: 28 days → If you do not send a void or capture, the system auto-captures the transaction. American Express: 30 days → If you do not send a void or capture, the system auto-voids the transaction. Diners: 11 days → If you do not send a void or capture, the system auto-voids the transaction.

Request a refund at least 10 minutes after approval and up to 357 days after the transaction. Request partial refunds only for transactions without installments (including single-installment transactions). For Visanet transactions, send partial refunds at least one day after the transaction. The minimum refund amount is 1 USD or 1 PEN. You can request more than one partial refund for payments made through AMEX, Diners, Mastercard (credit or debit), or Visa (credit or debit). Once approved, the payer receives the funds within 15 to 25 working days.

Void

The VOID method cancels a previously authorized transaction. This is an automatic process—as soon as the system submits a VOID request, it does not follow any approval flow, and the integration will not charge the transaction to the cardholder.

Parameters for Request and Response

API Call

The following examples show the request and response bodies for this transaction type.

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "id": "1400462414"
      },
      "type": "VOID",
      "reason": "Reason for requesting the void of the transaction",
      "parentTransactionId": "c8ec8737-7645-4756-a991-6e60a99eb4d9"
   },
   "test": false
}

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": {
        "orderId": 1400462414,
        "transactionId": "57546e0a-8275-48e3-af11-7d3dc7420bfe",
        "state": "APPROVED",
        "paymentNetworkResponseCode": "0",
        "paymentNetworkResponseErrorMessage": null,
        "trazabilityCode": "49263990",
        "authorizationCode": "NPS-011111",
        "pendingReason": null,
        "responseCode": "APPROVED",
        "errorCode": null,
        "responseMessage": "APROBADA - Autorizada",
        "transactionDate": null,
        "transactionTime": null,
        "operationDate": 1624880273010,
        "referenceQuestionnaire": null,
        "extraParameters": null,
        "additionalInfo": null
    }
}

<request>
   <language>es</language>
   <command>SUBMIT_TRANSACTION</command>
   <merchant>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
   </merchant>
   <transaction>
      <order>
         <id>1400462466</id>
      </order>
      <type>VOID</type>
      <parentTransactionId>50876ad6-46f2-4c8d-bb91-2f028b56ccb8</parentTransactionId>
   </transaction>
   <isTest>false</isTest>
</request>

<paymentResponse>
    <code>SUCCESS</code>
    <transactionResponse>
        <orderId>1400462466</orderId>
        <transactionId>5fbb1ab0-3d2e-448f-a0be-b0bcfb5501ae</transactionId>
        <state>APPROVED</state>
        <paymentNetworkResponseCode>0</paymentNetworkResponseCode>
        <trazabilityCode>49263990</trazabilityCode>
        <authorizationCode>NPS-011111</authorizationCode>
        <responseCode>APPROVED</responseCode>
        <responseMessage>APROBADA - Autorizada</responseMessage>
        <operationDate>2021-06-28T06:57:44</operationDate>
    </transactionResponse>
</paymentResponse>

Refunds

A refund is issued when a merchant voluntarily returns the payment to the shopper. This can happen due to customer dissatisfaction or when the product is out of stock. The REFUND method reverses a previously captured transaction.

Refunds can be issued for the full amount or as a partial refund (PARTIAL_REFUND).

Parameters for Request and Response

API Call

The following examples show the request and response bodies for this transaction type.

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "id": "1400462687"
      },
      "type": "REFUND",
      "reason": "Reason for requesting the refund of the transaction",
      "parentTransactionId": "60e2080d-08b1-4db2-a54f-8bcbe8271662"
   },
   "test": false
}

{  
   "command":"SUBMIT_TRANSACTION",
   "language":"es",
   "merchant":{  
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction":{  
      "additionalValues":{  
         "TX_VALUE":{  
            "value":"950",
            "currency":"ARS"
         }
      },
      "order":{  
         "id":"1400462690"
      },
      "parentTransactionId":"0486359b-a048-4b6b-9b72-af584e710e64",
      "reason":"Reason for requesting the refund or cancellation of the transaction",
      "type":"PARTIAL_REFUND"
   }
}

{
    "code": "SUCCESS",
    "error": null,
    "transactionResponse": {
        "orderId": 1400462690,
        "transactionId": null,
        "state": "PENDING",
        "paymentNetworkResponseCode": null,
        "paymentNetworkResponseErrorMessage": null,
        "trazabilityCode": null,
        "authorizationCode": null,
        "pendingReason": "PENDING_REVIEW",
        "responseCode": null,
        "errorCode": null,
        "responseMessage": "1400462690",
        "transactionDate": null,
        "transactionTime": null,
        "operationDate": null,
        "referenceQuestionnaire": null,
        "extraParameters": null,
        "additionalInfo": null
    }
}

<request>
   <language>es</language>
   <command>SUBMIT_TRANSACTION</command>
   <merchant>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
   </merchant>
   <transaction>
      <order>
         <id>1400462689</id>
      </order>
      <type>REFUND</type>
      <reason>Reason for requesting the refund of the transaction.</reason>
      <parentTransactionId>1d31ea44-0d8f-4e65-93ac-6be4347e5b40</parentTransactionId>
   </transaction>
   <isTest>false</isTest>
</request>

<request>
   <command>SUBMIT_TRANSACTION</command>
   <language>es</language>
   <merchant>
      <apiKey>4Vj8eK4rloUd272L48hsrarnUA</apiKey>
      <apiLogin>pRRXKOl8ikMmt9u</apiLogin>
   </merchant>
   <transaction>
      <additionalValues>
         <entry>
            <string>TX_VALUE</string>
            <additionalValue>
               <value>950</value>
               <currency>ARS</currency>
            </additionalValue>
         </entry>
      </additionalValues>
      <order>
         <id>1400462690</id>
      </order>
      <parentTransactionId>0486359b-a048-4b6b-9b72-af584e710e64</parentTransactionId>
      <reason>Reason for requesting the refund or cancellation of the transaction</reason>
      <type>PARTIAL_REFUND</type>
   </transaction>
</request>

<paymentResponse>
    <code>SUCCESS</code>
    <transactionResponse>
        <orderId>1400462691</orderId>
        <transactionId>6cef020a-8006-4744-b7f9-d9a343807297</transactionId>
        <state>PENDING</state>
        <pendingReason>PENDING_REVIEW</pendingReason>
        <responseMessage>1400462690</responseMessage>
    </transactionResponse>
</paymentResponse>

Querying the Refund Status

As mentioned earlier, refund requests go through an approval process. PayU usually takes 1 to 3 days to review and either approve or reject the request. You can check the refund status using one of the following methods:

Checking the Status via the PayU Management Panel

1. Log in to the PayU Management Panel. In the left menu, expand the Transactions tab and select Sales Report.

   

2. Use the Filter my sales field to search for the order using the order ID or transaction ID.

   
   

3. Check the Status column to see whether the refund is approved, rejected, or still pending.

   

Checking the Status via the Queries API

You can also check the refund status using the Queries API. To do so, send a request with the order ID.

When you query an order, the system returns the most recent transaction associated with it.

The response can indicate one of three statuses:

• Unresolved Request: The refund request is still under review. The order shows a CAPTURED status (result.payload.status in the response).

  • The first transaction type is AUTHORIZATION_AND_CAPTURE (result.transactions.type in the response).
  • The first transaction status is APPROVED (result.transactions.transactionResponse.state in the response).

• Approved: A PayU customer service agent approved the refund request. The order shows a REFUNDED status (result.payload.status in the response).

  • The first transaction type is REFUND (result.transactions.type in the response).
  • The first transaction status is APPROVED (result.transactions.transactionResponse.state in the response).

• Declined: A PayU customer service agent rejected the refund request. The order shows a CAPTURED status (result.payload.status in the response).

  • The first transaction type is REFUND (result.transactions.type in the response).
  • The first transaction status is DECLINED (result.transactions.transactionResponse.state in the response).

Handling Pending Refunds with the PayU Cancellations Module

This section will guide you on how to track the final status of a refund that you initiated through the PayU Cancellations Module, especially when you are relying on the Queries API for updates.

Manual Cancellations Module and Pending Refund Updates

When you request a refund through the Voids and Refunds API, PayU submits the request to the payment network. If the network rejects the refund, PayU initially returns a PENDING status in the paymentResponse.transactionResponse.state field.

In this scenario, PayU automatically activates the Cancellations Module to retry the refund. This process may involve multiple attempts, each generating a new refund ID, until a final status is reached. This mechanism improves refund success rates and reduces the need for merchants to submit multiple manual attempts.

To confirm whether the refund request submitted through the Voids and Refunds API has reached a final status (APPROVED or DECLINED), you should:

• Query its status using the Queries API (by order ID), or
• Wait for a notification via your configured webhook (notifyUrl for API integrations or the Confirmation Page for WebCheckout).

Identifying the Final Refund Status in the Queries API

To distinguish between your initial refund request and the attempts generated by the PayU Cancellations Module, use the order ID in the Queries API and check the following fields:

• result > payload > status – General order status (REFUNDED if the full amount was refunded; CAPTURED may indicate partial refunds).
• result > payload > transactions[] > id – Refund transaction ID.
• result > payload > transactions[] > type – Transaction type (REFUND or PARTIAL_REFUND).
• result > payload > transactions[] > source – Source (EMPTY = online refunds, CANCELLATIONS_MODULE = retries via PayU Cancellations Module).
• result > payload > transactions[] > transactionResponse > state – Refund status (PENDING, APPROVED, DECLINED).
• result > payload > transactions[] > transactionResponse > operationDate – Date and time when the refund was generated.
• result > payload > transactions[] > additionalValues > TX_VALUE > value – Refund amount.
• result > payload > transactions[] > extraParameters > MANUAL_REFUND – Indicates how the refund was processed (absent, TRUE, or FALSE).

Rules for Updating Refund Status

Follow these rules when updating your system:

Additional Considerations

• If the final status is DECLINED after the Cancellations Module operation, you may submit a new refund request via the Refunds API. When doing so, avoid updating based on previous transaction attempts — use operationDate and TX_VALUE to track the correct refund attempt.
• Always register one refund record per API request in your system, even if the Cancellations Module created multiple transactions.
• Update your refund record only when a final status is reached, following the rules above.

Identifying the Final Refund Status via Webhook

PayU also notifies you of the final refund status through your configured webhook (notifyUrl for API integrations or Confirmation Page for WebCheckout).

Webhook Logic

• If the refund request status is APPROVED or DECLINED, PayU immediately sends a webhook notification.
• If the refund status is initially PENDING, no webhook is sent until a final status (APPROVED or DECLINED) is reached.

Webhook Update Rules

• If the initial status is PENDING, do not update the refund until you receive the webhook.
• Once the webhook arrives, update the refund status accordingly (APPROVED or DECLINED).
• Use at least the following fields from the payload to identify the refund correctly:
  • transaction_type – Transaction type
  • value – Refund amount
  • response_message_pol – Response message
  • transaction_date – Date and time of the transaction

Webhook Considerations

Unlike the Queries API, the webhook only notifies you once the refund reaches a final status. No notifications are sent for intermediate attempts (PENDING) or retries within the Cancellations Module.

For this reason, we recommend implementing the webhook if you have not already done so. It allows you to update refund statuses automatically without applying the manual validation rules required for the Queries API.

This behavior applies when the following account settings are enabled:

• Allow reversal transactions with pending state: Off
• Activate pending response for voids and refunds: On