Uso de la IPN (URL de notificación)

IPN son las siglas de Instant Payment Notification (URL de notificación instantánea, en inglés). Al crear una transacción o cambiar su estado, nuestros servidores emitirán una IPN que llamará a una URL de notificación en sus servidores. Esto le permitirá estar informado en tiempo real de los cambios realizados en una transacción.

Para más información general sobre las IPN, consulte el siguiente artículo: IPN: generalidades

Las IPN son la única manera de recibir notificaciones en los casos siguientes:

  • La conexión a Internet del comprador se ha cortado
  • El comprador cierra su navegador durante el pago
  • Se ha rechazado una transacción
  • El comprador no ha terminado su pago antes de la expiración de su sesión de pago

Por lo tanto, es obligatorio integrar las IPN.

Funcionamiento

Cuando el comprador valida el pago, se genera una transacción. Nuestros servidores intentarán contactar con los suyos para transmitir toda la información relativa a la transacción.

Etapa Descripción
1 El comprador ha hehco clic en el boton de pago: el formulario se envía desde el navegador del comprador a nuestros servidores. Nuestro cliente JavaScript realiza esta llamada de manera automática.
2 Una vez que la transacción se haya procesado, realizamos una llamada desde nuestros servidores a la URL que haya indicado. Se enviará el objeto completo de la transacción completo para permitirle actualizar su sistema de información antes del retorno del navegador. Se trata de la IPN (Instant Payment Notification).
3 Nuestros servidores reenvían el resultado del pago al cliente JavaScript.
4 El cliente JavaScript publica el formulario de pago en sus servidores.

La etapa 3 solo se produce una vez que los servidores hayan respondido (el tiempo máximo de espera es de 30 segundos). Así podrá actualizar su sistema de información antes de que el comprador sea redirigido a su página de confirmación de compra.

Définir l’URL dans le Back Office Expert

Notificación de fin de pago

La notificación de fin de pago se utiliza para notificar al sitio del vendedor en los siguientes casos:

  • Pago aceptado
  • Pago rechazado
  • Creación o actualización de un token
  • Creación de una recurrencia

Para configurar la notificación:

  1. Connectez vous sur le Back Office Lyra Collect
  2. Vaya al menú: Configuración > Reglas de notificación.
  3. Haga clic derecho en URL de notificación al final del pago.
  4. Seleccione Gestionar la regla.
  5. En la sección Configuración general, llene el campo Dirección(es) de e-mail a notificar en caso de fallo.
  6. Marque la casilla Reenvío automático en caso de fallo si desea autorizar a la plataforma a reenviar automáticamente la notificación hasta 4 veces en caso de fallo.
  7. En la sección URL de notificación de la API REST, indique la URL de su página en los campos URL de destino de la IPN a la que se llamará en modo TEST y URL de destino de la IPN a la que se llamará en modo PRODUCTION.
  8. Guarde los cambios.

Si el servidor de destino de la IPN está sin conexión, recibirá un correo electrónico a la dirección definida en la configuración de la regla.

Este correo electrónico contendrá:

  • El código de error HTTP que ha devuelto su servidor
  • Elementos de análisis
  • La explicación sobre las consecuencias del error
  • Les instructions pour relancer l’IPN (à travers le Back Office Expert)

Notificación en caso de abandono

La notificación en caso de abandono se utiliza para notificar al sitio del vendedor cuando el comprador no ha completado su pago antes de la expiración de su sesión de pago.

En este caso, la notificación no contiene un objeto Transaction, sino simplemente la información de Order.

Caso particular de la autenticación del portador

En caso de abandono durante el proceso de autenticación, el sitio del vendedor recibe:

  • una notificación de fin de pago para notificar el rechazo del pago, y que contiene un objeto Transaction con los detalles del pago rechazado,
  • una notificación de abandono que contiene la información de Order.

De forma predeterminada, el sitio del vendedor no recibe una notificación en caso de abandono. vous devez activer la règle de notification correspondante dans votre Back Office Lyra Collect.

Para configurar la notificación:

  1. Connectez vous sur le Back Office Lyra Collect
  2. Vaya al menú: Configuración > Reglas de notificación.
  3. Haga clic derecho en URL de notificación de cancelación.
  4. Seleccione Gestionar la regla.
  5. En la sección Configuración general, llene el campo Dirección(es) de e-mail a notificar en caso de fallo.
  6. Marque la casilla Reenvío automático en caso de fallo si desea autorizar a la plataforma a reenviar automáticamente la notificación hasta 4 veces en caso de fallo.
  7. En la sección URL de notificación de la API REST, indique la URL de su página en los campos URL de destino de la IPN a la que se llamará en modo TEST y URL de destino de la IPN a la que se llamará en modo PRODUCTION.
  8. Guarde los cambios.
  9. Active la regla haciendo clic derecho en URL de notificación de cancelación y seleccionando Activar la regla.

Definir la URL de manera dinámica

Al momento de generarse el formToken, podrá definir la URL de destino de la IPN de manera dinámica con el parámetro ipnTargetUrl:

{
    "amount": 990,
    "currency": "EUR",
    "ipnTargetUrl": "https://my.super.site/ipn"
}

Uso de la IPN

La IPN se envía a sus servidores utilizando el mismo procedimiento que el cliente JavaScript. Esto le permite usar un código similar para procesar la respuesta:

  • Los datos se envían en un formulario (content-type: x-www-form-urlencoded),
  • Los parámetros que contienen los datos son los mismos.

Las diferencias son:

  • kr-answer contiene los objetos Transacciones completos,
  • la firma contenida en kr-hash se calcula de manera diferente.

La IPN se enviará en POST a sus servidores de la siguiente manera:

