API de Anulações e Reembolsos

A API de Anulações e Reembolsos permite cancelar ou reembolsar transações que foram autorizadas ou capturadas. Dependendo do status da transação, você pode enviar uma solicitação usando os métodos Void ou Refund.

Para entender melhor as anulações e reembolsos, incluindo conceitos-chave e considerações, consulte este documento.

Considerações por país

Antes de usar a API de Anulações e Reembolsos, leve em conta as seguintes considerações específicas por país.

  Argentina
Anulações Reembolsos
  • Envie a solicitação em até 14 dias; caso contrário, o sistema anula automaticamente a transação.
  • Solicite um reembolso pelo menos 10 minutos após a aprovação e até 357 dias após a transação.
  • Não inclua valores decimais nos reembolsos.
  • Você pode solicitar mais de um reembolso parcial para pagamentos feitos com AMEX, Mastercard, Naranja ou Visa.
  • Uma vez aprovado, a PayU transfere os fundos ao pagador em até 30 dias úteis.
  Brasil
Anulações Reembolsos
  • Envie a solicitação em até 7 dias; caso contrário, o sistema anula automaticamente a transação.
  • Solicite um reembolso pelo menos 10 minutos após a aprovação.
  • Para transações feitas com PIX, solicite reembolsos em até 87 dias após a transação.
  • Para transações com cartão, solicite reembolsos em até 172 dias após a transação.
  • Você pode solicitar mais de um reembolso parcial para pagamentos feitos com AMEX, Elo, Mastercard, PIX ou Visa.
  • Uma vez aprovado, os reembolsos de transações PIX são processados imediatamente.
  • Uma vez aprovado, os reembolsos de outros métodos de pagamento levam até 15 dias úteis.
  Chile
Anulações Reembolsos
  • Envie a solicitação em até 3 horas após a transação; caso contrário, a rede não autoriza a anulação.
  • Se a anulação não for aceita ou nenhuma captura for enviada em até 7 dias, o sistema anula automaticamente a transação.
  • Solicite um reembolso pelo menos 10 minutos após a aprovação e até 327 dias após a transação.
  • Os reembolsos também estão disponíveis para transações processadas através de WebPay Plus ou Redcompra.
  • Para transações com cartões pré-pagos não processadas pelo WebPay Plus:
    • Se solicitar um reembolso na primeira hora, a rede financeira pode aprová-lo ou rejeitá-lo.
    • Se solicitar um reembolso após a primeira hora, a rede financeira o rejeita automaticamente.
  • Se a rede financeira rejeitar um reembolso, a PayU exibirá o código de erro correspondente.
  • Não inclua valores decimais nos reembolsos.
  • Uma vez aprovado, o pagador recebe os fundos em até 8 a 20 dias úteis.
  • Você pode enviar reembolsos parciais para transações com parcelamento; a PayU os recebe online, mas os processa manualmente devido a restrições do adquirente.
  • Siga os valores mínimos de reembolso exigidos pela rede adquirente:
    • Mais de 10 CLP para transações processadas pela TRANSBANK.
    • Mais de 50 CLP para transações processadas pela KLAP.
  • Você pode solicitar mais de um reembolso parcial para pagamentos feitos com AMEX, Mastercard ou Visa.
  Colômbia
Anulações Reembolsos
  • As anulações estão disponíveis apenas quando o fluxo em duas etapas está habilitado (AUTHORIZATION seguido de CAPTURE). Nesse caso, você pode cancelar uma autorização antes que ela seja capturada. Essa opção está disponível somente para transações com Visa e MasterCard.
  • Solicite um reembolso pelo menos 10 minutos após a aprovação e até 357 dias após a transação.
  • O valor mínimo de reembolso é de 100 COP.
  • Se você não enviar a solicitação de reembolso no mesmo dia da captura da transação (antes das 21h UTC-5), a PayU o processará manualmente em vez de tentar online.
  • Uma vez aprovado, o pagador recebe os fundos em até 15 dias úteis.
  • Solicite apenas um reembolso parcial por pedido. Se o cliente solicitar um reembolso adicional, processe-o fora da PayU (por exemplo, por meio de cartão-presente, desconto ou transferência bancária). Você também pode usar nossa API de Payouts para enviar o valor diretamente do seu saldo na PayU. Essa opção está disponível apenas sob o modelo agregador e exige solicitar os dados da conta bancária do cliente a cada vez. Isso é especialmente útil para meios de pagamento alternativos como Efecty ou PSE.
  • Reembolsos parciais para cartões de crédito internacionais não estão disponíveis.
  • Reembolsos parciais (apenas um por pedido) estão disponíveis para pagamentos feitos com AMEX, Codensa, Diners, Mastercard ou Visa.
  México
