Integración BankStore XML

Introducción

La finalidad del presente documento es servir de referencia durante el proceso de integración de un comercio con la pasarela de pagos PAYCOMET, utilizando el sistema BankStore que almacena los datos bancarios de los clientes del comercio.

Se incluye también un apéndice de referencia y se puede conseguir en la web de PAYCOMET un documento con los códigos de error devueltos por el sistema para simplificar el proceso de depuración.

Las integraciones XML y REST permiten el acceso a las operaciones de pago sin intervención directa del usuario, ampliando la operativa de cobro individual a una gestión de los datos bancarios del cliente del comercio. Las peticiones parten del servidor del comercio y son procesadas por la pasarela de pago.

Ambas tecnologías escogida para la realización de las operaciones permiten el paso seguro por firewalls y a través de la red. Si necesita la captación de los datos de tarjeta, revise las integraciones Full screen, Iframe y JET-IFRAME.

El servicio BankStore se diferencia por su comunicación entre el comercio y la pasarela aunando información sobre los datos del cliente. El comercio almacena los datos personales de su cliente y PAYCOMET los datos bancarios. Una vez el comercio da de alta el usuario PAYCOMET devuelve un identificador formado por un número único de cliente (IDUSER) y un token (TOKENUSER).

De esta forma el comercio tiene un común identificador con PAYCOMET para realizar gestiones sobre su cuenta de cliente como:

• Alta de usuario (add_user)
• Información de Usuario (info_user)
• Eliminación de Usuario (remove_user)
• Cobro de Usuario (execute_purchase)
• Cobro de Usuario con DCC (execute_purchase_dcc)
• Confirmación de cobro con DCC (confirm_purchase_dcc)

En el mismo servicio se ha añadido la operativa de subscripción. Esta operativa es completamente paralela a la de almacenamiento de datos bancarios del cliente. La gestión de las subscripciones se realizarán con las siguientes funciones:

• Alta de subscripción (create_subscription)
• Modificación de subscripción (edit_subscription)
• Eliminación de subscripción (remove_subscription)

También están presentes las operaciones relacionadas con las preautorizaciones, a través de las funciones:

• Alta de preautorización (create_preauthorization)
• Confirmación de preautorizcion (preauthorization_confirm)
• Anulación de preautorización (preauthorization_cancel)

De esta forma se dividen dos conceptos en el mismo servicio que es necesario aclarar su finalidad y diferencias:

Notificación de la Operación: Webhook

El proceso de compra es llevado a cabo por la pasarela de pagos y la resolución de la operación es devuelta directamente en el mensaje de respuesta. No obstante es posible configurar a través del panel de cliente de PAYCOMET métodos de notificación adicionales para mantener el conocimiento de la operación a usuarios o lanzar mecanismos adicionales.

Estas notificaciones son idénticas a las enviadas por otro tipo de productos de pasarela de pagos, tales como pasarela WEB o Venta Telefónica. De esta manera es posible para el cliente mantener un control unificado de las ventas realizadas por el comercio

Para una correcta notificación del proceso de pago es posible configurar el sistema de notificaciones para que te informe del estado de la operación llevada a cabo por la pasarela, bien por correo electrónico, llamada a una URL en segundo plano (independiente del proceso de respuesta al servicio) o ambas y de forma global mediante SMS.

Correo electrónico

La información contenida en un correo de notificación tipo es la siguiente:

		
			Se ha producido una venta según los siguientes parámetros:

			Identificador de cuenta: 0gs265nc

			Tipo de transacción: Autorización (1)

			País de expedición de la tarjeta: ES

			Fecha y hora de la transacción (yyyymmddhhmmss): 20101027110536

			Orden: 2010102711053676

			Respuesta: OK

			ID de error: 0

			Descripción del error:

			Código de autenticación: 802335/120098123810102711053606007000

			Moneda: EUR

			Cantidad (euros): 10.00

			Cantidad (origen): 1000

			Idioma: es

			ID de producto: 25

			Firma:

			Firma Extendida: 94f487ad8b57141d91fbc8fcda9e346cf17254bc

			Pago Seguro: 0

			Scoring: 0

			Marca Tarjeta: VISA

			Código BIC: BSABESBBXXX

			Número de serie: 00000200275

			PAYCOMET ID: 122548685

		
	