kr-hash=c3c0323c748fdb7c2d24bd39ada99663526236828efa795193bebfdea022fe58
kr-hash-algorithm=sha256_hmac
kr-hash-key=password
kr-answer-type=V4/Payment
kr-answer={"shopId":"33148340","orderCycle":"CLOSED",(...)}

Los parámetros POST corresponden a:

Parámetro Descripción
kr-hash Hash del objeto JSON almacenado en kr-answer. Así podrá confirmar la autenticidad de la respuesta
kr-hash-algorithm Algoritmo utilizado para calcular el hash
kr-hash-key Clave utilizada para firmar kr-answer. Puede establecerse en hmac_sha256 (retorno del navegador) o password (caso IPN).
kr-answer-type Tipo del objeto JSON almacenado en kr-answer
kr-answer Objeto que contiene los objetos transacciones completos codificados en formato JSON

Antes de entrar en el detalle del contenido de kr-answer, es necesario comprobar si es este es válido.

Comprobar la firma IPN (hash)

Para detectar posibles fraudes, es necesario comprobar la autenticidad del campo kr-answer.

El campo kr-hash contiene el hash de kr-answer generado con la contraseña (que comienza con testpassword* o prodpassword*).

La contraseña está disponible en su Back Office (menú Configuración > Tienda, pestaña Claves de API REST, sección Claves de API REST).

Para comprobar la validez de la firma con nuestros SDK:

/* Check the signature using password */

if (!$client->checkHash()) {
    //something wrong, probably a fraud ....
    signature_error($formAnswer['kr-answer']['transactions'][0]['uuid'], $hashKey, 
                    $client->getLastCalculatedHash(), $_POST['kr-hash']);
    throw new Exception('invalid signature');
}

Una vez que haya comprobado la firma, podrá acceder a la información vinculada a la transacción:

/* Retrieve the IPN content */
$rawAnswer = $client->getParsedFormAnswer();
$formAnswer = $rawAnswer['kr-answer'];

/* Retrieve the transaction id from the IPN data */
$transaction = $formAnswer['transactions'][0];

/* get some parameters from the answer */
$orderStatus = $formAnswer['orderStatus'];
$orderId = $formAnswer['orderDetails']['orderId'];
$transactionUuid = $transaction['uuid'];

Consulte la sección siguiente para más detalles.

Ejemplo de implementación de la verificación del hash en PHP:

    /**
     * check kr-answer object signature
     */
    public function checkHash($key=NULL)
    {
        $supportedHashAlgorithm = array('sha256_hmac');

        /* check if the hash algorithm is supported */
        if (!in_array($_POST['kr-hash-algorithm'],  $supportedHashAlgorithm)) {
            throw new LyraException("hash algorithm not supported:" . $_POST['kr-hash-algorithm'] .". Update your SDK");
        }

        /* on some servers, / can be escaped */
        $krAnswer = str_replace('\/', '/', $_POST['kr-answer']);

        /* if key is not defined, we use kr-hash-key POST parameter to choose it */
        if (is_null($key)) {
            if ($_POST['kr-hash-key'] == "sha256_hmac") {
                $key = $this->_hashKey;
            } elseif ($_POST['kr-hash-key'] == "password") {
                $key = $this->_password;
            } else {
                throw new LyraException("invalid kr-hash-key POST parameter");
            }
        }
    
        $calculatedHash = hash_hmac('sha256', $krAnswer, $key);
        $this->_lastCalculatedHash = $calculatedHash;

        /* return true if calculated hash and sent hash are the same */
        return ($calculatedHash == $_POST['kr-hash']);
    }
}

La elección de la contraseña dependerá del valor de kr-hash-key:

kr-hash-key Clave utilizada Descripción
hmac_sha256 hmac_sha256 clave HMAC SHA256 Datos recibidos durante el retorno del navegador. Se utiliza la clave SHA256 para comprobar el valor de kr-hash
password Contraseña Datos recibidos a través de la IPN (llamada de servidor a servidor). Se utiliza la contraseña para comprobar el valor de kr-hash

El objeto Transaction

El objeto Transaction está contenido en el parámetro POST kr-answer en formato JSON:

El parámetro kr-answer contiene la información sobre el estado de la sesión de pago:

{
    "shopId": "69876357",
    "orderCycle": "CLOSED",
    "orderStatus": "PAID",
    "serverDate": "2018-09-27T14:02:17+00:00",
    "orderDetails": (...)
    "customer": (...)
    },
    "transactions": [{
        "shopId": "69876357",
        "uuid": "5b158f084502428499b2d34ad074df05",
        "amount": 990,
        (...)
        "_type": "V4/PaymentTransaction"
    }],
    "_type": "V4/Payment"
}

Para acceder a él, puede utilizar cualquier función estándar o nuestro SDK:

/* Retrieve the IPN content */
$rawAnswer = $client->getParsedFormAnswer();
$formAnswer = $rawAnswer['kr-answer'];

/* Retrieve the transaction id from the IPN data */
$transaction = $formAnswer['transactions'][0];

/* get some parameters from the answer */
$orderStatus = $formAnswer['orderStatus'];
$orderId = $formAnswer['orderDetails']['orderId'];
$transactionUuid = $transaction['uuid'];

Ciclo de vida de una transacción

Para comprender el significado de los campos status y detailedStatus, consulte: Referencia de los estados

Restricciones del servidor del vendedor

En caso de que se establezca una restricción del lado del sitio web del vendedor, será necesario autorizar el rango de direcciones IP 194.50.38.0/24.

Las notificaciones se enviarán desde una dirección IP dentro del rango 194.50.38.0/24 en modo de prueba y en modo de producción.