Medios de Pago (sigue)
Índice de contenidos
Adyen
La integración con Adyen está dividida en dos grandes bloques. Por un lado la integración de los terminales físicos y por otro la integración de pagos online (ecommerce, tokenización…)
TERMINALES FÍSICOS
En la aplicación de Hotel, la integración con Adyen nos permitirá enviar a los terminales la información de un cobro de manera automática, evitando que el operador tenga que introducir el importe manualmente. La configuración se muestra en la siguiente captura (B.8 -Setup – Formatos/Interfaces => Medios de pago => Adyen):
Describiremos ahora los parámetros de configuración:
- Merchant account: Parámetro obligatorio. Nombre del merchant account en Adyen, típicamente tendrá el formato <NOMBRE_EMPRESA>POS. Si queremos activar los Refund (explicados más adelante) y tenemos también POS recomendamos que los merchant account sean distintos.
- Path to certificate: Obligatorio. Ruta en el servidor al certificado de Adyen. https://docs.adyen.com/point-of-sale/choose-your-architecture/local#install-root-cert
- Test mode: Activo en modo pruebas, desactivarlo para el modo Live.
- Parámetros del Webhook: Obligatorio si queremos activar los Refunds. Se tienen que corresponder exactamente con la configuración del Webhook en Adyen, que explicaremos más adelante en detalle
- User name:
- Password
- HMAC Key
- Email notifications: dirección de email (o emails, separados por punto y coma ‘;’) a donde se enviarán unas notificaciones si hay algún problema con los refunds
- Parámetros de cada terminal:
- Serial Number: Obligatorio. Concatenación del device model y el serial number del terminal. Se puede localizar fácilmente en la plataforma de Adyen en Point of sale -> Terminals -> seleccionar terminal.
- Endpoint: Dirección IP del terminal, precedido por https://
- Forma de pago: Forma de pago de POS asociada. Esto nos servirá para identificar en qué momento enviar la orden de cobro al terminal. Lógicamente, las formas de pago no se deben repetir entre distintos terminales.
- Key identifier, Key passphrase y Key version: Se tienen que corresponder con los parámetros que hayamos definido en Adyen, en el menú del terminal -> Integrations -> Encryption Key
- Mostrar propinas: Si queremos que el terminal ofrezca la posibilidad de ofrecer propinas, según las hayamos configurado en Adyen (Menú del terminal -> Payment Features -> Tipping)
- Permitir negativos / Refunds: Si permitimos las devoluciones o los cargos por importe negativo.
- Por último, indicar que la moneda se tomará del parámetro de moneda de los pagos online de Adyen, en el panel de Adyen – Online. https://docs.adyen.com/development-resources/currency-codes
REFUNDS
Los Refunds, nos permitirán realizar una operación de devolución o de cobro por importe negativo en los terminales de Adyen. Existen dos tipos distintos de Refund
- Referenced Refunds: Cuando existe una operación previa que queremos cancelar. Se correspondería a la anulación de una factura previamente cobrada a través de Adyen o de la devolución de un anticipo/depósito previamente cobrado a través de Adyen. No se necesitará pasar la tarjeta del cliente por el terminal.
- Unreferenced Refunds: Cuando no existe una operación previa y simplemente queremos hacer un cobro de un importe negativo. Se necesitará pasar la tarjeta del cliente por el terminal.
Los refunds en Adyen funcionan de manera asíncrona. Aunque el terminal nos devuelva una respuesta en el momento de manera síncrona, esta no es definitiva y será una notificación o Webhook la que nos informe posteriormente de si la operación ha sido realmente exitosa o no. Según Adyen, la inmensa mayoría de los Refunds van a ser exitosos, y el caso más típico de error será el que el propio comercio/hotel no tenga fondos en su cuenta para hacer la devolución, caso que es fácilmente evitable.
Para adecuarnos a este comportamiento, hemos escogido una estrategia optimista, de tal manera que cuando el terminal nos responde que la operación ha sido exitosa, nosotros ya interpretamos por adelantado que todo ha ido OK. Solamente será en el caso de que el webhook nos informase de que la operación ha sido fallida cuando enviaríamos un correo al email de notificaciones y eliminaríamos el cobro del PMS. Así, en el caso de que el cobro fuese de una factura, ésta quedaría pendiente de pago y si fuese un anticipo se eliminaría la devolución del anticipo. Podría darse el (raro) caso de que el sistema no encontrase el pago al que hace referencia la operación de Refund. En este caso se informa de ello en el email para que el hotel tome las medidas pertinentes, ya que debido a la estrategia optimista, habrá una devolución recogida en el PMS pero que realmente no se ha podido completar.
Para configurar el webhook, es necesario hacerlo desde Adyen -> Developers -> Webhooks. Se recomienda dar de alta el webhook a nivel de merchant account y no a nivel de empresa. En nuestro caso, además, el webhook debería ser independiente del webhook de POS. En el webhook, deberemos indicar los siguientes parámetros:
- URL: https://<URL_APP_HOTEL>/rest/adyen/terminal. Es obligatorio que sea HTTPS (puertos 443, 8443, or 8843) bajo TLS v1.2. https://docs.adyen.com/development-resources/webhooks
- Method: JSON
- Authentication: Usuario y contraseña que deben coincidir con los de nuestra configuración (B.8 – Medios de pago – Adyen)
- Additional settings – HMAC Key: Debemos generar una clave y copiarla en nuestra configuración de Adyen (B.8 – Medios de pago – Adyen)
- Además, se le puede pedir a Adyen que este webhook sólo envíe los eventos de “CANCEL_OR_REFUND” y “REFUND_WITH_DATA”. Así, no enviará ningún otro webhook y ahorraremos en capacidad de procesamiento y logs.
En caso de no tener activados los refund, el sistema no se conectará contra el terminal de Adyen y dará la operación como realizada, por lo que para cuadrar las cuentas sería necesario hacer la devolución de manera manual desde el terminal. Para ello es necesario que se habilite desde Adyen esta funcionalidad.
PROPINAS – TIPS
Para las propinas, tenemos dos opciones que además son complementarias:
- Configurar los terminales con el check de “tips” activado. De esta manera, en cada pago se le mostrará al cliente en el terminal una pantalla para que indique si desea dar propina.
- Aplicar la propina en el sistema, indicando en el importe del cobro una cantidad mayor de la que queda pendiente de cobro, previamente a la orden de cobro al terminal.
Independientemente del caso usado, el sistema recogerá el cobro final, dejándolo como importe de propinas en la factura. Para el caso de anticipos, el importe final del anticipo será el importe original más el importe de la propina.
DCC – PAGO EN OTRAS MONEDAS
El DCC consiste en que, si un cliente paga con una tarjeta cuya cuenta no está en la moneda local, Adyeyn detecta que es una moneda extranjera y le permite al cliente escoger entre usar su propia moneda o la moneda local.
Para activar esta funcionalidad lo deben hacer desde Adyen y es totalmente transparente a nuestra integración.
PAGOS ONLINE
A través de esta integración podremos realizar 3 casos de uso principales:
- Enviar links de pago de una factura. Recepción a través de un Webhook del resultado de la operación de pago y dar de alta el cobro correspondiente en el PMS.
- Enviar email con link de pago a 0€ para tokenizar la tarjeta del cliente. Recepción a través del Webhook del token de la tarjeta.
- Hacer pagos contra un token previamente guardado. http://manuales.shms.es/sspsd2/
- Eliminar un token previamente guardado.
La configuración de Adyen para estos casos de uso es:
- Merchant account. Nombre del merchant account en Adyen, típicamente tendrá el formato <NOMBRE_EMPRESA>ECOM. Si tenemos integración del CWM con Adyen recomendamos que tengan distintos merchant accounts
- Test mode. Activo en modo pruebas, desactivarlo para el modo Live.
- API Key: Se obtiene de Adyen -> Developers -> API credentials -> Authentication -> Api Key
- Forma de pago: la forma de pago con la que se van a registrar los pagos del pay by link.
- Live URL Prefix: Lo podremos obtener desde Adyen -> Developers -> API URLs https://docs.adyen.com/development-resources/live-endpoints#live-url-prefix
- Activo: check para habilitar o desactivar Adyen – Online
- Moneda: código de moneda https://docs.adyen.com/development-resources/currency-codes
- Parámetros del webhook (user name, password, HMAC Key). Deben coincidir con los del webhhook que creemos en Adyen -> Developers -> Webhook. Es importante que este webhook se cree a nivel de merchant account y no a nivel de empresa en Adyen.
Para configurar el webhook, es necesario hacerlo desde Adyen -> Developers -> Webhooks. Se recomienda dar de alta el webhook a nivel de merchant account y no a nivel de empresa. En nuestro caso, además, el webhook debería ser independiente del webhook de los datáfonos físicos, del webhook de POS y del webhook para el CWM. En el webhook, deberemos indicar los siguientes parámetros:
- URL: https://<URL_APP_HOTEL>/rest/adyen. Es obligatorio que sea HTTPS (puertos 443, 8443, or 8843) bajo TLS v1.2. https://docs.adyen.com/development-resources/webhooks
- Method: JSON
- Authentication: Usuario y contraseña que deben coincidir con los de nuestra configuración (B.8 – Medios de pago- Adyen)
- Additional settings – HMAC Key: Debemos generar una clave y copiarla en nuestra configuración de Adyen (B.8 – Medios de pago – Adyen)
Además, es muy importante activar el parámetro “Recurring details” en la parte de Developers -> Additional Data para poder funcionar correctamente con la tokenización de tarjetas.
Tanto los pay by link como los enlaces para tokenizar pueden ser customizados desde la plataforma de Adyen.
Pagos Online en CWM
Si queremos aceptar pagos a través de Adyen en el CWM tenemos que habilitar el check en la propia configuración del CWM en Configuración->Conectividad y además tendremos que completar la configuración en el apartado B.9 de cada PMS, de un modo parecido al recogido en la siguiente captura:
La explicación de los parámetros es la misma que para el caso de la configuración en el apartado B.8. Hay un parámetro nuevo, “Client Key” que se obtiene del mismo sitio donde está el API Key. En Adyen debería estar justo debajo de la API Key. Es importante que todos los parámetros estén cubiertos con valor, incluido el de Live URL prefix, aunque estemos en modo pruebas.
Además, aunque los parámetros sean similares, se recomienda que el merchant account sea distinto y que además el webhook configurado sea distinto al usado en la configuración del B.8. Además, el webhook en este caso tendrá un URL que apunta a la aplicación del CWM: https://<URL_APP_CWM>/rest/adyen. El resto de parámetros de configuración del webhook son los mismos que en el caso anterior.
¿Por qué necesitamos un webhook para recibir los pagos que se hacen en la pasarela de pago? Es debido a ciertos métodos de pago que se procesan en Adyen y cuyo procesamiento se hace asíncronamente. Es el caso de iDeal en Países Bajos. De esta manera, aunque el flujo de la pasarela de pago termine correctamente, la operación no se realizará hasta que nos llegue la notificación al webhook. Para el caso de tarjetas “normales” la notificación llega casi instantáneamente, para otros métodos de pago como el mencionado iDeal podría tardar varios segundos o minutos.
Por último, en la parte de Adyen, deberemos incluir el dominio del CWM en la whitelist del servicio web. https://docs.adyen.com/development-resources/client-side-authentication#manage-allowed-origins
Redsys
Para activar la plataforma de pago Redsys mediante el PMS será necesario disponer de los siguientes campos facilitados por su entidad bancaria:
- Merchant Code: Es el número de comercio único.
- Terminal ID: El número de terminal es el número asignado al terminal facilitado por la entidad bancaria.
- Merchant Key: Es una clave firma única.
Una vez dispongamos de estos datos, deberemos rellenar la configuración del medio de pago que se encuentra en B.8. Setup – Formatos/Interfaces -> Medios de pago para Hotel, y en B.9. Setup – CWM -> Formas de pago CWM para CWM.
Estos son el resto de campos a rellenar:
- Endpoint: La dirección a la que se envían las peticiones de pagos, siendo distinta para pruebas y para transacciones reales. Disponible en la documentación de Redsys.
- Email avisos: Como su propio nombre indica será el email al que lleguen los avisos de los fallos relacionados con esta implementación.
- Forma de pago: Tendrá que ser creada previamente una forma de pago para el TPV virtual de Redsys.