Llamada a URL

A la URL de destino se le pasan los parámetros de la notificación con el método POST según la siguiente tabla:

La firma extendida para comprobación de notificaciones (NotificationHash) se calculará de la siguiente manera:

Configuración del TPV

Para poder utilizar la pasarela de pago PAYCOMET en tu comercio deberás estar en posesión de los parámetros de configuración necesarios. Éstos pueden obtenerse a través de la plataforma de gestión de cliente de PAYCOMET, en el área de cliente

Una vez dentro de la plataforma, puedes revisar la configuración del producto contratado mediante el menú Terminales->"Nombre de terminal"->Datos de terminal.

Tras pulsar en el terminal elegido, aparecerá un panel con la información básica del producto bajo el apartado “Credenciales de integración”. En concreto los datos necesarios durante el proceso de integración son:

• Contraseña
• Número de terminal
• Código de cliente
• URL del servicio (https://api.paycomet.com/gateway/xml-bankstore)
• URL del archivo de descripción del servicio web (WSDL) a modo de referencia (https://api.paycomet.com/gateway/xml-bankstore?wsdl)

Integración para la captura de datos

Para facilitar el cumplimiento de la norma PCI-DSS, el comercio dispone de la solución de captura de datos de su cliente mediante IFRAME personalizable.

Esta solución permite la generación de un formulario de captura de datos con el look&feel predefinido en el panel de control del producto. Esta solución debe ser activada por PAYCOMET, por lo que si no aparece en el panel de control, deberás solicitarlo mediante la apertura de un ticket administrativo desde: (Soporte -> Crear ticket -> Administrativa-Operativa).

En esta sección podrás ver una previsualización de los estilos aplicados más abajo. Los estilos permiten la referencia a sites externos pero deberán responder con un certificado digital correctamente firmado por una entidad de confianza, de lo contrario el navegador del cliente mostrará un error que creará desconfianza en su cliente:

La plantilla se puede personalizar desde la sección: (Terminales->"Nombre de terminal"->Formulario de pago). Aqui se encuentran los campos modificables mediante estilos CSS y una previsualización de dichos cambios.

Si las propiedades disponibles no se ajustan a las necesidades de la aplicación, es posible solicitar un desarrollo de “Template” específico mediante la apertura de un ticket administrativo (Soporte -> Crear ticket -> Administrativa-Operativa).

Te informaremos de los pasos a seguir y la normativa de dicho desarrollo.

Las funcionalidades disponibles en Bankstore IFRAME son:

• Función: (add_user)
• Función: (execute_purchase)
• Función: (create_subscription)

Dichas funcionalidades son las que implican la recogida de los datos bancarios del cliente. De forma posterior, una vez recogidos los datos IDUSER y TOKENUSER, se podrán utilizar las integraciones XML y REST para ejecutar compras, modificación de las suscripciones, información de los datos de tarjeta del usuario, cancelación de suscripciones, etc...

Operativa de captura de datos (ejemplo)

La finalidad de utilizar una integración para la captación de los datos de tarjeta del cliente, es facilitar el cumplimiento de la norma PCI-DSS de la aplicación web. De esta forma la recogida de los datos bancarios se realiza en el entorno seguro de PAYCOMET para posteriormente tratarlos en una conversación Server2Server sin riesgo de datos susceptibles de robo

En un entorno ficticio encontraríamos el siguiente escenario:

Un comercio con alta recurrencia quiere almacenar los datos bancarios del cliente para facilitar las compras futuras. La técnica de la recogida de sus datos bancarios son dos:

• Desde la cuenta de cliente. En su panel de control puede modificar sus datos de facturación, envío e incluso sus tarjetas de crédito/débito asociadas. De esta forma al finalizar el carrito de compra, con sólo pulsar un botón realizará el pago del pedido
• En la primera compra. El cliente introduce todos sus datos bancarios en el proceso final del carrito de compra y quedarán almacenados para compras futuras. De esta forma, elalmacenamiento se realiza de una forma “transparente” al finalizar su pedido.

En el primer caso, el cliente se autentica en la plataforma del e-commerce porque es un usuario previamente dado de alta. Entra en su panel de control y elige añadir una tarjeta de crédito/débito a su cuenta para realizar los pagos. El comercio muestra de una forma integrada en su panel de control, un formulario de captura de datos y PAYCOMET notifica al comercio del resultado. El comercio almacena los datos IDUSER y TOKENUSER a la cuenta del cliente (puede tener varios, para disponer de varias tarjetas), para posteriormente realizar los cobros.

El cliente introduce los datos en el formulario de captura de datos de PAYCOMET (integrado estéticamente con la web del comercio) y PAYCOMET notifica en diferido los datos IDUSER y TOKENUSER en caso de éxito.

El comercio almacena los datos asociados a la cuenta de su cliente para poder ejecutar un cobro mediante una integración SOAP XML

En el segundo caso (almacenamiento en la primera compra), el cliente realiza el pedido normalmente y en la selección del método de pago por tarjeta de crédito/débito le solicita los datos bancarios para proceder al pago.

Los datos bancarios los introduce en un formulario de captura de datos generado por PAYCOMET devolviendo tanto los datos del almacenamiento del usuario (IDUSER y TOKENUSER) como el resultado de la transacción

Este caso sólo se produce si el comercio no dispone de los dos datos IDUSER y TOKENUSER. En caso contrario la comunicación no se haría mediante un formulario de captura de datos.

En la situación que el comercio disponga de los datos IDUSER y TOKENUSER, ya bien por la obtención mediante un add_user, el cliente ha introducido sus datos desde su panel de control del comercio, o mediante execute_purchase, el cliente ya ha realizado una compra con anterioridad, el método para realizar una compra es diferente. El método a utilizar será mediante una conexión Server2Server (XML or REST) donde el comercio utilizará el servicio execute_purchase de forma directa con PAYCOMET.

Se recomienda utilizar algún tipo de autenticación (tipo PIN o similar) para ejecutar el servicio de execute_purchase para evitar compras no solicitadas.

Dichas compras no solicitadas suelen ser motivo de disputa de la operación pudiendo incurrir en gastos adicionales por parte de la entidad bancaria y si se trata de una falta reiterada, se podría llegar a cancelar la cuenta.

Modalidades de cobro en función a la integración

Es importante entender las dos integraciones de cara a construir la operativa del comercio.

Cobros mediante Operativa DCC

PAYCOMET permite mediante la operativa de BankStore, realizar transacciones en modalidad DCC (Dynamic Currency Conversion).

La conversión dinámica de moneda (DCC) convierte las compras internacionales con tarjetas de crédito de Visa® y MasterCard® en la moneda local del titular de la tarjeta. PAYCOMET administra todo el proceso de conversión; desde tasas de cambios directas del tesoro y procesamiento de transacciones, a conciliación de pagos diferidos, liquidación,financiamiento y apoyo.

Con DCC, los clientes internacionales sabrán exactamente cuánto es el total de la compra en su moneda local. Las tarifas de conversión generalmente son mucho más competitivas que en las empresas de cambio.

Esta operativa debe ser activada antes de su uso, contacta con nosotros para darlo de alta al producto deseado.

La integración DCC difiere de la integración convencional por el uso de un servicio específico para realizar el cobro al cliente. Los servicios dedicados al DCC son:

• Cobro de Usuario con DCC
• Confirmación de cobro con DCC

El procedimiento de alta de usuario: add_user, sigue siendo necesario en el caso de compras sin 3D Secure. La diferencia principal es la incorporación de un paso adicional para recibir el cambio disponible de la moneda nativa de la tarjeta en el mismo momento de la transacción:

Integración BANKSTORE XML

Debido a que todo el proceso de pago se realiza en segundo plano (de servidor a servidor) las modificaciones a realizar en el comercio son totalmente ajenas a la experiencia de usuario.

Las tecnologías disponibles para la operativa con la pasarela de pagos PAYCOMET son SOAP y REST, ambas basadas en HTTPS para evitar problemas de transporte a través de firewalls y otros dispositivos y a la vez garantizar la seguridad de las operaciones. Existe un soporte muy amplio para la realización de llamadas con ambos protocolos para los principales lenguajes de programación usados en entornos web.

Las peticiones se realizan mediante el protocolo de transporte HTTPS, de manera que debes asegurarte de que tu sistema es capaz de realizar las peticiones correctamente y gestionar los certificados de seguridad devueltos por la plataforma para una correcta utilización.

Existen varias operaciones que se podrán lanzar desde el mismo servicio. Las operaciones disponibles vienen descritas a continuación.

Ejecución de alta de usuario en el sistema

Función: (add_user)

Las variables que se requieren para dar de alta a un usuario con sus datos bancarios son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_IDUSER y DS_TOKEN_USER que deberán ser almacenados por el comercio, asociándolo a la cuenta de su cliente, para posteriormente realizar cargos en su tarjeta de crédito/débito.

Información del usuario

Función: (info_user)

Esta función se utilizará para confirmar a los clientes del comercio la tarjeta a la que se le realizará el cobro. Este paso es opcional pero resulta conveniente para evitar desconfianzas.

Las variables que se requieren para solicitar información de un usuario son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error..

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_MERCHANT_PAN que contendrá la tarjeta de crédito/débito enmascarada, dejando visibles sólo los 6 primeros dígitos y los 4 últimos. Esta operativa es muy útil para mostrarle al cliente del comercio con qué tarjeta se va a realizar la transacción.

Ejemplos de integración en diferentes lenguajes:

Eliminación del usuario

Función: (remove_user)

Esta función se utilizará para eliminar un usuario de la cuenta del comercio.

Las variables que se requieren para solicitar la baja de un usuario son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Ejecución de cobro a usuario en el sistema

Función: (execute_purchase)

Una vez el usuario está dado de alta en el sistema, se podrán realizar cobros a su cuenta mediante el envío de sus credenciales y datos de la operación

Las variables que se requieren para realizar un cobro a un usuario dado de alta en el sistema son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Ejemplos de integración en diferentes lenguajes:

Ejecución de cobro a Usuario en el sistema por DCC

Función: (execute_purchase_dcc)

Una vez el usuario está dado de alta en el sistema, se podrán realizar cobros a su cuenta mediante el envío de sus credenciales y datos de la operación. La casuística del DCC requiere que un proceso de pago se realice en dos pasos: execute_purchase_dcc, donde se recibe la moneda nativa de la tarjeta (en caso que la tarjeta tenga la misma moneda que el producto asociado a la transacción, el resultado será de conversión 1:1) y posteriormente se confirmará con el método confirm_purchase_dcc con la moneda seleccionada y la sesión original de la transacción.

Las variables que requiere el servicio para realizar un cobro DCC a un usuario dado de alta en el sistema son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá todos los campos. En este caso el campo DS_ERROR_ID será devuelto vacío. El dato a guardar para la confirmación de la operación es el DS_MERCHANT_DCC_SESSION que se trata del identificador único transaccional vinculante a la operación de compra iniciada en DCC. En el siguiente paso debe confirmarse la moneda para finalizar la transacción y vincularla a la sesión DCC.

Ejemplos de integración en diferentes lenguajes:

Confirmación de moneda en pago DCC

Función: (confirm_purchase_dcc)

Una vez se ha devuelto el parámetro DS_MERCHANT_DCC_SESSION cuando se realizó una compra por DCC, el estado de la transacción se queda “a la espera” de la confirmación de moneda. El comercio debe proponer al cliente la moneda en la que quiere pagar (mostrándole la conversión en tiempo real) y cuando la selecciona, el comercio debe confirmar la autorización con la moneda seleccionada por el usuario final.

(ejemplo de interacción con usuario final)

Las variables que se requieren para confirmar una operación en DCC en el sistema son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá todos los campos (excepto DS_MERCHANT_CARDCOUNTRY que es opcional) que deberán ser almacenados por el comercio de cara a una posible devolución. En este caso el campo DS_ERROR_ID será devuelto con valor 0.

Ejemplos de integración en diferentes lenguajes:

Devolución de cobro a usuario en el sistema

Función: (execute_refund)

Se podrán ejecutar devoluciones de las operaciones realizadas mediante esta función. Será necesario los datos identificativos del usuario y el código de autorización bancario.

Las variables que se requieren para realizar una devolución de una operación son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá todos los campos. En este caso el campo DS_ERROR_ID será devuelto vacío. El servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito de la devolución.

Ejecución de alta de suscripción en el sistema

Función: (create_subscription)

El alta de una subscripción implica el alta de un usuario en el sistema BankStore de PAYCOMET. Este proceso es completamente independiente del cobro puntual a un cliente del comercio.

Las variables que se requieren para dar de alta a un usuario con subscripción son (en este orden):

Ejemplo:

DS_SUBSCRIPTION_ORDER = Luis_3268314

El cobro de la subscripción al DS_IDUSER 32 el día 23 de Diciembre del 2030 el sistema devolverá como DS_SUBSCRIPTION_ORDER:

DS_SUBSCRIPTION_ORDER = Luis_3268314[23]20301223

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá los campos DS_IDUSER y DS_TOKEN_USER que deberán ser almacenados por el comercio, asociándolo a la cuenta de su cliente, para posteriormente modificar la subscripción o dar de baja la subscripción.

En caso de ejecución de la primera cuota con éxito el sistema devolverá todos los campos menos DS_ERROR_ID que quedará vacío.

Si la ejecución de la primera cuota es errónea por diferentes motivos (saldo, validez de la tarjeta, etc...), la subscripción será cancelada teniendo que crear otra subscripción nueva. En este caso sólo se devolverá DS_ERROR_ID con el código de error específico.

Modificación de suscripción en el sistema

Función: (edit_subscription)

Si un usuario renueva su subscripción o simplemente se quiere aumentar la cuota del servicio, ofrecemos el servicio de modificar una subscripción. En este caso no se podrá cambiar la moneda ni los datos bancarios del cliente del comercio. La modificación de la subscripción implica el previo alta de un usuario en modo subscripción en el sistema BankStore de PAYCOMET. Este proceso es completamente independiente del cobro puntual a un cliente del comercio.

Las variables que se requieren para modificar una subscripción son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de ejecución de la primera cuota con éxito el sistema devolverá todos los campos menos DS_ERROR_ID que quedará vacío.

Si la ejecución de la primera cuota es errónea por diferentes motivos (saldo, validez de la tarjeta, etc...), la subscripción será cancelada teniendo que crear otra subscripción nueva. En este caso sólo se devolverá DS_ERROR_ID con el código de error específico.

Eliminación de Suscripción

Función: (remove_subscription)

Esta función se utilizará para eliminar una subscripción de la cuenta del comercio.

Las variables que se requieren para solicitar la baja de una subscripción son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Ejecución de alta de suscripción a usuario en el sistema

Función: (create_subscription_token)

El alta de una subscripción por esta vía creará una suscripción a un usuario que ya fue dado de alta en el sistema, sin que sea necesario en este caso, enviar los datos de tarjeta nuevamente.

Las variables que se requieren para dar de alta la subscripción son:

Ejemplo:

DS_SUBSCRIPTION_ORDER = Luis_3268314

El cobro de la subscripción al DS_IDUSER 32 el día 23 de Diciembre del 2030 el sistema devolverá como DS_SUBSCRIPTION_ORDER:

DS_SUBSCRIPTION_ORDER = Luis_3268314[23]20301223

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, importe incorrecto, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de ejecución de la primera cuota con éxito el sistema devolverá todos los campos menos DS_ERROR_ID que quedará vacío.

Si la ejecución de la primera cuota es errónea por diferentes motivos (saldo, validez de la tarjeta, etc...), la subscripción será cancelada teniendo que crear otra subscripción nueva. En este caso sólo se devolverá DS_ERROR_ID con el código de error específico.

Creación de una preautorización a usuario en el sistema

Función: (create_preauthorization)

Una vez el usuario está dado de alta en el sistema, se podrán realizar operaciones de preautorización mediante el envío de sus credenciales y datos de la operación.

Las variables que se requieren para realizar una preautorización a un usuario dado de alta en el sistema son las mismas que las descritas en el apartado Ejecución de cobro a usuario en el sistema

Confirmación de una preautorización a usuario en el sistema

Función: (preauthorization_confirm)

Una vez realizada y autorizada una operación de preautorización, puede confirmarse para realizar el cobro efectivo dentro de los 7 días siguientes; pasada esa fecha, las preautorizaciones pierden su validez. El importe de la confirmación de preautorización puede ser menor, igual o superior sin exceder en un 15% la preautorización original.

Las variables que se requieren para confirmar la preautorización son:

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Cancelación de una preautorización a usuario en el sistema

Función: (preauthorization_cancel)

Una vez realizada una preautorización, puede cancelarse la misma dentro de los 7 días siguientes.

Las variables que se requieren para cancelar la preautorización y los elementos de respuesta son los mismas que para la confirmación de preautorización.

Confirmación de una validación de tarjeta a usuario en el sistema

Función: (deferred_preauthorization_confirm)

Una vez realizada y autorizada una operación de validación de tarjeta., puede confirmarse para realizar el cobro efectivo dentro de las 72 horas siguientes; pasada esa fecha, las preautorizaciones diferidas pierden su validez. El importe de la confirmación de validación de tarjeta debe ser exactamente igual al de la validación de tarjeta original.

Las variables que se requieren para confirmar la validación de tarjeta. son las mismos que para confirmar la preautorización.

La respuesta del servicio tendrá los mismos elementos que la respuesta de la preautorización

Cancelación de una validación de tarjeta a usuario en el sistema

Función: (deferred_preauthorization_cancel)

Una vez realizada una validación de tarjeta, puede cancelarse la misma dentro de las 72 horas siguientes.

Las variables que se requieren para cancelar la validación de tarjeta y los elementos de respuesta son los mismas que para la confirmación de validación de tarjeta.

Ejecución de alta de usuario en el sistema mediante Token

Función: (add_user_token)

Este método permite dar de alta un usuario en base a un token obtenido previamente mediante la solución BankStore JET-IFRAME

Las variables que se requieren para dar de alta a un usuario son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Ejecución de Cobro a un usuario por Referencia

Función: execute_purchase_rtoken

Este método permite ejecutar un cobro en base a un token obtenido previamente mediante la solución de Pago por Referencia

Las variables que se requieren para dar de alta a un usuario son (en este orden):

La respuesta del servicio a la petición se realiza mediante la devolución de un array formateado en XML con los distintos elementos quedan descritos en la tabla siguiente:

Si la petición produjo un error de algún tipo (firma incorrecta, usuario no encontrado, etc) todos los campos se entregarán vacíos, salvo “DS_ERROR_ID” que contendrá el código de error.

En caso de que la transacción sea correcta, el servicio devolverá el campo DS_RESPONSE cuyo valor será 0 o vacío en caso de error y 1 en caso de éxito en la eliminación.

Integración BANKSTORE IFRAME

La integración mediante un marco IFRAME (una página web independiente ubicada dentro de otra página web, en este caso la pasarela de pago de PAYCOMET y la tienda respectivamente) se realiza mediante un objeto IFRAME con origen la dirección URL

https://api.paycomet.com/gateway/ifr-bankstore

A continuación mostramos un ejemplo del código HTML (se han simplificado los parámetros de llamada, que se tratarán más adelante):

Para evitar bloqueos en las redirecciones requeridas por el proceso de pago en algunos navegadores con restricciones de seguridad es imprescindible indicar estos parámetros en la declaración del iframe.

Los parámetros de llamada deben formatearse de la siguiente manera:

Operaciones permitidas:

Parámetros

Ejecución de Alta de Usuario en el sistema (add_user)

Esta operación dará de alta un nuevo usuario en el sistema y realizará la notificación correspondiente.

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación del alta de usuario en el sistema solamente se enviará mediante llamada a la URL configurada en el panel de control. No se enviará notificación del alta de usuario por correo electrónico.

A la URL de destino se le pasan los parámetros de la notificación con el método POST según la siguiente tabla:

Cálculo de Firma

Las notificaciones incluirán una firma para la comprobación de la integridad de los datos. El cálculo de la misma se realiza de la siguiente forma (en pseudo-código):

Ejecución de Cobro (Alta implícita de Usuario en el sistema) (execute_purchase)

Esta operación dará de alta un nuevo usuario en el sistema y realizará la operación de cobro sobre ese usuario. Se notificará del resultado del alta de usuario y la operación de cobro.

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de un cobro a un nuevo usuario en el sistema se efectuará conforme a lo descrito en el apartado Llamada Url Notificación.

A la URL de destino se le pasan los parámetros de la notificación ya especificados en Llamada url Notificación y en caso de alta de usuario y cobro correcto, se devolverán además:

Ejecución de Alta de Suscripción (Alta implícita de Usuario en el sistema) (create_subscription)

El alta de una subscripción implica el alta de un usuario en el sistema BankStore de PAYCOMET. Esta operación dará de alta un nuevo usuario en el sistema y realizará la operación del primer cobro de la suscripción. Se notificará del resultado de la suscripción.

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la creación de una suscripción (que implica la ejecución del primer cobro) a un nuevo usuario en el sistema se efectuará conforme a lo descrito para notificaciones Llamada url Notificación.

A la URL de destino se le pasan los parámetros de la notificación ya especificados en Llamada url Notificación y en caso de alta de suscripción correcta (+ operación de cobro correcta), se devolverán además:

Ejecución de Cobro a un usuario existente (execute_purchase_token)

Esta operación realiza un cobro a un usuario dado de alta previamente en el sistema. Se notificará el resultado de la operación (como un Tipo 1, Autorización).

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de un cobro a un usuario existente en el sistema se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

A la URL de destino se le pasan los parámetros de la notificación ya especificados en Llamada url Notificación y además:

Ejecución de Alta de Suscripción a un usuario existente (create_subscription_token)

Esta operación realiza la creación de una suscripción a un usuario ya existente en el sistema y ejecuta la operación del primer cobro de la misma. Se notificará el resultado de la operación (como un Tipo 9, Suscripción).

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de un cobro a un usuario existente en el sistema se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

A la URL de destino se le pasan los parámetros de la notificación ya especificados en Llamada url Notificación y además:

Ejecución de Alta de Preautorización (Alta Implícita de Usuario en el sistema) (create_preauthorization)

Esta operación dará de alta un nuevo usuario en el sistema y realizará la operación de alta de preautorización. Se notificará del resultado del alta de usuario y la operación de preautorización.

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de un cobro a un usuario existente en el sistema se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

A la URL de destino se le pasan los parámetros de la notificación ya especificados en Llamada url Notificación y además:

Ejecución de Confirmación de Preautorización (preauthorization_confirm)

Esta operación realizará la operación de confirmación de preautorización. Se notificará del resultado de la operación de confirmación de preautorización.

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de un cobro a un usuario existente en el sistema se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

Ejecución de Cancelación de Preautorización (preauthorization_cancel)

Esta operación realizará la operación de cancelación de preautorización. Se notificará del resultado de la operación de cancelación de preautorización.

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de un cobro a un usuario existente en el sistema se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

Alta de Preautorización a un usuario existente (create_preauthorization_token)

Esta operación realiza una preautorización a un usuario dado de alta previamente en el sistema. Se notificará el resultado de la operación (como un Tipo 3, Preautorización).

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de un cobro a un usuario existente en el sistema se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

A la URL de destino se le pasan los parámetros de la notificación ya especificados en Llamada url Notificación y además:

Validación de tarjeta y confirmación (alta implícita de usuario en el sistema) (deferred_preauthorization)

Este tipo de operacion permite al comercio validar si los datos de tarjeta introducidos son correctos. En esta validacion se realiza la autenticacion del titular salvo que el comercio no posea metodo de pago seguro (Tipo 13). Para utilizarlo en la rest se trata de llamar a preatuh para verificar la tarjeta con los datos del pago y confirmpreauth para completarlo, con el parámetro deferred=1 en ambos caso. Para utilizarlo en GET hay que llamar a deferred_preauthorization y deferred_preauthorization_confirm análogamente.

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la validación de tarjeta en el sistema se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

A la URL de destino se le pasan los parámetros de la notificación ya especificados en Llamada url Notificación y además:

Aprobación tras validación de tarjeta (deferred_preauthorization_confirm)

Esta operación realizará la operación de confirmación tras la validación de tarjeta. Se notificará del resultado de la operación de confirmación tras la validación de tarjeta (Tipo 16).

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución tras la validación de tarjeta. se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

Cancelación tras validación de tarjeta (deferred_preauthorization_cancel)

Esta operación realizará la operación de cancelación tras la validación de tarjeta. Se notificará del resultado de la operación de cancelación de validación de tarjeta (Tipo 14).

Para ejecutar una llamada correcta será necesario entregar los siguientes datos:

Cálculo de Firma

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Notificación (Llamada a URL)

La notificación de la ejecución de cobro a un usuario por referencia se efectuará conforme a lo descrito en el apartado Llamada url Notificación.

Sobreescritura de parámetros URLOK y URLKO

Adicionalmente a los parámetros citados para cada tipo de operación, y de forma genérica y transversal a todas las operativas, es posible sobreescribir los parámetros URLOK y URLKO. Dichos parámetros indican al sistema las URL a las que redirigir el resultado de la operación, en función de su éxito o rechazo.

Esta posibilidad está disponible en prácticamente todas las entidades bancarias. Si necesitas utilizarla verifica este punto con PAYCOMET.

Anexo I – Cálculo de la firma de comercio – XML Bankstore

La firma deberá ser calculada en el servidor del comercio y englobará los principales parámetros de la llamada para verificar la integridad de los datos a través de Internet y el navegador del comprador.

El algoritmo de cifrado utilizado al efecto será SHA512, el cual nos permite cifrar una cadena de texto. Este tipo de algoritmos de un solo sentido impide obtener el parámetro inicial a partir del resultado.

La firma se calculará de modos distintos dependiendo de la función utilizada, para verificar la integridad de los datos de envío a la plataforma.

Para facilitar la generación de la firma en lenguajes sin las herramientas necesarias para el cálculo de algoritmos SHA512 se han incluído una serie de librerías. Puedes descargar los archivos desde el apartado Soporte -> Documentación del panel de control de cliente.

Algunas de estas librerías han sido realizadas por personas o entidades ajenas a PAYCOMET. Consulta el contenido de cada archivo para más información.

CÁLCULOS DE FIRMAS DEPENDIENDO DE LA FUNCIÓN EMPLEADA

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

Función: (add_user)

Función: (info_user)

Función: (remove_user)

Función: (execute_purchase)

Función: (execute_purchase_dcc)

Función: (confirm_purchase_dcc)

Función: (execute_refund)

Función: (create_subscription)

Función: (edit_subscription)

Función: (remove_subscription)

Función: (create_subscription_token)

Función: (create_preauthorization)

Función: (preauthorization_confirm)

Función: (preauthorization_cancel)

Función: (deferred_preauthorization_confirm)

Función: (deferred_preauthorization_cancel)

Función: (add_user_token)

Función: (execute_purchase_rtoken)

Anexo II – Tipos de operaciones

Los tipos de operaciones que se notificarán, se detallan en la siguiente tabla:

Anexo II - Firma avanzada VHASH

La firma avanzada VHASH tiene como objetivo securizar y mantener la integridad de la información de datos personales que pueden contener las variables enviadas en la generación del IFRAME. Esta funcionalidad, debe ser activada por PAYCOMET.

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

SHA512( MD5( QUERY_STRING + MD5( PASSWORD ) ) )

La firma calculada, se debe incluir en los parámetros de la llamada.