Publicado el

Para integrar los pagos recibidos en Codeeta con el back-end de una aplicación web lo más sencillo es hacer uso de la funcionalidad de notificaciones a mi servidor web.

¿Qué son las notificaciones a mi servidor web? ¿Para qué sirven?

Se trata de posts HTTP que Codeeta enviará a una URL de tu elección cada vez que tu widget de comercio electrónico genere algún tipo de actividad. En la mayoría de los casos esta URL será la del servidor de tu aplicación web, esto permite la actualización automática y en tiempo real de tus distintos procesos de negocio y tus bases de datos con el resultado de cada nueva venta o pago realizado. Es tu responsabilidad gestionar correctamente la información que recibas de Codeeta en tu servidor para actualizar todos tus procesos de negocio.

¿Cómo integro notificaciones a mi servidor web?

Accede a la sección Notificaciones de tu widget y selecciona Servidor web. Desde ahí, Codeeta permite configurar distintas notificaciones a tu servidor web en función del resultado de las transacciones de tu widget de comercio electrónico. Puedes seleccionar una URL donde recibir las notificaciones cuando tu widget realice una venta de forma satisfactoria y otra URL donde recibirlas en los casos en los que la transacción no se llegue a completar. También puedes configurar las notificaciones para recibir en la misma URL tanto los mensajes de ventas realizadas como los de ventas fallidas.

Para configurar las notificaciones a tu servidor web en caso de ventas realizadas o pagos recibidos con éxito selecciona la pestaña Venta realizada. Para configurar las notificaciones en caso de que no se complete una transacción selecciona Venta fallida.

Callbacks para servidor web

El único requisito imprescindible para configurar notificaciones a tu servidor web es proporcionar la URL donde quieres recibirlas. Para ello, simplemente aporta dicha URL en el campo de texto destinado a tal fin. Por cada transacción de tu widget de comercio electrónico y según tu configuración, Codeeta enviará una notificación que incluirá una serie de parámetros generales de identificación de la transacción y resultado de la misma. Opcionalmente, Codeeta puede incluir también el valor que tus clientes hayan destinado a los elementos de tu widget tras interactuar con él. Si quieres que Codeeta incluya en la notificación el valor de elementos de tu widget, simplemente selecciónalos a través del desplegable.

Configuración de campos del callback

Un ejemplo

Imaginemos que queremos configurar notificaciones a tu servidor web para el siguiente widget de tienda virtual de venta de camisetas.
Widget de promociones con callbacks

Para recibir notificaciones en tu servidor cada vez que alguien interactúe con tu widget deberás realizar los siguientes pasos.

    1. En la pestaña Venta realizada introduce la URL de tu servidor web donde quieres recibir la notificación cada vez que realices una nueva venta. Si quieres recibir notificaciones cada vez que una venta no se completa, configura la URL donde recibir dicha notificación en la pestaña Venta fallida. Recuerda que puedes configurar ambas URLs de manera independiente y que si lo deseas puedes recibir ambos tipos de notificaciones en la misma URL.
Configuración URL para callback

Dada la configuración mostrada en el ejemplo, cada vez que se realice una nueva venta a través del widget, Codeeta enviará un post HTTP de notificación a https://www.mangacorta.cl/ventas/exito.

  • Opcionalmente, selecciona aquellos elementos del widget que, junto con el resto de parámetros generales, quieras recibir en la notificación. En el widget de ejemplo, tras seleccionar la talla de la camiseta y el tipo de envío, el widget solicita una serie de datos al comprador, como son su nombre y apellidos, dirección, correo electrónico, etc.

 

Si, por ejemplo, queremos recibir en la notificación, además de la información básica de la transacción, la talla de la camiseta comprada, el tipo de envío seleccionado, el nombre y apellidos del comprador, su dirección y su correo electrónico, simplemente selecciona estos elementos en el desplegable.

Configuración de elementos del callback

Con esta configuración, una posible notificación que se recibiría en https://www.mangacorta.cl/ventas/exito cuando se realice una venta sería la siguiente:

Notificacion de callback

Esta notificación indica que se realizó una venta satisfactoria, por un total de 5750 CL$ a través de la pasarela de pago de DineroMail. La talla seleccionada para la camiseta es M, el envío seleccionado es Envío a Santiago +1500CL$, el comprador se llama Juan y sus apellidos son García Pérez, su dirección es Avda. de Filipinas 50, Escalera 2, 1ºA, 28003 Madrid y su correo electrónico es juangarcia@correo.com.