Anulações Reembolsos
  • Envie a solicitação pelo menos 10 minutos após a autorização e em até 7 dias.
  • Se você não enviar uma anulação ou captura dentro desse prazo, o sistema anula automaticamente a transação.
  • Solicite um reembolso pelo menos 10 minutos após a aprovação.
  • Para a maioria das transações, solicite reembolsos em até 175 dias após a transação.
  • Para transações processadas pelo Bancomer, solicite reembolsos em até 40 dias após a transação.
  • Uma vez aprovado, o pagador recebe os fundos em até 30 dias úteis.
  • Não inclua valores decimais nos reembolsos.
  • Você pode solicitar mais de um reembolso parcial para pagamentos feitos com AMEX, Mastercard ou Visa.
  Panamá
Anulações Reembolsos
  • A integração não suporta anulações para transações no Panamá.
  • Solicite um reembolso pelo menos 10 minutos após a aprovação e até 357 dias após a transação.
  • Uma vez aprovado, o pagador recebe os fundos em até 8 dias úteis.
  Peru
Anulações Reembolsos
  • Siga o prazo máximo permitido por cada rede de pagamento:
    • Visa: 21 dias → Se você não enviar uma anulação ou captura, o sistema captura automaticamente a transação.
    • Mastercard: 28 dias → Se você não enviar uma anulação ou captura, o sistema captura automaticamente a transação.
    • American Express: 30 dias → Se você não enviar uma anulação ou captura, o sistema anula automaticamente a transação.
    • Diners: 11 dias → Se você não enviar uma anulação ou captura, o sistema anula automaticamente a transação.
  • Solicite um reembolso pelo menos 10 minutos após a aprovação e até 357 dias após a transação.
  • Solicite reembolsos parciais apenas para transações sem parcelamento (incluindo transações de parcela única).
  • Para transações Visanet, envie reembolsos parciais pelo menos um dia após a transação.
  • O valor mínimo de reembolso é 1 USD ou 1 PEN.
  • Você pode solicitar mais de um reembolso parcial para pagamentos feitos com AMEX, Diners, Mastercard (crédito ou débito) ou Visa (crédito ou débito).
  • Uma vez aprovado, o pagador recebe os fundos em até 15 a 25 dias úteis.

Anulação (Void)

O método VOID cancela uma transação previamente autorizada. Este é um processo automático—assim que a solicitação VOID é enviada, não segue nenhum fluxo de aprovação, e a transação não é cobrada do portador do cartão.

Parâmetros para Solicitação e Resposta

Solicitação
Nome do Campo Formato Tamanho Descrição Obrigatório
language Alfanumérico 2 Idioma utilizado na requisição. Define o idioma das mensagens de erro. Veja idiomas suportados. Sim
command Alfanumérico Máx: 32 Definir como SUBMIT_TRANSACTION. Sim
test (JSON)
isTest (XML)
Booleano Definir como true para modo de teste; caso contrário, false. Sim
merchant Objeto Contém os dados de autenticação. Sim
merchant > apiLogin Alfanumérico Mín: 12, Máx: 32 Usuário ou login fornecido pela PayU. Como obter API Login. Sim
merchant > apiKey Alfanumérico Mín: 6, Máx: 32 Senha fornecida pela PayU. Como obter API Key. Sim
transaction Objeto Contém os dados da transação. Sim
transaction > order Objeto Contém os detalhes do pedido. Sim
transaction > order > id Numérico ID do pedido a ser anulado. Sim
transaction > type Alfanumérico 32 Definir como VOID para cancelar uma transação autorizada. Sim
transaction > reason Alfanumérico Motivo da anulação da transação. Não
transaction > parentTransactionId Alfanumérico 36 ID da transação a ser anulada. Sim
Resposta
Nome do Campo Formato Tamanho Descrição
code Alfanumérico Código de resposta da transação. Valores possíveis: ERROR, SUCCESS.
error Alfanumérico Máx: 2048 Mensagem de erro quando o código de resposta é ERROR.
transactionResponse Objeto Contém os detalhes da resposta.
transactionResponse > orderId Numérico O ID do pedido gerado ou existente na PayU.
transactionResponse > transactionId Alfanumérico 36 ID da transação na PayU.
transactionResponse > state Alfanumérico Máx: 32 Status da transação.
transactionResponse > paymentNetworkResponseCode Alfanumérico Máx: 255 Código de resposta da rede financeira.
transactionResponse > paymentNetworkResponseErrorMessage Alfanumérico Máx: 255 Mensagem de erro da rede financeira.
transactionResponse > trazabilityCode Alfanumérico Máx: 32 Código de rastreabilidade da rede financeira.
transactionResponse > authorizationCode Alfanumérico Máx: 12 Código de autorização da rede financeira.
transactionResponse > responseCode Alfanumérico Máx: 64 Código de resposta relacionado ao status da transação.
transactionResponse > responseMessage Alfanumérico Máx: 2048 Mensagem relacionada ao código de resposta.
transactionResponse > operationDate Data Data em que a resposta foi gerada no sistema da PayU.

