URL de Resposta

A URL de Resposta serve como uma ponte para retornar o pagador à sua plataforma após ele ter concluído (ou tentado) um pagamento. Embora a integração redirecione o cliente por meio de uma requisição GET a nível de navegador, os dados enviados permitem que você exiba resumos de transações ou status personalizados, como Aprovado, Rejeitado, Em validação ou Pagamento pendente (para transações em dinheiro). Lembre-se, porém, que o pagador pode fechar o checkout antes de chegar à página de resultado.

Métodos de Integração

O nome do parâmetro e a localização da URL de Resposta variam dependendo do tipo de integração que você está usando.

Considerações

• Não utilize para Lógica de Backend: Evite depender da URL de Resposta para atualizar seu banco de dados ou liberar pedidos. Os usuários podem fechar o navegador antes que o redirecionamento ocorra. Sempre use a URL de Confirmação (Webhook) para processos de backend.

• Restrições de Hospedagem: Certifique-se de que seu provedor de hospedagem não bloqueie URLs enviadas como valores de parâmetros (ex: &merchant_url=...).

• Recomendações de Exibição: Recomendamos mostrar ao cliente, no mínimo: status, referência, valor, moeda e data.

• Comportamento Padrão: Se você não fornecer uma URL de Resposta (seja na requisição ou no Painel de Gestão PayU), o processo termina na página de checkout web da PayU.

Parâmetros Enviados para a URL de Resposta

Independentemente do método de integração, a PayU envia os seguintes parâmetros para sua URL via uma requisição HTTP GET.

Exemplo de Implementação (PHP)

A lógica é essencialmente a mesma para ambas as integrações assim que o sistema redireciona o usuário para o seu script:

<?php
$apiKey = "4Vj8eK4rloUd272L48hsrarnUA";
$merchant_id = $_GET['merchantId'];
$referenceCode = $_GET['referenceCode'];
$TX_VALUE = (float) $_GET['TX_VALUE'];
$currency = $_GET['currency'];
$transactionState = $_GET['transactionState'];

// Apply rounding for signature validation
$new_value = round($TX_VALUE, 1, PHP_ROUND_HALF_EVEN);

$signature_string = "$apiKey~$merchant_id~$referenceCode~$new_value~$currency~$transactionState";
$calculated_signature = md5($signature_string);
$received_signature = $_GET['signature'];

if (hash_equals(strtolower($received_signature), strtolower($calculated_signature))) {
    echo "<h2>Transaction Verified Successfully</h2>";
    // Display summary to user
} else {
    echo "<h2>Invalid Signature - Data Integrity Compromised</h2>";
}
?>

Exemplo de Requisição GET:

O exemplo a seguir mostra a query string que a PayU anexa à sua URL de Resposta. Você pode usar isso para testar a capacidade do seu script de capturar variáveis e validar a assinatura.

http://mytestsite.com/response.php?merchantId=508029&transactionState=6&referenceCode=2015-05-27+13%3A04%3A37&reference_pol=7069375&transactionId=f5e668f1-7ecc-4b83-a4d1-0aaa68260862&signature=e1b0939bbdc99ea84387bee9b90e4f5c&TX_VALUE=100.00&currency=USD&buyerEmail=test%40payulatam.com&lapPaymentMethod=VISA&lapTransactionState=DECLINED&message=Declined

Validação de Assinatura

Para garantir que os dados recebidos na URL de Resposta não tenham sido alterados, você deve regenerar a assinatura e compará-la com o parâmetro signature.

Regra de Arredondamento para URL de Resposta

• Para calcular o new_value da assinatura, arredonde o TX_VALUE para uma casa decimal usando o método round half to even (arredondamento ao par mais próximo):
  • Se a primeira casa decimal for par e a segunda for 5 → arredonde para baixo (ex: 150.25 torna-se 150.2).
  • Se a primeira casa decimal for ímpar e a segunda for 5 → arredonde para cima (ex: 150.35 torna-se 150.4).
  • Caso contrário, arredonde normalmente para o decimal mais próximo.

Formato da Assinatura

Sempre use os valores vindos da URL de Resposta (merchantId, referenceCode, TX_VALUE, currency e transactionState) para gerar a assinatura. Não utilize os valores do seu banco de dados.

A string para o hash é:

apiKey~merchantId~referenceCode~new_value~currency~transactionState

Exemplos de Assinatura

Os exemplos a seguir ilustram como gerar uma assinatura, neste caso, usando HMAC-SHA256.

Primeira casa decimal é um número par e a segunda é 5

Primeira casa decimal é um número ímpar e a segunda é 5

Outros Casos

Valide sua Assinatura

Use este gerador para criar uma assinatura com qualquer um dos métodos de criptografia disponíveis. Esta funcionalidade auxilia você na verificação do valor da signature que a PayU envia para sua URL de Resposta.