El parámetro customer_id sólo será incluido en mensajes que notifiquen preautorizaciones, pagos one-click o pagos one-click con CVC que se realicen a través de pasarelas de pago de Adyen. Su significado es el identificador de tu cliente dentro de tu propia aplicación o plataforma de negocio y sirve para que, posteriormente utilizando la API de Codeeta, puedas conocer si tu cliente ya tiene asociada una forma de pago dentro de tu aplicación. Esto te permitirá mostrar en tu aplicación la forma de pago ya utilizada por tu cliente y evitar tener que solicitar dichos datos de nuevo, favoreciendo de esta manera el proceso de compra en tu sitio web.

Para recibir correctamente el parámetro customer_id con el identificador de tu cliente en tu plataforma deberás utilizar la meta etiqueta customerid en la URL de tu widget, por ejemplo:

https://services.codeeta.com/c/mangacorta/ExportWidgetAction/35357?meta_customerid=123456

Si no utilizas esta meta etiqueta, Codeeta generará aleatoriamente un identificador para tu cliente. Si el pago no se realiza mediante una pasarela de Adyen o si no es una preautorización, un pago one-click o one-click con CVC, el parámetro customer_id no es enviado.

En tu servidor, bajo la URL que hayas configurado para escuchar las notificaciones recibidas de Codeeta, tu código debe acceder a los parámetros de la notificación de la misma manera que, en el lenguaje de programación de tu servidor, accedas a las variables de un formulario web normal. Por ejemplo, en PHP se accedería a los parámetros de la notificación de la siguiente manera:

$codeeta_notification_params = $_POST();

Independientemente de que el mensaje que recibas sea para notificar una nueva venta o una venta fallida, Codeeta siempre te enviará los siguientes parámetros generales:

Parámetros del callback

Además de estos parámetros, si has configurado tus notificaciones para recibir el valor que tome alguno de los elementos del widget cuando tus clientes interactúen con él recibirás en el mensaje el parámetro element_responses.

El parámetro element_responses es un array que contiene pares clave-valor donde la clave es el identificador unívoco del elemento seleccionado y el valor es el que haya dado tu cliente a dicho elemento en su compra.

En el ejemplo anterior, dado que hemos configurado las notificaciones para recibir el valor de los elementos Talla (cuyo identificador es 327340), Envío (identificador 329139), Nombre (identificador 327349), Apellidos (identificador 327351), Dirección (identificador 327350) y Correo electrónico (identificador 327348) la notificación tras la realización de una venta podría incluir los siguientes datos en el campo element_responses:

Elementos de respuesta

Recuerda que si no has configurado tus notificaciones para incluir el valor de algún elemento la notificación no incluirá el parámetro element_responses.

¿Cómo verifico que la notificación proviene realmente de Codeeta?

Tanto si configuras notificaciones a tu servidor en caso de ventas o pagos realizados con éxito como para ventas o pagos fallidos, Codeeta siempre enviará el parámetro hash como último parámetro de la notificación. Puedes utilizar el valor de este parámetro para verificar que las notificaciones que recibas realmente provienen de Codeeta y no de un tercero malintencionado.

El parámetro hash se calcula realizando una encriptación sha1 de la cadena generada al concatenar todos los valores incluidos en la notificación (a excepción del valor de hash) más tu clave privada que puedes encontrar en la sección Servidor web de la pantalla Notificaciones de tu widget.

Hash del callback

En el ejemplo anterior, el parámetro hash se calcularía creando la siguiente cadena, formada por todos los elementos de la notificación exceptuando el propio valor del parámetro hash.

TY035357-000000345750CLPCOMPLETEDDINEROMAIL851350893539759235357123456MEnvío a Santiago +1500CL$JuanGarcía PérezAvda. de Filipinas 50, Escalera 2, 1ºA, 28003 Madridjuangarcia@correo.com 

Para verificar que sólo tú y Codeeta pueden generar esta cadena, concatena tu clave privada de manera que la cadena a la cual aplicar la encriptación sha1 sea:

TY035357-000000345750CLPCOMPLETEDDINEROMAIL851350893539759235357123456MEnvío a Santiago +1500CL$JuanGarcía PérezAvda. de Filipinas 50, Escalera 2, 1ºA, 28003 Madridjuangarcia@correo.comebb26c50d29dcd3a5d018a24e58d983aa51ff65f

Tras aplicar la encriptación sha1 sobre esta cadena, el valor del parámetro hash sería cf122b2dd68cf2b5aa52ff07fb086f7d613d7efb.

Cuando recibas una notificación, simplemente tienes que repetir este proceso y calcular en tu servidor el valor del parámetro hash, si el resultado de tu cálculo coincide con el valor recibido puedes estar seguro de que la notificación proviene de Codeeta y no es ningún tipo de suplantación.