URL de Respuesta

La URL de Respuesta sirve como un puente para retornar al pagador a tu plataforma después de haber completado (o intentado) un pago. Aunque la integración redirige al cliente a través de una petición GET a nivel de navegador, los datos enviados te permiten mostrar resúmenes de transacción o estados personalizados, tales como Aprobado, Rechazado, En validación o Pago pendiente (para transacciones en efectivo). Ten en cuenta, sin embargo, que el pagador podría cerrar el checkout antes de llegar a la página de resultados.

Métodos de Integración

El nombre del parámetro y su ubicación para la URL de Respuesta varían según el tipo de integración que estés utilizando.

Consideraciones

• No apto para lógica de Backend: Evita depender de la URL de Respuesta para actualizar tu base de datos o procesar pedidos. Los usuarios pueden cerrar el navegador antes de que ocurra la redirección. Utiliza siempre la URL de Confirmación (Webhook) para los procesos de backend.

• Restricciones de Hosting: Asegúrate de que tu proveedor de hosting no bloquee URLs enviadas como valores de parámetros (ej. &merchant_url=...).

• Recomendaciones de Visualización: Recomendamos mostrar al cliente al menos: el estado, la referencia, el valor, la moneda y la fecha.

• Comportamiento por Defecto: Si no proporcionas una URL de Respuesta (ya sea en la petición o en el Panel de Gestión de PayU), el proceso finaliza en la página de checkout web de PayU.

Parámetros enviados a la URL de Respuesta

Independientemente del método de integración, PayU envía los siguientes parámetros a tu URL a través de una petición HTTP GET.

Ejemplo de Implementación (PHP)

La lógica es esencialmente la misma para ambas integraciones una vez que el sistema redirige al usuario a tu 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>";
}
?>

Ejemplo de Petición GET:

El siguiente es un ejemplo de la cadena de consulta (query string) que PayU añade a tu URL de Respuesta. Puedes usarlo para probar la capacidad de tu script para capturar variables y validar la firma.

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

Validación de la Firma

Para garantizar que los datos recibidos en la URL de Respuesta no hayan sido alterados, debes regenerar la firma y compararla con el parámetro signature.

Regla de Redondeo para la URL de Respuesta

• Para calcular el new_value de la firma, redondea el TX_VALUE a un decimal utilizando el método de redondeo al par más cercano (round half to even):
  • Si el primer decimal es par y el segundo es 5 → redondea hacia abajo (ej., 150.25 se convierte en 150.2).
  • Si el primer decimal es impar y el segundo es 5 → redondea hacia arriba (ej., 150.35 se convierte en 150.4).
  • De lo contrario, redondea normalmente al decimal más cercano.

Formato de la Firma

Utiliza siempre los valores provenientes de la URL de Respuesta (merchantId, referenceCode, TX_VALUE, currency y transactionState) para generar la firma. No utilices los valores de tu base de datos.

La cadena a cifrar es:

apiKey~merchantId~referenceCode~new_value~currency~transactionState

Ejemplos de Firma

Los siguientes ejemplos ilustran cómo generar una firma, en este caso, utilizando HMAC-SHA256.

El primer decimal es un número par y el segundo es 5

El primer decimal es un número impar y el segundo es 5

Otros casos

Valida tu Firma

Utiliza este generador para crear una firma con cualquiera de los métodos de cifrado disponibles. Esta funcionalidad te ayuda a verificar el valor de la signature que PayU envía a tu URL de Respuesta.