Chamada da API

Os exemplos a seguir mostram os corpos de requisição e resposta para este tipo de transação.


Exemplo de uma Solicitação:

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "id": "1400462414"
      },
      "type": "VOID",
      "reason": "Motivo do pedido de cancelamento da transação",
      "parentTransactionId": "c8ec8737-7645-4756-a991-6e60a99eb4d9"
   },
   "test": false
}

Exemplo de uma Resposta:

{
    "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
    }
}

Exemplo de uma Solicitação:

<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>

Exemplo de uma Resposta:

<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>

Reembolsos

Um reembolso é emitido quando o comerciante devolve voluntariamente o pagamento ao comprador. Isso pode ocorrer devido à insatisfação do cliente ou quando o produto está fora de estoque. O método REFUND reverte uma transação que já foi capturada.

Os reembolsos podem ser emitidos para o valor total ou como um reembolso parcial (PARTIAL_REFUND).

Parâmetros para Solicitação e Resposta

Solicitação
Nome do Campo Formato Tamanho Descrição Obrigatório
language Alfanumérico 2 Idioma usado na requisição. Isso determina o idioma das mensagens de erro. Veja os idiomas suportados. Sim
command Alfanumérico Máx: 32 Defina como SUBMIT_TRANSACTION. Sim
test (JSON)
isTest (XML)
Booleano Defina como true para o modo de teste; caso contrário, false. Sim
merchant Objeto Contém os dados de autenticação. Sim
merchant > apiLogin Alfanumérico Mín: 12, Máx: 32 Usuário ou login fornecido pela PayU. Como obter o API Login. Sim
merchant > apiKey Alfanumérico Mín: 6, Máx: 32 Senha fornecida pela PayU. Como obter o API Key. Sim
transaction Objeto Contém os dados da transação. Sim
transaction > additionalValues Objeto Especifica o valor para um reembolso parcial. Obrigatório para reembolsos parciais. Não
transaction > additionalValues > TX_VALUE Objeto Contém os detalhes do valor da transação. Obrigatório para reembolsos parciais. Não
transaction > additionalValues > TX_VALUE > value Número Máx: 19 Valor a ser reembolsado. Obrigatório para reembolsos parciais. Não
transaction > additionalValues > TX_VALUE > currency Alfanumérico 3 Código da moeda em formato ISO. Veja as moedas aceitas. Obrigatório para reembolsos parciais. Não
transaction > order Objeto Contém os detalhes do pedido. Sim
transaction > order > id Número ID do pedido a ser reembolsado. Sim
transaction > type Alfanumérico 32 Especifica o tipo de reembolso:
- REFUND para reembolsos totais.
- PARTIAL_REFUND para reembolsos parciais (se suportado).
Sim
transaction > reason Alfanumérico Motivo do reembolso. Não
transaction > parentTransactionId Alfanumérico 36 ID da transação original que está sendo reembolsada. Sim
Resposta
Nome do Campo Formato Tamanho Descrição
code Alfanumérico Código de resposta da transação. Valores possíveis: ERROR, SUCCESS.
error Alfanumérico Máx: 2048 Mensagem de erro quando o código de resposta é ERROR.
transactionResponse Objeto Contém os detalhes da resposta.
transactionResponse > orderId Número O ID do pedido gerado ou existente na PayU.
transactionResponse > transactionId Alfanumérico 36 ID da transação na PayU.
transactionResponse > state Alfanumérico Máx: 32 Status da transação.
transactionResponse > paymentNetworkResponseCode Alfanumérico Máx: 255 Código de resposta da rede financeira.
transactionResponse > paymentNetworkResponseErrorMessage Alfanumérico Máx: 255 Mensagem de erro da rede financeira.
transactionResponse > trazabilityCode Alfanumérico Máx: 32 Código de rastreabilidade da rede financeira.
transactionResponse > authorizationCode Alfanumérico Máx: 12 Código de autorização da rede financeira.
transactionResponse > responseCode Alfanumérico Máx: 64 Código de resposta associado ao status da transação.
transactionResponse > responseMessage Alfanumérico Máx: 2048 Mensagem associada ao código de resposta.
transactionResponse > operationDate Data Data em que a resposta foi gerada no sistema da PayU.

