En esta guía

Cómo integrar tu TPV con Talonarium?

¿Necesitas integrar tu sistema de cobro en línea con nosotros? Con esta guía te ayudaremos a integrarlo paso a paso.

Antes de comenzar, ten en cuenta que esta guía está enfocada para usuarios con conocimientos técnicos avanzados. Si no dispones de estos conocimientos, puedes ponerte en contacto con un técnico de confianza para que pueda hacer la implementación.

También es importante tener en cuenta que esta integración solo es posible realizarla si dispones de un servidor que pueda aceptar llamadas y respuestas HTTP.

1 - Visión general

Talonarium ofrece el servicio de integración de un TPV de forma genérica. Con esto queremos recalcar que no podemos garantizar la compatibilidad con todos los TPV del mercado.

Antes de todo, RECOMENDAMOS que primero eches un vistazo a esta guía para analizar si la integración es posible.

En el siguiente diagrama podemos ver los diferentes componentes necesarios y cómo interactúan entre ellos:

  • Talonarium
  • Tu servidor
  • El TPV elegido
tpv-diagram

Inicio del proceso

Una vez que el comprador ha añadido todas las entradas al carrito de compra, se habilita el botón "Ir al pago". Al hacer clic en el botón, automáticamente Talonarium se comunica con tu servidor enviando todos los datos del pedido y esperando un enlace web que redirigirá al comprador a la página de pago del TPV.

Realización del pago

Cuando el comprador es dirigido a la página de pago propia del TPV, puede efectuar el pago con los diferentes métodos configurados. Es importante tener en cuenta que Talonarium no aplica ningún cargo. Si hay cargos, dependen del TPV elegido.

Si el pago se ha validado correctamente por parte del TPV, se debe comunicar a Talonarium para que el pedido pase a ser válido.

Confirmación del pago

Una vez completado el pago y enviada la notificación a Talonarium de que todo ha ido bien, el TPV puede redirigir al comprador a una página de confirmación propia, donde se muestran todos los detalles del pedido.

2 - Enlace de pago

Como hemos comentado previamente, cuando el comprador hace clic en el botón "Ir al pago", Talonarium automáticamente se comunica con tu servidor para que este proporcione el enlace web.

Esta comunicación se hace mediante una petición HTTP de tipo POST hacia tu servidor. Es necesario configurar la URL de este endpoint entrando en la aplicación de Talonarium, dentro de la configuración del TPV de un grupo organizador.

POST: https://your-server.com/payment-link

Talonarium envía la siguiente información en el JSON body:

{
    "paymentIntentId": "63ac23b439eaa500258b84fc",
    "price": 15,
    "currency": "EUR",
    "customerName": "Jean Warner",
    "customerEmail": "[email protected]",
    "customerLocale": "EN",
    "eventTitle": "Music festival in the beach",
    "organizerName": "BCN events",
    "tickets": [
        {
            "customerName": "Katerina Dean",
            "priceCategory": "vip",
            "price": 10
        },
        {
            "customerName": "Rachel Macias",
            "priceCategory": "default",
            "price": 5
        }
    ]
}

En este momento, tu servidor debe pedir al TPV que genere un enlace de pago con los datos obtenidos y a continuación, retornarlo como respuesta a la petición de Talonarium con la siguiente estructura JSON:

{
    "paymentLink": "https://your-tpv-payment-link"
}

El enlace de pago debe ser en formato HTTPS. Una vez Talonarium recibe el enlace de pago, automáticamente redirige al comprador a esta página para poder efectuar el pago.

3 - Validación del pago

Cuando el comprador efectúa el pago, Talonarium necesita saber que se ha efectuado correctamente. Por lo tanto, tu servidor nos debe notificar de que todo ha ido bien. En general los TPV permiten la configuración de un webhook cuando se ha realizado un pago.

*IMPORTANTE: es necesario notificar a Talonarium la validez del pago. Si no se notifica, el pedido es considerado inválido.

Para realizar esta notificación, debemos hacer la siguiente petición HTTP de tipo POST y estos datos en el JSON body:

POST: https://api.talonarium.com/v1/tpv-wh/payment-validate
{
    "paymentIntentId": "63ac23b439eaa500258b84fc",
    "secretKey": "xxx"
}

La secretKey es una clave privada de seguridad que se puede generar desde la configuración del TPV del grupo organizador. Tu servidor debe retornarla junto con el paymentIntentId.

4 - Página de confirmación

Según el TPV utilizado, podemos redirigir al comprador a la página de confirmación del pedido.

bgwbgwbgw