Chamada da API

Os exemplos a seguir mostram os corpos de requisição e resposta para esse tipo de transação.


Exemplo de uma Solicitação de Reembolso:

{
   "language": "es",
   "command": "SUBMIT_TRANSACTION",
   "merchant": {
      "apiKey": "4Vj8eK4rloUd272L48hsrarnUA",
      "apiLogin": "pRRXKOl8ikMmt9u"
   },
   "transaction": {
      "order": {
         "id": "1400462687"
      },
      "type": "REFUND",
      "reason": "Motivo do pedido de reembolso da transação",
      "parentTransactionId": "60e2080d-08b1-4db2-a54f-8bcbe8271662"
   },
   "test": false
}

Exemplo de uma Solicitação de Reembolso Parcial:

{  
   "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 ou cancellation da transação",
      "type":"PARTIAL_REFUND"
   }
}

Exemplo de uma Resposta:

{
    "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
    }
}

Exemplo de uma Solicitação de Reembolso:

<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>Motivo do pedido de reembolso da transação.</reason>
      <parentTransactionId>1d31ea44-0d8f-4e65-93ac-6be4347e5b40</parentTransactionId>
   </transaction>
   <isTest>false</isTest>
</request>

Exemplo de uma Solicitação de Reembolso Parcial:

<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>

Exemplo de uma Resposta:

<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>

Consultando o Status do Reembolso

Conforme mencionado anteriormente, os pedidos de reembolso passam por um processo de aprovação no qual a PayU leva de 1 a 3 dias para processar e aprovar ou rejeitar a solicitação. Você pode verificar o status de um reembolso usando um dos seguintes métodos:

Verificando o Status pelo Painel de Gestão da PayU

  1. Acesse sua conta no módulo da PayU. No painel esquerdo, expanda o menu Transações e selecione Relatório de Vendas.

    PrintScreen

  2. Utilize o campo Filtrar minhas vendas para buscar o pedido usando o ID do pedido ou o ID da transação.

    PrintScreen

  3. A coluna Status indica se o reembolso foi aprovado, rejeitado ou se está pendente.

    PrintScreen

Verificando o Status pela API de Consultas

Você também pode verificar o status do reembolso usando a API de Consultas. Para isso, envie uma requisição contendo o ID do pedido.

Ao consultar um pedido, o sistema retorna a última transação associada a ele.

A resposta pode indicar um dos três possíveis status:

  • Solicitação Pendente: Se o pedido de reembolso ainda estiver em análise, o pedido aparecerá com status CAPTURED (result.payload.status na resposta).

    • O primeiro tipo de transação será AUTHORIZATION_AND_CAPTURE (result.transactions.type na resposta).
    • O primeiro status da transação será APPROVED (result.transactions.transactionResponse.state na resposta).
  • Aprovado: Se o pedido de reembolso for aprovado por um agente de atendimento da PayU, o pedido aparecerá com status REFUNDED (result.payload.status na resposta).

    • O primeiro tipo de transação será REFUND (result.transactions.type na resposta).
    • O primeiro status da transação será APPROVED (result.transactions.transactionResponse.state na resposta).
  • Recusado: Se o pedido de reembolso for rejeitado por um agente de atendimento da PayU, o pedido aparecerá com status CAPTURED (result.payload.status na resposta).

    • O primeiro tipo de transação será REFUND (result.transactions.type na resposta).
    • O primeiro status da transação será DECLINED (result.transactions.transactionResponse.state na resposta).
Última modificação 1 de outubro de 2025: Documentation updates (3a7e506d9)