Sobre este proyecto
it-programming / desktop-apps
Abierto
Realizar una Interfaz de programación (API)
Pensando en simplificar el trabajo a nuestros clientes e integradores, Nuestro Banco ha desarrollado una interfaz de programación (también conocida como API, siglas del inglés Application Program Interface) que internamente se hace cargo de la complejidad técnica del protocolo de comunicación con el Pinpad, y provee a cambio una serie de funciones de muy fácil uso que la aplicación puede ejecutar desde su propio código a fin de instruir al Pinpad a realizar determina función en un punto determinado de la operación.
Adicionalmente a la mera función de lectura de tarjetas, la interfaz de programación desarrollada por Nuestro Banco permite al cliente que así lo desee efectuar la autorización en línea de la transacción, entregándole como salida la información necesaria para su aplicación de punto de venta, tal como el resultado (si la operación fue aceptada o declinada), el código de autorización (en caso de haber sido aceptada), el nombre del tarjetahabiente, y toda la información adicional que típicamente se requiere para este tipo de aplicaciones.
Obsérvese que integrado de esta forma, el Pinpad se convierte en una especie de terminal de punto de venta tradicional, pero con la ventaja de que es la aplicación que solicitamos desarrollar es quien lo controla.
Esta serie de funciones está disponible para diversos lenguajes y plataformas de programación, y se describen en forma detallada dentro del presente escrito.
Modos de operación
La interfaz de programación De Nuestro Banco pinpads posee dos modalidades de operación:
1. Lectura de tarjeta con procesamiento de transacción incluido (Envió a Nuestro Banco de datos de operación y respuesta de la transacción)
2. Sólo lectura de tarjeta para procesamiento interno de la información.
Bajo la primera modalidad, al momento de efectuar una transacción, el Pinpad no sólo leerá la tarjeta del cliente, sino que enviará la información de entrada suministrada por la aplicación, así como la información recopilada de la tarjeta hacia el procesador central de pagos de Nuestro Banco con el fin de efectuar la autorización de la misma. Una vez recibida la respuesta del procesador central, la información será entregada a la aplicación del cliente en los parámetros de salida de la misma llamada.
Esta modalidad se recomienda para aquellos clientes que por la arquitectura de su aplicación pueden enviar directamente la transacción a Nuestro Banco sin requerir de la intervención de un tercer componente de software.
Sin embargo, para aquellos clientes que por necesidades de arquitectura requieren hacer llegar la transacción a Al Banco por un medio alterno (por ejemplo, clientes con un servidor de transacciones ISO 8583, los cuales requieren sólo la información leída de la tarjeta para formar el mensaje de la transacción), la interfaz de programación provee la segunda modalidad, en la que únicamente se regresan a la aplicación del cliente los datos de la tarjeta leída sin enviar ningún requerimiento de autorización al procesador central de pagos de Ell Banco. Se asume, por supuesto, que el cliente se hará cargo de hacer llegar la transacción al banco a través de su medio alterno.
Esta segunda modalidad puede ser también de utilidad para aquellos clientes que deseen implantar algún esquema de tarjeta propia, en la que únicamente requieren de la función de lectura de la misma. Por supuesto, las tarjetas deberán cumplir con los estándares mínimos necesarios para poder ser leídas por los dispositivos pinpads.
El usar la interfaz de programación en una modalidad u otra es simplemente cuestión de hacer llamadas a diferentes funciones incluidas dentro del propio API; no hay necesidad de hacer uso de configuraciones o instalaciones especiales. La aplicación puede decidir en cualquier momento, en base a la operación cuándo usar el API en un modo o en otro.
Instrucciones Básicas para operar con la API
En esta sección se detallaran las operaciones básicas de la API ejemplificando el proceso completo desde la lectura de la tarjeta hasta el envío de la operación a El Banco.
Inicialización y liberación del Pinpad
Los pinpads proporcionados por El Banco utilizan una interfaz virtual de bajo nivel basada en puerto serial. Esto significa que aun cuando el puerto físico utilizado sea un usb, el controlador instalado para el dispositivo crea un puerto serial virtual, mediante el cual el api puede interactuar con el pinpad.
El Banco provee a sus clientes el controlador necesario para los pinpads; los cuales deberán solicitarse vía correo electrónico a las direcciones de contacto descritas en la última sección de este manual, especificando el modelo de dispositivo que le fue entregado.
Como en el caso de cualquier otro puerto serial, ya sea virtual o físico, es necesario garantizar que el puerto designado para usarse con el Pinpad se encuentre disponible para uso del API.
La interfaz de programación provee dos llamadas, denominadas prepareDevice y releaseDevice, las cuales deberán ser ejecutadas, la primera al inicio de operaciones para realizar la inicialización del puerto serial asignado, y la segunda al término de la ejecución de la aplicación para garantizar que el puerto quede libre para un eventual uso de otras aplicaciones.
No se recomienda llamar estas dos operaciones por transacción, ya que se estaría haciendo la inicialización y la liberación del puerto innecesariamente múltiples veces. Sin embargo es de mucha importancia que dentro del manejo de excepciones se establezca el procedimiento para liberar el dispositivo.
La Figura 2 esquematiza el uso de estas llamadas por la aplicación:
Figura 2. Esquema de llamadas a la aplicación.
Inicio y fin de transacciones
El API provee dos llamadas, denominadas startTransaction y endTransaction, las cuales deberán ser ejecutadas por la aplicación al inicio y al término de una transacción, respectivamente. Internamente, estas llamadas se utilizan para realizar los pasos necesarios en el pinpad de modo que éste sepa cuándo está por iniciar una transacción y cuándo se ha completado.
Estas llamadas deberán hacerse por cada transacción efectuada con el Pinpad, ya que es necesario informar a éste sobre los eventos de inicio y fin, para que la aplicación residente en el dispositivo se sincronice adecuadamente.
Es importante comentar que ambas llamadas son necesarias aún y cuando el API se utilice en modalidad de sólo lectura de tarjetas. En ese caso, la operación de lectura de tarjeta (y eventual notificación del resultado de la transacción) se considera como una transacción, aun cuando ésta no se haga llegar a El Banco por medio del API.
La Figura 3 bosqueja el uso de estas llamadas por parte de la aplicación:
Figura 3. Bosquejo de llamadas a la aplicación.
Carga de llaves de encripción
Para la seguridad de los comercios y de los tarjetahabientes la información viaja de forma encriptada desde el dispositivo hacia El Banco. Para esto es necesario realizar la carga de la llave de encripción en el dispositivo. Dependiendo la forma en que se realice la conexión entre el punto de venta y El Banco será la llamada a realizarse al API para la carga de la llave.
Se recomienda al desarrollador generar un módulo o una aplicación por separado para la carga de llaves del dispositivo
Conexión directa entre el punto de venta y El Banco
Dando como hecho que el punto de venta tiene conexión directa a Internet y a El Banco, la aplicación del cliente deberá solicitar la información del Pinpad mediante la llamada getInformation. Esta llamada como parámetros de salida entregará la información del dispositivo que incluirá el número de serie y la versión de la aplicación instalada en el dispositivo.
Con la información obtenida de la llamada getInformation se realizará la llamada updateMasterKey, la cual irá a El Banco y solicitará la llave de encripción y la inyectará en el dispositivo. Después de que la llave se inyecte el dispositivo podrá realizar transacciones financieras.
Sin conexión directa entre punto de venta y El Banco
Cuando el punto de venta no tiene acceso directo a la nube y por ende no tiene acceso directo a El Banco, sino que se conecta a un servidor antes de enviar la transacción a El Banco, la aplicación tiene
unas llamadas específicas para estos casos. La aplicación de punto de venta del cliente deberá solicitar la información del dispositivo mediante la llamada getInformation. Este comando entregará la información del dispositivo que incluye el número de serie del dispositivo y la versión de la aplicación instalada en el dispositivo.
Para obtener la llave de encripción El Banco solicita un selector del dispositivo. Este selector se obtiene realizando la llamada getSelector. Esta llamada retornará el selector necesario para solicitar la llave de encripción a El Banco.
Ya con el selector se enviará el comando GET_KEY utilizando la llamada sendTransaction. El Banco retornará la llave de encripción que se inyectará en el dispositivo mediante el llamada loadMasterKey. Después de la inyección de la llave el dispositivo podrá realizar transacciones.
Procesamiento de transacciones
El API provee la funcionalidad para enviar a procesar las transacciones al emisor mediante Payworks. Existe dos maneras de procesar las transacciones: Proceso integrado de transacciones y Proceso independiente de transacciones o por módulos.
Proceso integrado de transacciones
El API de El Banco está diseñado para trabajar en una modalidad que permita en una sola llamada hacer llegar la transacción al procesador central de pagos de El Banco para su autorización. Esta es la modalidad generalmente recomendada a los clientes, a menos que por motivos de su arquitectura requieran hacer llegar la transacción a El Banco por otro medio.
Para utilizar el API en este modo, la aplicación del cliente deberá ejecutar la llamada processTransaction. En ese momento, el Pinpad se preparará para recibir la tarjeta del cliente (ya sea de banda magnética o de chip), la leerá, generará la información necesaria para enviar la información a El Banco, recibirá la respuesta y entregará el resultado a la aplicación del cliente en los parámetros de salida de esta misma llamada.
La llamada espera ciertos parámetros de entrada que indican, entre otras cosas, el tipo de transacción, el importe de la misma, etc.
La Figura 4 ilustra la secuencia de eventos que se llevan a cabo al momento de ejecutar la llamada
processTransaction:
Figura 4. Secuencia de eventos del método processTransaction.
Obsérvese que dado que el API intentará enviar la transacción hacia El Banco, se requiere que las aplicaciones que utilicen el API bajo esta modalidad tengan disponible la conexión necesaria al momento de ejecutar la llamada. La conexión a El Banco puede estar disponible en diferentes modos: Internet, línea dedicada, VPN, etc., Y normalmente es gestionada por el cliente al momento de tramitar su afiliación.
Al momento de ejecutar esta llamada, el cliente observará que en la pantalla del Pinpad se despliega la leyenda “Inserte tarjeta”. En este momento el cliente podrá deslizar su tarjeta (si es de banda magnética) o insertarla (si es de chip). En el caso de una tarjeta de chip, ésta no deberá ser retirada hasta que la transacción se complete, ya que de lo contrario ésta no podrá concluirse satisfactoriamente.
La Figura 5 muestra un tipo de Pinpad provisto por El Banco, el VX820, en donde se señalan claramente los lectores correspondientes a cada tipo de tarjeta (banda y chip); otros modelos contarán con lectores similares:
Figura 5. Pinpad VeriFone Vx820.
Lector de banda magnética
Lector de chip
La llamada a processTransaction entregará como parámetros de salida a la aplicación del cliente la información necesaria para que ésta pueda proceder a hacer sus registros en base de datos, efectuar impresión de ticket, etc.
Proceso independiente de transacciones
En el caso de aplicaciones que requieran hacerse cargo de la transacción directamente, el API provee dos llamadas: readCard y notifyResult.
Como su nombre lo indica, la primera llamada se utiliza exclusivamente para realizar el proceso de lectura de una tarjeta del cliente, sea de banda o chip, y entregará como parámetros de salida la información necesaria para que la aplicación del cliente, o un tercer componente de software, pueda construir el mensaje de la transacción y enviarlo a El Banco.
En el caso de tarjetas con banda magnética, el API internamente detecta cuando una tarjeta leída es bancaria, y en ese caso entrega como parámetros de salida los datos desglosados del nombre del tarjetahabiente, el número de tarjeta y la fecha de expiración. Si la tarjeta no es reconocida como bancaria (Visa, MasterCard o American Express), la llamada devolverá únicamente el contenido de los tracks 1 y 2 que se hubieren reconocido en la lectura.
Es importante mencionar en este punto que el mecanismo de lector del Pinpad está diseñado para leer tarjetas que cumplen con los estándares ISO 7810, 7811 y 7813 que reglamentan el diseño de las tarjetas, las características del material magnético de la banda, el formato de grabación de los tracks, el contenido de los mismos, etc. No se garantiza la lectura de tarjetas que no se adhieran a dichos estándares.
Para el caso de tarjetas con chip, el equipo podrá leer sin problema todas aquellas tarjetas que cumplan con los estándares de EMVCo publicados sobre la materia. No se garantiza la lectura de tarjetas de chip que no cumplan con dichos estándares. Cuando la lectura se ha realizado sin problema, la llamada devolverá igualmente a la aplicación del cliente la información desglosada del nombre del tarjetahabiente, el número de tarjeta y la fecha de expiración para facilitar el proceso de la transacción en el punto de venta.
En el caso de tarjetas que posean tanto chip como banda magnética, la aplicación del Pinpad considerará al chip como el medio de lectura preferido, ya que se considera más seguro. Por tanto, si el cliente intenta deslizar por el lector de banda una tarjeta de chip, la lectura será rechazada y se invitará al cliente a que utilice el lector de chip.
En caso de que el Pinpad detecte que el chip de la tarjeta es defectuoso y no pueda ser leído, se aceptará el uso de la banda después del segundo intento fallido de lectura de chip. A esta situación se le denomina lectura de banda forzada, o “fallback” en inglés. En esos casos la aplicación no requiere hacer una segunda llamada a readCard; los reintentos y la aceptación de la lectura de banda ocurren dentro de la misma llamada.
Como parte de la información de salida suministrada por esta llamada, la aplicación del cliente podrá determinar cuál fue el medio por el que se leyó la tarjeta, a saber: banda magnética, chip o banda magnética forzada (fallback). Esta información requiere ser enviada al banco emisor, por lo que si el cliente se está haciendo cargo de la transacción, deberá informar a El Banco sobre el tipo de lectura realizada, lo cual se hará dependiendo del medio que se utilice para hacer llegar la transacción a El Banco. Por ejemplo, aquellos clientes que cuentan con un servidor de transacciones iso 8583 deberán generar el campo 22 (pos entry mode) con los valores adecuados dependiendo de la salida que entregue esta llamada.
Para el caso de las tarjetas de chip, la llamada a readCard devolverá igualmente la información de Tags EMV que la especificación define como requisito para ser enviados al banco emisor para su validación. Esta es una cadena ASCII de dígitos hexadecimales que la aplicación del cliente deberá hacer llegar a El Banco dependiendo del medio que utilice para tal fin. Por ejemplo, si se tiene un servidor de transacciones iso 8583, la cadena entregada por esta llamada deberá ser convertida a la secuencia binaria respectiva y colocada en el campo 55 del mensaje iso 8583 como lo señala la especificación terminal to host.
Es importante comentar que el procesador central de pagos de El Banco puede rechazar aquellas transacciones que no cumplan con la información necesaria requerida por los estándares de transacciones financieras vigentes en el momento.
La llamada a Notifyresult se requiere únicamente para tarjetas con chip, ya que la especificación emv obliga a la aplicación del cliente a informar al dispositivo sobre el resultado de la transacción.
Esta llamada deberá hacerse una vez que ya se tiene el resultado de la transacción, informando de ésta al API través de los parámetros de entrada que dicha llamada espera. Obsérvese que esta llamada deberá hacerse independientemente del resultado de la transacción; es decir, deberá ejecutarse para transacciones aprobadas, declinadas, e inclusive para aquellas en las que no se recibió respuesta por parte del emisor (siempre asumiendo que se trata de transacciones con lectura de chip). Al momento de ejecutarse la llamada a notifyResult, el Pinpad completa los registros necesarios en el chip de la tarjeta,
y despliega el mensaje respectivo invitando al tarjetahabiente o al cliente a retirar su tarjeta, una vez que el proceso de la transacción ha concluido.
Esta es la razón por la que tarjeta no debe retirarse anticipadamente.
El usuario podrá apreciar en este punto la diferencia entre las dos modalidades de operación provistas por el api: mientras que en la modalidad con proceso de transacción incluido el api se encarga de suministrar todos los datos requeridos a el banco y completar la transacción con una sola llamada, en la segunda modalidad es la aplicación del cliente la que en base a la información de salida proporcionada por la llamada a readcard deberá ser responsable de formar el mensaje correspondiente, hacer llegar la transacción a el banco, recibir la respuesta, procesar el resultado de la respuesta y notificar al api del resultado final por medio de una llamada a notifyresult.
Despliegue de mensajes en pantalla
Para aquellos clientes que deseen personalizar los mensajes desplegados en la pantalla del Pinpad, el API incluye una llamada desplegarTexto que permite pasar como parámetro de entrada el texto deseado, e internamente se encarga de que éste sea desplegado en el dispositivo.
Esta llamada puede ejecutarse antes de procesar una transacción, o bien una vez que ésta ha sido completada.
Selección de idioma
El API permite especificar el idioma que se usará para los nombres de variables, valores de éstas y textos de los posibles mensajes de error. Los idiomas actualmente soportados son español e inglés. La forma específica en que el idioma se selecciona depende del lenguaje de programación.
Igualmente, cada una de las llamadas del API tiene un nombre en inglés y en español. Por ejemplo, existe displayText equivalente a desplegarTexto.
Arquitectura
En este capítulo se proporciona un panorama general de la construcción de la interfaz de programación para pinpads de El Banco, así como diversos aspectos técnicos que ayudarán a los consultores especializados a facilitarles el trabajo de integrar el API a las aplicaciones.
Estructura
El API de El Banco está estructurado por niveles, para facilitar así la futura integración de nuevos modelos y/o marcas de dispositivos, evitando así trasladar al cliente las complejidades técnicas internas requeridas por el esquema de comunicación de cada dispositivo.
Es importante enfatizar que la aplicación del cliente no tiene que involucrarse en los detalles de bajo nivel, y que la arquitectura anterior tiene por objetivo hacer lo más transparente posible a los clientes un posible cambio de equipo a futuro.
Físicamente, el api se entrega como una biblioteca de carga dinámica (dll para usuarios windows, so para usuarios unix). Las llamadas disponibles en el API se encuentran convenientemente
exportadas para facilitar su localización desde el código de la aplicación. Dependiendo del lenguaje de programación seleccionado, es posible que se entregue algún componente adicional de software (por ejemplo, para usuarios Java se entrega un archivo .jar que expone la interfaz de programación como un conjunto de clases que son fácilmente utilizables por usuarios de dicho lenguaje).
Parámetros de entrada y salida
Tratando de seleccionar un esquema que resultara fácil de utilizar para los clientes, considerando la diversidad de lenguajes de programación y plataformas existentes, se adoptó un esquema de comunicación para las llamadas del API basado en parámetros, tanto de entrada como de salida. Por medio de ciertos parámetros de entrada la aplicación puede proporcionar a la llamada específica del api la información que requiere para hacer su trabajo, y es también por medio de parámetros de salida que la aplicación del cliente puede recibir retroalimentación del api sobre el resultado de una llamada en particular.
Cada parámetro, tanto de entrada como de salida está identificado por un nombre que es representativo de su uso. Este nombre puede estar en inglés o en español, dependiendo del lenguaje seleccionado al momento de iniciar la operación con el API.
Los valores de cada parámetro invariablemente serán de tipo texto, para evitar así las complejidades que la implementación de tipos específicos diferentes representa para cada posible lenguaje de programación y/o plataforma. Será responsabilidad de la aplicación del cliente realizar las conversiones necesarias entre su propio código y el API cuando maneje algún parámetro con un tipo de dato diferente a texto.
Cada llamada específica del API señala sus parámetros de entrada y/o de salida. La estructura de datos específica para pasarlos depende del lenguaje de programación; en el presente documento puede hallarse la implementación para cada lenguaje soportado.
Instalación del dispositivo Pinpad
El presente capítulo explica los pasos a seguir para conectar los dispositivos pinpad, así como para instalar los componentes de software requeridos, a fin de integrar éstos adecuadamente a la aplicación de punto de venta del cliente.
Conexiones Físicas
Pinpads Con Interfaz USB
Actualmente todos nuestros pinpad cuentan con cable para conexión a puerto USB, entonces es necesario seguir los siguientes pasos:
• Instalar primeramente el controlador (driver) proporcionado por El Banco para virtualizar el puerto serial que utilizará el API para manipular el dispositivo. Solicite la guía detallada sobre la instalación de cada controlador esto depende de cada marca y modelo de equipo. Es importante realizar primero la instalación antes de conectar físicamente el dispositivo.
• Comprobar que la instalación del controlador se ha realizado con éxito. Si esto es así, el nuevo puerto serial virtual instalado por el controlador debe aparecer en la lista de dispositivos de hardware del sistema operativo. En Windows, esta lista puede obtenerse haciendo clic con el botón derecho en el ícono correspondiente a Mi PC y luego seleccionando la opción “Propiedades”, la pestaña “Hardware” y finalmente el botón Administrador de Dispositivos.
Deberá encontrarse una lista similar a la que se muestra en la Figura 6:
21 interredes web api payworks seguro
manual de integración
figura 6. Instalación de Pinpad en la ventada del Administrador de Dispositivos.
Obsérvese que en el ejemplo, el puerto virtual serial asignado es el COM1; este es el identificador de puerto que deberá pasarse como parámetro al API al momento de ejecutar la inicialización del dispositivo (Véase el apartado Funciones de API).
Referencias de Implementación
En este apartado, se revisaran los tipos de operaciones permitidas, así como algunos ejemplos en diferentes lenguajes de programación de los métodos contenidos en la API.
Incluso si el lenguaje de programación no se encontrara en este manual, esto no significa que la integración no se pueda realizar, es probable que solo se requiera realizar un poco más de investigación técnica, por lo cual se le sugiere que contacte a su ejecutivo para validar las opciones que podemos ofrecer para llevar a cabo su integración.
Funciones de API
El presente capítulo proporciona la información detallada sobre el uso de cada una de las llamadas disponibles en la interfaz de programación para pinpads de El Banco. Ya que los detalles específicos son dependientes del lenguaje y/o de la plataforma utilizada por el cliente, se ha considerado conveniente subdividir este capítulo en secciones, una por cada uno de los lenguajes directamente soportados por la versión actual del API. De esta forma, los usuarios familiarizados con algún lenguaje en particular encontrarán la información buscada mucho más comprensible.
Si algún lenguaje en particular no apareciera en la presente referencia, esto no significa necesariamente que el API no pueda integrarse con aplicaciones desarrolladas en dicho lenguaje; sin embargo, será necesario realizar una investigación técnica adicional para estudiar la manera de llevar a cabo esa integración. Para ello el usuario que así lo requiera puede contactar a su ejecutivo El Banco indicándole las características de su plataforma y aplicación.
En la Tabla 2. Funciones en español e inglés y su descripción. Se muestra en resumen los nombres de las funciones en inglés y español y una breve descripción:
Tabla 2.
Funciones en español e inglés y su descripción.
Función Nombre Español Nombre en Inglés Descripción
Desplegar texto
desplegarTexto
displayText Despliega un mensaje de texto en la pantalla de la pinpad.
Inicializar dispositivo
inicializarDispositivo
prepareDevice Prepara al pinpad para recibir instrucciones.
Liberar dispositivo
liberarDispositivo
releaseDevice Al término de la ejecución de la aplicación para garantizar que el puerto quede libre.
Iniciar transacción
iniciarTransaccion
startTransaction Le indica al pinpad que iniciará una transacción.
Terminar transacción
terminarTransaccion
endTransaction Indica la finalización de una transacción.
Obtener información
obtenerInformacion
getInformation
Obtiene la información del dispositivo
Obtener selector
obtenerSelector
getSelector Retorna el selector necesario para solicitar la llave de encripción.
Cargar llave
cargarLlaveMaestra
loadMasterKey Inyecta la llave de encripción en el dispositivo.
Cancelar carga de llave
cancelarCargaLlave
cancelLoadKey Cancela la inyección de la llave de encripción.
Actualizar llave
actualizarLlaveMaestra
updateMasterKey Realiza la obtención del selector y la carga de la llave en un solo paso.
Leer Tarjeta
leerTarjeta
readCard Le indica al pinpad que se leerá una tarjeta.
Enviar Transacción
enviarTransaccion
sendTransaction Envía una transacción al motor de Pagos Payworks.
Notificar Resultado
notificarResultado
notifyResult Notifica al pinpad el resultado de una transacción Chip.
Procesar Transacción
procesarTransaccion
processTransaction
Es una función que realiza las 3 funciones anteriores en un solo paso, genera la Lectura de la tarjeta, el envío de la transacción al motor de Pagos y la notificación al Chip del resultado de la transacción.
Obtener Versión
obtenerVersion
getVersion Regresa la versión de DLL que está siendo utilizada.
Tipos de Transacciones
En esta sección analizaremos de los tipos de operación que soporta Payworks Seguro mostrando ejemplos de operativas e información requerida en cada una de las transacciones, así como una breve explicación de su uso para un mayor entendimiento.
Los tipos de operación que podemos utilizar en Payworks Seguro son:
• Venta normal (con plástico presente o PagoMóvil).
• Venta con promoción (con plástico presente).
• Venta forzada (con plástico presente).
• Preautorización (con plástico presente).
• Reautorización.
• Postautorización.
• Devolución referenciada (parcial o total).
• Cancelación de venta.
• Cashback (solicitar anexo al Laboratorio de Payworks).
• Reversa.
Venta
Como venta se identifican aquellas transacciones que se aplican directamente a la cuenta del tarjetahabiente. Los tipos de ventas son:
• Venta normal (con plástico presente o PagoMóvil).
• Venta con promoción (con plástico presente).
• Venta forzada (con plástico presente): Por venta forzada se entiende una transacción en la que el comercio solicita autorización telefónica al emisor y obtiene un código de autorización, el cual es proporcionado como parte de la transacción. El plástico debe de estar presente.
• Venta QPS (Quick Payment Service): Por venta QPS se entiende una transacción en la
que no es necesario que el tarjetahabiente firme un comprobante. Se envía el parámetro QPS en la transacción.
NOTA: La venta QPS es únicamente para transacciones por montos de $250.00 o menores; y es aplicable únicamente a ciertos giros de comercios. Para mayor información comunicarse con su ejecutivo de E-banking El Banco.
Se consideran ventas “normales” aquellas en las que el cargo será aplicado en una sola exhibición al tarjetahabiente. Se consideran ventas con promoción aquellas en las que aplica una o más de las siguientes modalidades:
Venta con promoción
Se consideran ventas con promoción aquellas en las que aplica una o más de las siguientes modalidades:
• Pago diluido a meses sin intereses
• Pago diluido a meses con intereses
• Pago diferido (compre hoy y pague después)
• Esquema mixto (pago diferido y diluido a meses con o sin intereses).
Existen 3 identificadores para reconocer una venta como Q6, estos son PLAN_TYPE, PAYMENTS_NUMBER e INITIAL_DEFERMENT, los diferentes valores entre estas variables indicaran a la venta si es con o sin intereses, el plazo de diferimiento y el número de pagos a realizar. Más adelante se detallara esta información.
Preautorización - Reautorización - Postautorización
La preautorización es una operación que genera una reserva sobre el saldo del tarjetahabiente, en caso de querer hacerlo efectivo el comercio deberá enviar el cierre de esta operación de diversas formas, esto pude ser a través de una postautorización, de un comando como el cierre de lote o cierre de afiliación que se detallarán más adelante. Algunos emisores en lugar de reservar el saldo realizan el cargo directo en sus tarjetas de débito.
La reautorización es una transacción referenciada que tiene por objetivo solicitar una retención adicional de saldo en la cuenta del tarjetahabiente sin necesidad de enviar de nuevo los datos de la tarjeta. La referencia que debe proporcionarse es la de la preautorización sobre la que originalmente se hizo la retención de saldo inicial. Las reautorizaciones están disponibles normalmente sólo para aquellos puntos de venta o terminales registradas con la operativa de hoteles o renta de autos.
Pueden hacerse tantas reautorizaciones como se desee, mientras el emisor de la tarjeta lo apruebe.
La postautorización es una transacción referenciada en la que se cierra una preautorización previa, proporcionándose el monto definitivo. La preautorización cuya referencia se proporciona podría tener una cadena de varias reautorizaciones previas, pero por estándar de intercambio bancario sólo se cerrará la original. El monto de la postautorización está sujeto a las siguientes reglas:
• Hasta por un monto igual al de la preautorización original, para operativa de retail.
• Hasta por el doble de la preautorización original, para operativa de restaurante.
• Hasta por la suma de la preautorización original más la suma de las posibles reautorizaciones adicionales, para operativas de hoteles y renta de autos.
A continuación se muestra un ejemplo de cómo encadenar estos mensajes:
La preautorización solicita un monto (inicial o definitivo) al autorizador en este caso 10 pesos.
******************************************************************** [24/01/2012 13:17:53] se recibio post http desde la ip:
group: [tester] terminal_id: [327782962] password: [a7395007]
user: [a7395007] merchant_id: [7395007] cmd_trans: [preauth] track2:
[6f022e3aca4e4e420e5eb126df96a6f2f4affc35195b8253ed5f089147ff0af5]
control_number: [a-1787715971] entry_mode: [magstripe] amount: [10]
mode: [aut]
********************************************************************
el comercio recibe por respuesta un código de autorización y una referencia que deberá guardar para realizar el cierre de esta operación.
******************************************************************** [24/01/2012 13:17:53] se envio respuesta http hacia la ip: numero_control: [a-1787715971]
referencia: [327346348261]
fecha_rsp_cte: [20120124 13:17:53.158]
TEXTO: [Aprobada+por+Payworks+%28modo+prueba%29] RESULTADO_PAYW: [A]
FECHA_REQ_CTE: [20120124 13:17:53.111]
CODIGO_AUT: [254131]
ID_AFILIACION: [7395007]
********************************************************************
El comercio puede (en caso de ser operativa Hotel o Renta de autos) solicitar una reautorización para reservar más saldo en la cuenta del tarjetahabiente. En este caso se hace una reautorización por 5 pesos adicionales.
******************************************************************** [24/01/2012 13:25:05] se recibio post http desde la ip:
group: [tester]
terminal_id: [327782962]
reference: [327346348261]
password: [a7395007]
user: [a7395007]
merchant_id: [7395007]
cmd_trans: [reauth] control_number: [a-21944831] mode: [aut]
amount: [5]
********************************************************************
observe que se entrega la referencia de la operación original y únicamente el importe adicional que se solicita. El último paso sería la solicitud de cierre de esta operación.
******************************************************************** [24/01/2012 13:28:02] se recibio post http desde la ip:
group: [tester]
terminal_id: [327782962]
reference: [327346348261]
password: [a7395007]
user: [a7395007]
merchant_id: [7395007]
cmd_trans: [postauth] control_number: [a-1548305838] mode: [aut]
amount: [15]
********************************************************************
******************************************************************** [24/01/2012 13:28:02] se envio respuesta http hacia la
ip numero_control: [a-1548305838] referencia: [327346348381]
fecha_rsp_cte: [20120124 13:28:02.591]
TEXTO: [Aprobada+por+Payworks+%28modo+prueba%29]
RESULTADO_PAYW: [A]
FECHA_REQ_CTE: [20120124 13:28:02.551]
CODIGO_AUT: [713967]
ID_AFILIACION: [7395007]
********************************************************************
Se envía la postautorización para final la operación y enviarla a cobro. La transacción se depositara en la cuenta del comercio al día hábil siguiente de la fecha de postautorización.
Devolución Referenciada
Por devolución referenciada se entiende una bonificación que se hace al tarjetahabiente hasta por el 100% de una venta o preautorización previa, para lo cual el comercio deberá enviar la referencia de dicha venta o preautorización sobre la que se desea hacer la devolución. En el caso de preautorizaciones, éstas deberán haber sido ya cerradas, y el importe de la devolución no podrá exceder del importe final con el que se cerró dicha preautorización. Una venta o preautorización cerrada puede tener cualquier número de devoluciones parciales, siempre que el emisor lo autorice y el monto remanente de la transacción original no llegue a cero.
Cancelación
Por cancelación se entiende una transacción referenciada que solicita la anulación de una transacción previa, la cual puede ser una venta, preautorización, crédito directo o cashback. Nuevamente, el comercio enviará la referencia de la transacción que desea cancelar, sin necesidad de enviar un monto, ya que éste es calculado automáticamente por Payworks, de acuerdo a las siguientes reglas:
Si la transacción referenciada es una preautorización abierta:
1. Si el punto de venta o terminal tiene el permiso necesario:
• Para las operativas de retail y restaurante, el monto de la cancelación será igual al monto de la preautorización original.
• Para las operativas de hotel y renta de autos, el monto de la cancelación será igual a la suma de la preautorización original, más la suma de todas la posibles reautorizaciones que pudiera haber.
2. Si el punto de venta o terminal no cuenta con el permiso necesario, la transacción se declina.
3. En cualquier otro caso, la cancelación se efectúa por el monto remanente de la transacción original.
Reversa
Por reversa se entiende una transacción que es generada por el comercio para anular una transacción enviada cuando no se reciba respuesta de Payworks, o bien cuando se haya experimentado alguna falla en la comunicación. La reversa se diferencia de la cancelación fundamentalmente en que la primera es causada por una falla, mientras que la segunda es por voluntad explícita del comercio.
Para efectuar una reversa, el comercio tiene las siguientes alternativas:
• Si no maneja números de control pero conoce la referencia de la transacción que desea reversar, podrá enviarla como dato de entrada en la solicitud de reversa.
• Si maneja números de control para cada transacción, podrá enviar el número de control de la transacción que desea reversar como dato de entrada.
• Si se proporcionan ambos datos (referencia y número de control y en la solicitud de reversa, tomará precedencia el primero). En cualquier caso, Payworks verificará el estado de la transacción: si ésta había sido procesada y aprobada, se procederá a generar el mensaje de reversa hacia el autorizador respectivo; si la transacción no se localiza o no había sido aprobada, se rechazará la reversa sin ejercer acción alguna hacia el autorizador. El comercio podrá comprobar el resultado de la reversa como usualmente lo haría con cualquier otra transacción, verificando el código de resultado Payworks y el texto adicional.
NOTA: Es obligatorio enviar el número de control de la transacción y/o la referencia de la misma para poder realizar la reversa de la transacción.
Por restricciones en la mensajería de los diferentes autorizadores, no todas las transacciones son reversibles. Generalmente se podrán reversar ventas, preautorizaciones y reautorizaciones.
La reversa no aplica para operaciones de cierre de lote o cierre de afiliación; estas operaciones son irreversibles y están a total control del comercio.
Cashback
Por cashback se entiende la disposición de efectivo en el punto de venta por parte del tarjetahabiente. No se podrá realizar una cancelación, devolución o reversa a una transacción enviada como cashback. Para recibir más información sobre la integración de cashback favor de comunicarse con el laboratorio de soporte de Payworks.
Comandos
Los comandos son operaciones disponibles en Payworks Seguro que proveen funcionalidad expandida a la plataforma y permiten al comercio tener un mejor control de su flujo de transacciones.
Los comandos disponibles en Payworks Seguro son los siguientes:
Cierre de afiliación
Un cierre de afiliación es un comando que solicita a Payworks el cierre masivo de todas aquellas preautorizaciones/reautorizaciones se encuentren abiertas y que correspondan a la afiliación de la que procede el comando recibido. Internamente esto originará que Payworks genere las postautorizaciones respectivas hacia el autorizador, evitando así el comercio la necesidad de enviar una por una. Las reglas para cerrar las preautorizaciones son exactamente las mismas descritas en la información correspondiente la transacción de postautorización.
Adicional el comercio deberá tomar en cuenta que el cierre únicamente se procesara por el importe realizado en la preautorización original o por la suma total de todas las reautorizaciones realizadas sobre
la misma. En esta situación no le será posible cerrar por un importe menor una transacción. En tal caso deberá realizarlo previamente al cierre de afiliación de forma individual o suspender la transacción (Ver Suspensión de transacción/Reactivación de transacción).
Cierre de lote
Un cierre de lote es un comando que solicita a Payworks el cierre masivo de todas aquellas preautorizaciones/reautorizaciones se encuentren abiertas y que tengan el lote indicado como dato de entrada en el comando. Un lote es un identificador administrado por el comercio, enviado opcionalmente como dato de entrada en cada transacción, y que sirve para agrupar lógicamente un conjunto de transacciones. El comando de cierre de lote puede ser enviado cualquier número de veces, y cada vez que lo reciba, Payworks localizará en su base de datos todas aquellas preautorizaciones abiertas que tengan dicho lote, procediendo a generar las postautorizaciones respectivas.
Las reglas de cierre son exactamente las mismas descritas en la información correspondiente la transacción de postautorización y cierre de lote.
Es responsabilidad del cliente la administración del lote en las transacciones. Por ejemplo, si ya ha efectuado el cierre para un lote en particular, y posteriormente envía una nueva preautorización con ese mismo lote, dicha preautorización ya no será tomada en cuenta sino hasta que envíe un nuevo comando de cierre de lote.
Verificación
Una verificación es un comando que solicita a Payworks información sobre una transacción previa (status, código de autorización, fechas, etc.). Al igual que en el caso de las transacciones de reversa, el comando de verificación podrá hacerse por cualquiera de los siguientes criterios:
• Proporcionando la referencia de la transacción que se desea verificar
• Proporcionando el número de control de la transacción que se desea verificar
• Enviando simplemente la solicitud de verificación, con lo cual Payworks asumirá que se desea verificar la última transacción recibida del usuario y afiliación especificados en el comando.
Obsérvese que la transacción de reversa y el comando de verificación parecen similares a primera vista. Sin embargo, por ser una transacción, la primera ejerce una acción hacia el autorizador, mientras que la segunda sólo sirve para informar al comercio sobre el estado de una transacción. Por tanto, el comercio podrá utilizar cualquiera de las dos operaciones cuando no esté seguro del estado de una transacción, pero sólo debería usar la reversa cuando realmente desee solicitar al emisor la anulación de una transacción.
Ejemplo: VTA|290444177992|4931720020996319|10.00|C|A|null|819509|2010112211:48:39.652|null|null|2010
1122 11:48:39.762
Tabla 3. Información retornada en una transacción de verificación
Información
Retornada Descripción Formato Ejemplo
Tipo de Transacción
Original • VTA: Venta estándar
• VPR: Venta con promoción
• VFZ: Venta forzada
• PRE: Preautorización
• REA: Reautorización
• POS: Postautorización
• CRD: Crédito
• DEV: Devolución estándar
• CAN: Cancelación
• CSB: Cashback
• REV: Reversa Caracter VTA
Referencia Se genera en forma automática por el motor
de Payworks Numérico 290444177992
Tarjeta Ingresada al momento de la compra Número de tarjeta 4931720020996310
Monto Monto de transacción Formato: ####.## 10
Código Payworks Estatus de la transacción.
A: Abierta (por ejemplo, una preautorización
que no se ha cerrado).
C: Cerrada (por ejemplo, una preautorización ya cerrada, o cualquier otra transacción que
no requiere un cierre).
P: Con devolución parcial (por ejemplo, una venta a la que se le ha hecho por lo menos una devolución parcial).
R: Reversada (cualquier transacción para la
que se ha procesado una reversa).
T: Con devolución total (por ejemplo, una
venta en la que ya se han hecho una o más devoluciones, y la suma de éstas coincide con el importe de la venta).
V: Cancelada (cualquier transacción para la que se haya procesado una cancelación).
X: Indefinida (transacciones que fueron
enviadas al autorizador, pero no recibieron respuesta o fueron declinadas). C
Resultado Payworks Resultado de la transacción. Valores posibles:
A = Aprobada, D = Declinada, R = Rechazada o T = Sin Respuesta A
Resultado de Autorizador Código de respuesta retornado por
el Autorizador.
ÚNicamente en transacciones productivas. N/a modo prueba
Código de Autorización Código entregado por el Autorizador, Variable 819509
Fecha y hora transacción
El Banco Fecha y hora en que la transacción llegó
a El Banco aaaammdd
hh:mm:ss.sss 20101122 11:48:38.473
Fecha y hora transacción
prosa Fecha y hora en que la transacción llegó a
PROSA. Solamente se retorna en transacciones productivas.
aaaammdd
hh:mm:ss.sss 20101122 11:48:38.936
Fecha y hora salida
transacción prosa Fecha y hora en que la transacción
fue retornada por PROSA. Solamente aparece en transacciones productivas. aaaammdd
hh:mm:ss.sss 20101122 11:48:39.380
Fecha y hora salida transacción El Banco
Fecha y hora en que la transacción fue retornada por El Banco.
aaaammdd hh:mm:ss.sss
20101122 11:48:39.762
Suspensión de transacción/Reactivación de transacción
Una suspensión de transacción es un comando que indica a Payworks que una transacción de venta o preautorización no podrá ser referenciada posteriormente por otra transacción (devolución, reautorización, postautorización, etc.), Ni podrá participar en cierres masivos, en tanto no se reciba la correspondiente reactivación.
Una reactivación de transacción es un comando que indica a Payworks que una transacción que se encontraba en estado de suspensión podrá volver a ser referenciada por una nueva transacción y podrá asimismo considerarse para futuros cierres masivos.
De acuerdo al tipo de transacción deberán incluirse cada uno de los posibles campos en el envío de la operación a El Banco. El motor reconocerá las variables dependientes para cada una de las operaciones y si es necesario enviara una respuesta de error con el nombre de la variable faltante en el envío.
Obtención de llave
Una obtención de llave es un comando que indica a Payworks que se está solicitando una llave de encripción para un dispositivo en específico. Antes de enviar el comando para la obtención de la llave es necesario realizar la solicitud de la información de dispositivo y del selector. Después de recibir la llave se debe inyectar en el dispositivo.
Este comando es necesario únicamente cuando el punto de venta no tiene conexión directa a El Banco.
Referencias
El motor de pagos permite el envío de diferentes variables que pueden ser utilizadas como referencias. Las variables son:
Tabla 4. Referencias del cliente
Nombre Español Nombre Inglés Descripción
REF_CLIENTE1 CUSTOMER_REF1 Dato para uso exclusivo del cliente.
REF_CLIENTE2 CUSTOMER_REF2 Dato para uso exclusivo del cliente.
REF_CLIENTE3 CUSTOMER_REF3 Dato para uso exclusivo del cliente.
REF_CLIENTE4 CUSTOMER_REF4 Dato para uso exclusivo del cliente.
REF_CLIENTE5 CUSTOMER_REF5 Dato para uso exclusivo del cliente.
Tipos de Moneda
Los tipos de moneda que soporta el motor de Pagos Payworks son pesos y dólares. Este se especifica en la configuración interna, por lo tanto, no es necesario enviar una variable para especificar este valor.
Es importante aclarar que las afiliaciones en dólares solo aceptan pagos de tarjetas emitidas en el extranjero y el monto deberá ser enviado únicamente en dólares y no en pesos. Es decir si el cliente quiere cobrar 10 USD el monto que deberá enviar es 10.00.
NOTA: Recordar que cada afiliación únicamente puede ser configurada en pesos o dólares, no existe una operativa dual.
Pagos Diferidos
Para Pagos Diferidos Q6 se utiliza la misma afiliación normal, solo se adiciona configuración para también enviar una transacción con diferimiento o promoción. Para operar los pagos diferidos en las transacciones de envío las siguientes 3 variables:
Tabla 5. Parámetros para pagos diferidos
Variable español Variable inglés Descripción
DIFERIMIENTO_INICIAL
INITIAL_DEFERMENT Indica el no.
De meses a los que se difiere el pago
(compre hoy y pague después). Si no hay diferimiento inicial, el valor reportado deberá
ser 00.
NUMERO_PAGOS
PAYMENTS_NUMBER Indica el no. De meses en los que se diluye el
pago. Si sólo hay diferimiento inicial, el valor reportado deberá ser 00.
TIPO_PLAN
PLAN_TYPE Indica el tipo de plan de la promoción sobre la que se hace la transacción. Valores posibles:
Si hay diferimiento inicial: 07 - Si hay no. de pagos:
03 - sin intereses 05 - con intereses
Pensando en simplificar el trabajo a nuestros clientes e integradores, Nuestro Banco ha desarrollado una interfaz de programación (también conocida como API, siglas del inglés Application Program Interface) que internamente se hace cargo de la complejidad técnica del protocolo de comunicación con el Pinpad, y provee a cambio una serie de funciones de muy fácil uso que la aplicación puede ejecutar desde su propio código a fin de instruir al Pinpad a realizar determina función en un punto determinado de la operación.
Adicionalmente a la mera función de lectura de tarjetas, la interfaz de programación desarrollada por Nuestro Banco permite al cliente que así lo desee efectuar la autorización en línea de la transacción, entregándole como salida la información necesaria para su aplicación de punto de venta, tal como el resultado (si la operación fue aceptada o declinada), el código de autorización (en caso de haber sido aceptada), el nombre del tarjetahabiente, y toda la información adicional que típicamente se requiere para este tipo de aplicaciones.
Obsérvese que integrado de esta forma, el Pinpad se convierte en una especie de terminal de punto de venta tradicional, pero con la ventaja de que es la aplicación que solicitamos desarrollar es quien lo controla.
Esta serie de funciones está disponible para diversos lenguajes y plataformas de programación, y se describen en forma detallada dentro del presente escrito.
Modos de operación
La interfaz de programación De Nuestro Banco pinpads posee dos modalidades de operación:
1. Lectura de tarjeta con procesamiento de transacción incluido (Envió a Nuestro Banco de datos de operación y respuesta de la transacción)
2. Sólo lectura de tarjeta para procesamiento interno de la información.
Bajo la primera modalidad, al momento de efectuar una transacción, el Pinpad no sólo leerá la tarjeta del cliente, sino que enviará la información de entrada suministrada por la aplicación, así como la información recopilada de la tarjeta hacia el procesador central de pagos de Nuestro Banco con el fin de efectuar la autorización de la misma. Una vez recibida la respuesta del procesador central, la información será entregada a la aplicación del cliente en los parámetros de salida de la misma llamada.
Esta modalidad se recomienda para aquellos clientes que por la arquitectura de su aplicación pueden enviar directamente la transacción a Nuestro Banco sin requerir de la intervención de un tercer componente de software.
Sin embargo, para aquellos clientes que por necesidades de arquitectura requieren hacer llegar la transacción a Al Banco por un medio alterno (por ejemplo, clientes con un servidor de transacciones ISO 8583, los cuales requieren sólo la información leída de la tarjeta para formar el mensaje de la transacción), la interfaz de programación provee la segunda modalidad, en la que únicamente se regresan a la aplicación del cliente los datos de la tarjeta leída sin enviar ningún requerimiento de autorización al procesador central de pagos de Ell Banco. Se asume, por supuesto, que el cliente se hará cargo de hacer llegar la transacción al banco a través de su medio alterno.
Esta segunda modalidad puede ser también de utilidad para aquellos clientes que deseen implantar algún esquema de tarjeta propia, en la que únicamente requieren de la función de lectura de la misma. Por supuesto, las tarjetas deberán cumplir con los estándares mínimos necesarios para poder ser leídas por los dispositivos pinpads.
El usar la interfaz de programación en una modalidad u otra es simplemente cuestión de hacer llamadas a diferentes funciones incluidas dentro del propio API; no hay necesidad de hacer uso de configuraciones o instalaciones especiales. La aplicación puede decidir en cualquier momento, en base a la operación cuándo usar el API en un modo o en otro.
Instrucciones Básicas para operar con la API
En esta sección se detallaran las operaciones básicas de la API ejemplificando el proceso completo desde la lectura de la tarjeta hasta el envío de la operación a El Banco.
Inicialización y liberación del Pinpad
Los pinpads proporcionados por El Banco utilizan una interfaz virtual de bajo nivel basada en puerto serial. Esto significa que aun cuando el puerto físico utilizado sea un usb, el controlador instalado para el dispositivo crea un puerto serial virtual, mediante el cual el api puede interactuar con el pinpad.
El Banco provee a sus clientes el controlador necesario para los pinpads; los cuales deberán solicitarse vía correo electrónico a las direcciones de contacto descritas en la última sección de este manual, especificando el modelo de dispositivo que le fue entregado.
Como en el caso de cualquier otro puerto serial, ya sea virtual o físico, es necesario garantizar que el puerto designado para usarse con el Pinpad se encuentre disponible para uso del API.
La interfaz de programación provee dos llamadas, denominadas prepareDevice y releaseDevice, las cuales deberán ser ejecutadas, la primera al inicio de operaciones para realizar la inicialización del puerto serial asignado, y la segunda al término de la ejecución de la aplicación para garantizar que el puerto quede libre para un eventual uso de otras aplicaciones.
No se recomienda llamar estas dos operaciones por transacción, ya que se estaría haciendo la inicialización y la liberación del puerto innecesariamente múltiples veces. Sin embargo es de mucha importancia que dentro del manejo de excepciones se establezca el procedimiento para liberar el dispositivo.
La Figura 2 esquematiza el uso de estas llamadas por la aplicación:
Figura 2. Esquema de llamadas a la aplicación.
Inicio y fin de transacciones
El API provee dos llamadas, denominadas startTransaction y endTransaction, las cuales deberán ser ejecutadas por la aplicación al inicio y al término de una transacción, respectivamente. Internamente, estas llamadas se utilizan para realizar los pasos necesarios en el pinpad de modo que éste sepa cuándo está por iniciar una transacción y cuándo se ha completado.
Estas llamadas deberán hacerse por cada transacción efectuada con el Pinpad, ya que es necesario informar a éste sobre los eventos de inicio y fin, para que la aplicación residente en el dispositivo se sincronice adecuadamente.
Es importante comentar que ambas llamadas son necesarias aún y cuando el API se utilice en modalidad de sólo lectura de tarjetas. En ese caso, la operación de lectura de tarjeta (y eventual notificación del resultado de la transacción) se considera como una transacción, aun cuando ésta no se haga llegar a El Banco por medio del API.
La Figura 3 bosqueja el uso de estas llamadas por parte de la aplicación:
Figura 3. Bosquejo de llamadas a la aplicación.
Carga de llaves de encripción
Para la seguridad de los comercios y de los tarjetahabientes la información viaja de forma encriptada desde el dispositivo hacia El Banco. Para esto es necesario realizar la carga de la llave de encripción en el dispositivo. Dependiendo la forma en que se realice la conexión entre el punto de venta y El Banco será la llamada a realizarse al API para la carga de la llave.
Se recomienda al desarrollador generar un módulo o una aplicación por separado para la carga de llaves del dispositivo
Conexión directa entre el punto de venta y El Banco
Dando como hecho que el punto de venta tiene conexión directa a Internet y a El Banco, la aplicación del cliente deberá solicitar la información del Pinpad mediante la llamada getInformation. Esta llamada como parámetros de salida entregará la información del dispositivo que incluirá el número de serie y la versión de la aplicación instalada en el dispositivo.
Con la información obtenida de la llamada getInformation se realizará la llamada updateMasterKey, la cual irá a El Banco y solicitará la llave de encripción y la inyectará en el dispositivo. Después de que la llave se inyecte el dispositivo podrá realizar transacciones financieras.
Sin conexión directa entre punto de venta y El Banco
Cuando el punto de venta no tiene acceso directo a la nube y por ende no tiene acceso directo a El Banco, sino que se conecta a un servidor antes de enviar la transacción a El Banco, la aplicación tiene
unas llamadas específicas para estos casos. La aplicación de punto de venta del cliente deberá solicitar la información del dispositivo mediante la llamada getInformation. Este comando entregará la información del dispositivo que incluye el número de serie del dispositivo y la versión de la aplicación instalada en el dispositivo.
Para obtener la llave de encripción El Banco solicita un selector del dispositivo. Este selector se obtiene realizando la llamada getSelector. Esta llamada retornará el selector necesario para solicitar la llave de encripción a El Banco.
Ya con el selector se enviará el comando GET_KEY utilizando la llamada sendTransaction. El Banco retornará la llave de encripción que se inyectará en el dispositivo mediante el llamada loadMasterKey. Después de la inyección de la llave el dispositivo podrá realizar transacciones.
Procesamiento de transacciones
El API provee la funcionalidad para enviar a procesar las transacciones al emisor mediante Payworks. Existe dos maneras de procesar las transacciones: Proceso integrado de transacciones y Proceso independiente de transacciones o por módulos.
Proceso integrado de transacciones
El API de El Banco está diseñado para trabajar en una modalidad que permita en una sola llamada hacer llegar la transacción al procesador central de pagos de El Banco para su autorización. Esta es la modalidad generalmente recomendada a los clientes, a menos que por motivos de su arquitectura requieran hacer llegar la transacción a El Banco por otro medio.
Para utilizar el API en este modo, la aplicación del cliente deberá ejecutar la llamada processTransaction. En ese momento, el Pinpad se preparará para recibir la tarjeta del cliente (ya sea de banda magnética o de chip), la leerá, generará la información necesaria para enviar la información a El Banco, recibirá la respuesta y entregará el resultado a la aplicación del cliente en los parámetros de salida de esta misma llamada.
La llamada espera ciertos parámetros de entrada que indican, entre otras cosas, el tipo de transacción, el importe de la misma, etc.
La Figura 4 ilustra la secuencia de eventos que se llevan a cabo al momento de ejecutar la llamada
processTransaction:
Figura 4. Secuencia de eventos del método processTransaction.
Obsérvese que dado que el API intentará enviar la transacción hacia El Banco, se requiere que las aplicaciones que utilicen el API bajo esta modalidad tengan disponible la conexión necesaria al momento de ejecutar la llamada. La conexión a El Banco puede estar disponible en diferentes modos: Internet, línea dedicada, VPN, etc., Y normalmente es gestionada por el cliente al momento de tramitar su afiliación.
Al momento de ejecutar esta llamada, el cliente observará que en la pantalla del Pinpad se despliega la leyenda “Inserte tarjeta”. En este momento el cliente podrá deslizar su tarjeta (si es de banda magnética) o insertarla (si es de chip). En el caso de una tarjeta de chip, ésta no deberá ser retirada hasta que la transacción se complete, ya que de lo contrario ésta no podrá concluirse satisfactoriamente.
La Figura 5 muestra un tipo de Pinpad provisto por El Banco, el VX820, en donde se señalan claramente los lectores correspondientes a cada tipo de tarjeta (banda y chip); otros modelos contarán con lectores similares:
Figura 5. Pinpad VeriFone Vx820.
Lector de banda magnética
Lector de chip
La llamada a processTransaction entregará como parámetros de salida a la aplicación del cliente la información necesaria para que ésta pueda proceder a hacer sus registros en base de datos, efectuar impresión de ticket, etc.
Proceso independiente de transacciones
En el caso de aplicaciones que requieran hacerse cargo de la transacción directamente, el API provee dos llamadas: readCard y notifyResult.
Como su nombre lo indica, la primera llamada se utiliza exclusivamente para realizar el proceso de lectura de una tarjeta del cliente, sea de banda o chip, y entregará como parámetros de salida la información necesaria para que la aplicación del cliente, o un tercer componente de software, pueda construir el mensaje de la transacción y enviarlo a El Banco.
En el caso de tarjetas con banda magnética, el API internamente detecta cuando una tarjeta leída es bancaria, y en ese caso entrega como parámetros de salida los datos desglosados del nombre del tarjetahabiente, el número de tarjeta y la fecha de expiración. Si la tarjeta no es reconocida como bancaria (Visa, MasterCard o American Express), la llamada devolverá únicamente el contenido de los tracks 1 y 2 que se hubieren reconocido en la lectura.
Es importante mencionar en este punto que el mecanismo de lector del Pinpad está diseñado para leer tarjetas que cumplen con los estándares ISO 7810, 7811 y 7813 que reglamentan el diseño de las tarjetas, las características del material magnético de la banda, el formato de grabación de los tracks, el contenido de los mismos, etc. No se garantiza la lectura de tarjetas que no se adhieran a dichos estándares.
Para el caso de tarjetas con chip, el equipo podrá leer sin problema todas aquellas tarjetas que cumplan con los estándares de EMVCo publicados sobre la materia. No se garantiza la lectura de tarjetas de chip que no cumplan con dichos estándares. Cuando la lectura se ha realizado sin problema, la llamada devolverá igualmente a la aplicación del cliente la información desglosada del nombre del tarjetahabiente, el número de tarjeta y la fecha de expiración para facilitar el proceso de la transacción en el punto de venta.
En el caso de tarjetas que posean tanto chip como banda magnética, la aplicación del Pinpad considerará al chip como el medio de lectura preferido, ya que se considera más seguro. Por tanto, si el cliente intenta deslizar por el lector de banda una tarjeta de chip, la lectura será rechazada y se invitará al cliente a que utilice el lector de chip.
En caso de que el Pinpad detecte que el chip de la tarjeta es defectuoso y no pueda ser leído, se aceptará el uso de la banda después del segundo intento fallido de lectura de chip. A esta situación se le denomina lectura de banda forzada, o “fallback” en inglés. En esos casos la aplicación no requiere hacer una segunda llamada a readCard; los reintentos y la aceptación de la lectura de banda ocurren dentro de la misma llamada.
Como parte de la información de salida suministrada por esta llamada, la aplicación del cliente podrá determinar cuál fue el medio por el que se leyó la tarjeta, a saber: banda magnética, chip o banda magnética forzada (fallback). Esta información requiere ser enviada al banco emisor, por lo que si el cliente se está haciendo cargo de la transacción, deberá informar a El Banco sobre el tipo de lectura realizada, lo cual se hará dependiendo del medio que se utilice para hacer llegar la transacción a El Banco. Por ejemplo, aquellos clientes que cuentan con un servidor de transacciones iso 8583 deberán generar el campo 22 (pos entry mode) con los valores adecuados dependiendo de la salida que entregue esta llamada.
Para el caso de las tarjetas de chip, la llamada a readCard devolverá igualmente la información de Tags EMV que la especificación define como requisito para ser enviados al banco emisor para su validación. Esta es una cadena ASCII de dígitos hexadecimales que la aplicación del cliente deberá hacer llegar a El Banco dependiendo del medio que utilice para tal fin. Por ejemplo, si se tiene un servidor de transacciones iso 8583, la cadena entregada por esta llamada deberá ser convertida a la secuencia binaria respectiva y colocada en el campo 55 del mensaje iso 8583 como lo señala la especificación terminal to host.
Es importante comentar que el procesador central de pagos de El Banco puede rechazar aquellas transacciones que no cumplan con la información necesaria requerida por los estándares de transacciones financieras vigentes en el momento.
La llamada a Notifyresult se requiere únicamente para tarjetas con chip, ya que la especificación emv obliga a la aplicación del cliente a informar al dispositivo sobre el resultado de la transacción.
Esta llamada deberá hacerse una vez que ya se tiene el resultado de la transacción, informando de ésta al API través de los parámetros de entrada que dicha llamada espera. Obsérvese que esta llamada deberá hacerse independientemente del resultado de la transacción; es decir, deberá ejecutarse para transacciones aprobadas, declinadas, e inclusive para aquellas en las que no se recibió respuesta por parte del emisor (siempre asumiendo que se trata de transacciones con lectura de chip). Al momento de ejecutarse la llamada a notifyResult, el Pinpad completa los registros necesarios en el chip de la tarjeta,
y despliega el mensaje respectivo invitando al tarjetahabiente o al cliente a retirar su tarjeta, una vez que el proceso de la transacción ha concluido.
Esta es la razón por la que tarjeta no debe retirarse anticipadamente.
El usuario podrá apreciar en este punto la diferencia entre las dos modalidades de operación provistas por el api: mientras que en la modalidad con proceso de transacción incluido el api se encarga de suministrar todos los datos requeridos a el banco y completar la transacción con una sola llamada, en la segunda modalidad es la aplicación del cliente la que en base a la información de salida proporcionada por la llamada a readcard deberá ser responsable de formar el mensaje correspondiente, hacer llegar la transacción a el banco, recibir la respuesta, procesar el resultado de la respuesta y notificar al api del resultado final por medio de una llamada a notifyresult.
Despliegue de mensajes en pantalla
Para aquellos clientes que deseen personalizar los mensajes desplegados en la pantalla del Pinpad, el API incluye una llamada desplegarTexto que permite pasar como parámetro de entrada el texto deseado, e internamente se encarga de que éste sea desplegado en el dispositivo.
Esta llamada puede ejecutarse antes de procesar una transacción, o bien una vez que ésta ha sido completada.
Selección de idioma
El API permite especificar el idioma que se usará para los nombres de variables, valores de éstas y textos de los posibles mensajes de error. Los idiomas actualmente soportados son español e inglés. La forma específica en que el idioma se selecciona depende del lenguaje de programación.
Igualmente, cada una de las llamadas del API tiene un nombre en inglés y en español. Por ejemplo, existe displayText equivalente a desplegarTexto.
Arquitectura
En este capítulo se proporciona un panorama general de la construcción de la interfaz de programación para pinpads de El Banco, así como diversos aspectos técnicos que ayudarán a los consultores especializados a facilitarles el trabajo de integrar el API a las aplicaciones.
Estructura
El API de El Banco está estructurado por niveles, para facilitar así la futura integración de nuevos modelos y/o marcas de dispositivos, evitando así trasladar al cliente las complejidades técnicas internas requeridas por el esquema de comunicación de cada dispositivo.
Es importante enfatizar que la aplicación del cliente no tiene que involucrarse en los detalles de bajo nivel, y que la arquitectura anterior tiene por objetivo hacer lo más transparente posible a los clientes un posible cambio de equipo a futuro.
Físicamente, el api se entrega como una biblioteca de carga dinámica (dll para usuarios windows, so para usuarios unix). Las llamadas disponibles en el API se encuentran convenientemente
exportadas para facilitar su localización desde el código de la aplicación. Dependiendo del lenguaje de programación seleccionado, es posible que se entregue algún componente adicional de software (por ejemplo, para usuarios Java se entrega un archivo .jar que expone la interfaz de programación como un conjunto de clases que son fácilmente utilizables por usuarios de dicho lenguaje).
Parámetros de entrada y salida
Tratando de seleccionar un esquema que resultara fácil de utilizar para los clientes, considerando la diversidad de lenguajes de programación y plataformas existentes, se adoptó un esquema de comunicación para las llamadas del API basado en parámetros, tanto de entrada como de salida. Por medio de ciertos parámetros de entrada la aplicación puede proporcionar a la llamada específica del api la información que requiere para hacer su trabajo, y es también por medio de parámetros de salida que la aplicación del cliente puede recibir retroalimentación del api sobre el resultado de una llamada en particular.
Cada parámetro, tanto de entrada como de salida está identificado por un nombre que es representativo de su uso. Este nombre puede estar en inglés o en español, dependiendo del lenguaje seleccionado al momento de iniciar la operación con el API.
Los valores de cada parámetro invariablemente serán de tipo texto, para evitar así las complejidades que la implementación de tipos específicos diferentes representa para cada posible lenguaje de programación y/o plataforma. Será responsabilidad de la aplicación del cliente realizar las conversiones necesarias entre su propio código y el API cuando maneje algún parámetro con un tipo de dato diferente a texto.
Cada llamada específica del API señala sus parámetros de entrada y/o de salida. La estructura de datos específica para pasarlos depende del lenguaje de programación; en el presente documento puede hallarse la implementación para cada lenguaje soportado.
Instalación del dispositivo Pinpad
El presente capítulo explica los pasos a seguir para conectar los dispositivos pinpad, así como para instalar los componentes de software requeridos, a fin de integrar éstos adecuadamente a la aplicación de punto de venta del cliente.
Conexiones Físicas
Pinpads Con Interfaz USB
Actualmente todos nuestros pinpad cuentan con cable para conexión a puerto USB, entonces es necesario seguir los siguientes pasos:
• Instalar primeramente el controlador (driver) proporcionado por El Banco para virtualizar el puerto serial que utilizará el API para manipular el dispositivo. Solicite la guía detallada sobre la instalación de cada controlador esto depende de cada marca y modelo de equipo. Es importante realizar primero la instalación antes de conectar físicamente el dispositivo.
• Comprobar que la instalación del controlador se ha realizado con éxito. Si esto es así, el nuevo puerto serial virtual instalado por el controlador debe aparecer en la lista de dispositivos de hardware del sistema operativo. En Windows, esta lista puede obtenerse haciendo clic con el botón derecho en el ícono correspondiente a Mi PC y luego seleccionando la opción “Propiedades”, la pestaña “Hardware” y finalmente el botón Administrador de Dispositivos.
Deberá encontrarse una lista similar a la que se muestra en la Figura 6:
21 interredes web api payworks seguro
manual de integración
figura 6. Instalación de Pinpad en la ventada del Administrador de Dispositivos.
Obsérvese que en el ejemplo, el puerto virtual serial asignado es el COM1; este es el identificador de puerto que deberá pasarse como parámetro al API al momento de ejecutar la inicialización del dispositivo (Véase el apartado Funciones de API).
Referencias de Implementación
En este apartado, se revisaran los tipos de operaciones permitidas, así como algunos ejemplos en diferentes lenguajes de programación de los métodos contenidos en la API.
Incluso si el lenguaje de programación no se encontrara en este manual, esto no significa que la integración no se pueda realizar, es probable que solo se requiera realizar un poco más de investigación técnica, por lo cual se le sugiere que contacte a su ejecutivo para validar las opciones que podemos ofrecer para llevar a cabo su integración.
Funciones de API
El presente capítulo proporciona la información detallada sobre el uso de cada una de las llamadas disponibles en la interfaz de programación para pinpads de El Banco. Ya que los detalles específicos son dependientes del lenguaje y/o de la plataforma utilizada por el cliente, se ha considerado conveniente subdividir este capítulo en secciones, una por cada uno de los lenguajes directamente soportados por la versión actual del API. De esta forma, los usuarios familiarizados con algún lenguaje en particular encontrarán la información buscada mucho más comprensible.
Si algún lenguaje en particular no apareciera en la presente referencia, esto no significa necesariamente que el API no pueda integrarse con aplicaciones desarrolladas en dicho lenguaje; sin embargo, será necesario realizar una investigación técnica adicional para estudiar la manera de llevar a cabo esa integración. Para ello el usuario que así lo requiera puede contactar a su ejecutivo El Banco indicándole las características de su plataforma y aplicación.
En la Tabla 2. Funciones en español e inglés y su descripción. Se muestra en resumen los nombres de las funciones en inglés y español y una breve descripción:
Tabla 2.
Funciones en español e inglés y su descripción.
Función Nombre Español Nombre en Inglés Descripción
Desplegar texto
desplegarTexto
displayText Despliega un mensaje de texto en la pantalla de la pinpad.
Inicializar dispositivo
inicializarDispositivo
prepareDevice Prepara al pinpad para recibir instrucciones.
Liberar dispositivo
liberarDispositivo
releaseDevice Al término de la ejecución de la aplicación para garantizar que el puerto quede libre.
Iniciar transacción
iniciarTransaccion
startTransaction Le indica al pinpad que iniciará una transacción.
Terminar transacción
terminarTransaccion
endTransaction Indica la finalización de una transacción.
Obtener información
obtenerInformacion
getInformation
Obtiene la información del dispositivo
Obtener selector
obtenerSelector
getSelector Retorna el selector necesario para solicitar la llave de encripción.
Cargar llave
cargarLlaveMaestra
loadMasterKey Inyecta la llave de encripción en el dispositivo.
Cancelar carga de llave
cancelarCargaLlave
cancelLoadKey Cancela la inyección de la llave de encripción.
Actualizar llave
actualizarLlaveMaestra
updateMasterKey Realiza la obtención del selector y la carga de la llave en un solo paso.
Leer Tarjeta
leerTarjeta
readCard Le indica al pinpad que se leerá una tarjeta.
Enviar Transacción
enviarTransaccion
sendTransaction Envía una transacción al motor de Pagos Payworks.
Notificar Resultado
notificarResultado
notifyResult Notifica al pinpad el resultado de una transacción Chip.
Procesar Transacción
procesarTransaccion
processTransaction
Es una función que realiza las 3 funciones anteriores en un solo paso, genera la Lectura de la tarjeta, el envío de la transacción al motor de Pagos y la notificación al Chip del resultado de la transacción.
Obtener Versión
obtenerVersion
getVersion Regresa la versión de DLL que está siendo utilizada.
Tipos de Transacciones
En esta sección analizaremos de los tipos de operación que soporta Payworks Seguro mostrando ejemplos de operativas e información requerida en cada una de las transacciones, así como una breve explicación de su uso para un mayor entendimiento.
Los tipos de operación que podemos utilizar en Payworks Seguro son:
• Venta normal (con plástico presente o PagoMóvil).
• Venta con promoción (con plástico presente).
• Venta forzada (con plástico presente).
• Preautorización (con plástico presente).
• Reautorización.
• Postautorización.
• Devolución referenciada (parcial o total).
• Cancelación de venta.
• Cashback (solicitar anexo al Laboratorio de Payworks).
• Reversa.
Venta
Como venta se identifican aquellas transacciones que se aplican directamente a la cuenta del tarjetahabiente. Los tipos de ventas son:
• Venta normal (con plástico presente o PagoMóvil).
• Venta con promoción (con plástico presente).
• Venta forzada (con plástico presente): Por venta forzada se entiende una transacción en la que el comercio solicita autorización telefónica al emisor y obtiene un código de autorización, el cual es proporcionado como parte de la transacción. El plástico debe de estar presente.
• Venta QPS (Quick Payment Service): Por venta QPS se entiende una transacción en la
que no es necesario que el tarjetahabiente firme un comprobante. Se envía el parámetro QPS en la transacción.
NOTA: La venta QPS es únicamente para transacciones por montos de $250.00 o menores; y es aplicable únicamente a ciertos giros de comercios. Para mayor información comunicarse con su ejecutivo de E-banking El Banco.
Se consideran ventas “normales” aquellas en las que el cargo será aplicado en una sola exhibición al tarjetahabiente. Se consideran ventas con promoción aquellas en las que aplica una o más de las siguientes modalidades:
Venta con promoción
Se consideran ventas con promoción aquellas en las que aplica una o más de las siguientes modalidades:
• Pago diluido a meses sin intereses
• Pago diluido a meses con intereses
• Pago diferido (compre hoy y pague después)
• Esquema mixto (pago diferido y diluido a meses con o sin intereses).
Existen 3 identificadores para reconocer una venta como Q6, estos son PLAN_TYPE, PAYMENTS_NUMBER e INITIAL_DEFERMENT, los diferentes valores entre estas variables indicaran a la venta si es con o sin intereses, el plazo de diferimiento y el número de pagos a realizar. Más adelante se detallara esta información.
Preautorización - Reautorización - Postautorización
La preautorización es una operación que genera una reserva sobre el saldo del tarjetahabiente, en caso de querer hacerlo efectivo el comercio deberá enviar el cierre de esta operación de diversas formas, esto pude ser a través de una postautorización, de un comando como el cierre de lote o cierre de afiliación que se detallarán más adelante. Algunos emisores en lugar de reservar el saldo realizan el cargo directo en sus tarjetas de débito.
La reautorización es una transacción referenciada que tiene por objetivo solicitar una retención adicional de saldo en la cuenta del tarjetahabiente sin necesidad de enviar de nuevo los datos de la tarjeta. La referencia que debe proporcionarse es la de la preautorización sobre la que originalmente se hizo la retención de saldo inicial. Las reautorizaciones están disponibles normalmente sólo para aquellos puntos de venta o terminales registradas con la operativa de hoteles o renta de autos.
Pueden hacerse tantas reautorizaciones como se desee, mientras el emisor de la tarjeta lo apruebe.
La postautorización es una transacción referenciada en la que se cierra una preautorización previa, proporcionándose el monto definitivo. La preautorización cuya referencia se proporciona podría tener una cadena de varias reautorizaciones previas, pero por estándar de intercambio bancario sólo se cerrará la original. El monto de la postautorización está sujeto a las siguientes reglas:
• Hasta por un monto igual al de la preautorización original, para operativa de retail.
• Hasta por el doble de la preautorización original, para operativa de restaurante.
• Hasta por la suma de la preautorización original más la suma de las posibles reautorizaciones adicionales, para operativas de hoteles y renta de autos.
A continuación se muestra un ejemplo de cómo encadenar estos mensajes:
La preautorización solicita un monto (inicial o definitivo) al autorizador en este caso 10 pesos.
******************************************************************** [24/01/2012 13:17:53] se recibio post http desde la ip:
group: [tester] terminal_id: [327782962] password: [a7395007]
user: [a7395007] merchant_id: [7395007] cmd_trans: [preauth] track2:
[6f022e3aca4e4e420e5eb126df96a6f2f4affc35195b8253ed5f089147ff0af5]
control_number: [a-1787715971] entry_mode: [magstripe] amount: [10]
mode: [aut]
********************************************************************
el comercio recibe por respuesta un código de autorización y una referencia que deberá guardar para realizar el cierre de esta operación.
******************************************************************** [24/01/2012 13:17:53] se envio respuesta http hacia la ip: numero_control: [a-1787715971]
referencia: [327346348261]
fecha_rsp_cte: [20120124 13:17:53.158]
TEXTO: [Aprobada+por+Payworks+%28modo+prueba%29] RESULTADO_PAYW: [A]
FECHA_REQ_CTE: [20120124 13:17:53.111]
CODIGO_AUT: [254131]
ID_AFILIACION: [7395007]
********************************************************************
El comercio puede (en caso de ser operativa Hotel o Renta de autos) solicitar una reautorización para reservar más saldo en la cuenta del tarjetahabiente. En este caso se hace una reautorización por 5 pesos adicionales.
******************************************************************** [24/01/2012 13:25:05] se recibio post http desde la ip:
group: [tester]
terminal_id: [327782962]
reference: [327346348261]
password: [a7395007]
user: [a7395007]
merchant_id: [7395007]
cmd_trans: [reauth] control_number: [a-21944831] mode: [aut]
amount: [5]
********************************************************************
observe que se entrega la referencia de la operación original y únicamente el importe adicional que se solicita. El último paso sería la solicitud de cierre de esta operación.
******************************************************************** [24/01/2012 13:28:02] se recibio post http desde la ip:
group: [tester]
terminal_id: [327782962]
reference: [327346348261]
password: [a7395007]
user: [a7395007]
merchant_id: [7395007]
cmd_trans: [postauth] control_number: [a-1548305838] mode: [aut]
amount: [15]
********************************************************************
******************************************************************** [24/01/2012 13:28:02] se envio respuesta http hacia la
ip numero_control: [a-1548305838] referencia: [327346348381]
fecha_rsp_cte: [20120124 13:28:02.591]
TEXTO: [Aprobada+por+Payworks+%28modo+prueba%29]
RESULTADO_PAYW: [A]
FECHA_REQ_CTE: [20120124 13:28:02.551]
CODIGO_AUT: [713967]
ID_AFILIACION: [7395007]
********************************************************************
Se envía la postautorización para final la operación y enviarla a cobro. La transacción se depositara en la cuenta del comercio al día hábil siguiente de la fecha de postautorización.
Devolución Referenciada
Por devolución referenciada se entiende una bonificación que se hace al tarjetahabiente hasta por el 100% de una venta o preautorización previa, para lo cual el comercio deberá enviar la referencia de dicha venta o preautorización sobre la que se desea hacer la devolución. En el caso de preautorizaciones, éstas deberán haber sido ya cerradas, y el importe de la devolución no podrá exceder del importe final con el que se cerró dicha preautorización. Una venta o preautorización cerrada puede tener cualquier número de devoluciones parciales, siempre que el emisor lo autorice y el monto remanente de la transacción original no llegue a cero.
Cancelación
Por cancelación se entiende una transacción referenciada que solicita la anulación de una transacción previa, la cual puede ser una venta, preautorización, crédito directo o cashback. Nuevamente, el comercio enviará la referencia de la transacción que desea cancelar, sin necesidad de enviar un monto, ya que éste es calculado automáticamente por Payworks, de acuerdo a las siguientes reglas:
Si la transacción referenciada es una preautorización abierta:
1. Si el punto de venta o terminal tiene el permiso necesario:
• Para las operativas de retail y restaurante, el monto de la cancelación será igual al monto de la preautorización original.
• Para las operativas de hotel y renta de autos, el monto de la cancelación será igual a la suma de la preautorización original, más la suma de todas la posibles reautorizaciones que pudiera haber.
2. Si el punto de venta o terminal no cuenta con el permiso necesario, la transacción se declina.
3. En cualquier otro caso, la cancelación se efectúa por el monto remanente de la transacción original.
Reversa
Por reversa se entiende una transacción que es generada por el comercio para anular una transacción enviada cuando no se reciba respuesta de Payworks, o bien cuando se haya experimentado alguna falla en la comunicación. La reversa se diferencia de la cancelación fundamentalmente en que la primera es causada por una falla, mientras que la segunda es por voluntad explícita del comercio.
Para efectuar una reversa, el comercio tiene las siguientes alternativas:
• Si no maneja números de control pero conoce la referencia de la transacción que desea reversar, podrá enviarla como dato de entrada en la solicitud de reversa.
• Si maneja números de control para cada transacción, podrá enviar el número de control de la transacción que desea reversar como dato de entrada.
• Si se proporcionan ambos datos (referencia y número de control y en la solicitud de reversa, tomará precedencia el primero). En cualquier caso, Payworks verificará el estado de la transacción: si ésta había sido procesada y aprobada, se procederá a generar el mensaje de reversa hacia el autorizador respectivo; si la transacción no se localiza o no había sido aprobada, se rechazará la reversa sin ejercer acción alguna hacia el autorizador. El comercio podrá comprobar el resultado de la reversa como usualmente lo haría con cualquier otra transacción, verificando el código de resultado Payworks y el texto adicional.
NOTA: Es obligatorio enviar el número de control de la transacción y/o la referencia de la misma para poder realizar la reversa de la transacción.
Por restricciones en la mensajería de los diferentes autorizadores, no todas las transacciones son reversibles. Generalmente se podrán reversar ventas, preautorizaciones y reautorizaciones.
La reversa no aplica para operaciones de cierre de lote o cierre de afiliación; estas operaciones son irreversibles y están a total control del comercio.
Cashback
Por cashback se entiende la disposición de efectivo en el punto de venta por parte del tarjetahabiente. No se podrá realizar una cancelación, devolución o reversa a una transacción enviada como cashback. Para recibir más información sobre la integración de cashback favor de comunicarse con el laboratorio de soporte de Payworks.
Comandos
Los comandos son operaciones disponibles en Payworks Seguro que proveen funcionalidad expandida a la plataforma y permiten al comercio tener un mejor control de su flujo de transacciones.
Los comandos disponibles en Payworks Seguro son los siguientes:
Cierre de afiliación
Un cierre de afiliación es un comando que solicita a Payworks el cierre masivo de todas aquellas preautorizaciones/reautorizaciones se encuentren abiertas y que correspondan a la afiliación de la que procede el comando recibido. Internamente esto originará que Payworks genere las postautorizaciones respectivas hacia el autorizador, evitando así el comercio la necesidad de enviar una por una. Las reglas para cerrar las preautorizaciones son exactamente las mismas descritas en la información correspondiente la transacción de postautorización.
Adicional el comercio deberá tomar en cuenta que el cierre únicamente se procesara por el importe realizado en la preautorización original o por la suma total de todas las reautorizaciones realizadas sobre
la misma. En esta situación no le será posible cerrar por un importe menor una transacción. En tal caso deberá realizarlo previamente al cierre de afiliación de forma individual o suspender la transacción (Ver Suspensión de transacción/Reactivación de transacción).
Cierre de lote
Un cierre de lote es un comando que solicita a Payworks el cierre masivo de todas aquellas preautorizaciones/reautorizaciones se encuentren abiertas y que tengan el lote indicado como dato de entrada en el comando. Un lote es un identificador administrado por el comercio, enviado opcionalmente como dato de entrada en cada transacción, y que sirve para agrupar lógicamente un conjunto de transacciones. El comando de cierre de lote puede ser enviado cualquier número de veces, y cada vez que lo reciba, Payworks localizará en su base de datos todas aquellas preautorizaciones abiertas que tengan dicho lote, procediendo a generar las postautorizaciones respectivas.
Las reglas de cierre son exactamente las mismas descritas en la información correspondiente la transacción de postautorización y cierre de lote.
Es responsabilidad del cliente la administración del lote en las transacciones. Por ejemplo, si ya ha efectuado el cierre para un lote en particular, y posteriormente envía una nueva preautorización con ese mismo lote, dicha preautorización ya no será tomada en cuenta sino hasta que envíe un nuevo comando de cierre de lote.
Verificación
Una verificación es un comando que solicita a Payworks información sobre una transacción previa (status, código de autorización, fechas, etc.). Al igual que en el caso de las transacciones de reversa, el comando de verificación podrá hacerse por cualquiera de los siguientes criterios:
• Proporcionando la referencia de la transacción que se desea verificar
• Proporcionando el número de control de la transacción que se desea verificar
• Enviando simplemente la solicitud de verificación, con lo cual Payworks asumirá que se desea verificar la última transacción recibida del usuario y afiliación especificados en el comando.
Obsérvese que la transacción de reversa y el comando de verificación parecen similares a primera vista. Sin embargo, por ser una transacción, la primera ejerce una acción hacia el autorizador, mientras que la segunda sólo sirve para informar al comercio sobre el estado de una transacción. Por tanto, el comercio podrá utilizar cualquiera de las dos operaciones cuando no esté seguro del estado de una transacción, pero sólo debería usar la reversa cuando realmente desee solicitar al emisor la anulación de una transacción.
Ejemplo: VTA|290444177992|4931720020996319|10.00|C|A|null|819509|2010112211:48:39.652|null|null|2010
1122 11:48:39.762
Tabla 3. Información retornada en una transacción de verificación
Información
Retornada Descripción Formato Ejemplo
Tipo de Transacción
Original • VTA: Venta estándar
• VPR: Venta con promoción
• VFZ: Venta forzada
• PRE: Preautorización
• REA: Reautorización
• POS: Postautorización
• CRD: Crédito
• DEV: Devolución estándar
• CAN: Cancelación
• CSB: Cashback
• REV: Reversa Caracter VTA
Referencia Se genera en forma automática por el motor
de Payworks Numérico 290444177992
Tarjeta Ingresada al momento de la compra Número de tarjeta 4931720020996310
Monto Monto de transacción Formato: ####.## 10
Código Payworks Estatus de la transacción.
A: Abierta (por ejemplo, una preautorización
que no se ha cerrado).
C: Cerrada (por ejemplo, una preautorización ya cerrada, o cualquier otra transacción que
no requiere un cierre).
P: Con devolución parcial (por ejemplo, una venta a la que se le ha hecho por lo menos una devolución parcial).
R: Reversada (cualquier transacción para la
que se ha procesado una reversa).
T: Con devolución total (por ejemplo, una
venta en la que ya se han hecho una o más devoluciones, y la suma de éstas coincide con el importe de la venta).
V: Cancelada (cualquier transacción para la que se haya procesado una cancelación).
X: Indefinida (transacciones que fueron
enviadas al autorizador, pero no recibieron respuesta o fueron declinadas). C
Resultado Payworks Resultado de la transacción. Valores posibles:
A = Aprobada, D = Declinada, R = Rechazada o T = Sin Respuesta A
Resultado de Autorizador Código de respuesta retornado por
el Autorizador.
ÚNicamente en transacciones productivas. N/a modo prueba
Código de Autorización Código entregado por el Autorizador, Variable 819509
Fecha y hora transacción
El Banco Fecha y hora en que la transacción llegó
a El Banco aaaammdd
hh:mm:ss.sss 20101122 11:48:38.473
Fecha y hora transacción
prosa Fecha y hora en que la transacción llegó a
PROSA. Solamente se retorna en transacciones productivas.
aaaammdd
hh:mm:ss.sss 20101122 11:48:38.936
Fecha y hora salida
transacción prosa Fecha y hora en que la transacción
fue retornada por PROSA. Solamente aparece en transacciones productivas. aaaammdd
hh:mm:ss.sss 20101122 11:48:39.380
Fecha y hora salida transacción El Banco
Fecha y hora en que la transacción fue retornada por El Banco.
aaaammdd hh:mm:ss.sss
20101122 11:48:39.762
Suspensión de transacción/Reactivación de transacción
Una suspensión de transacción es un comando que indica a Payworks que una transacción de venta o preautorización no podrá ser referenciada posteriormente por otra transacción (devolución, reautorización, postautorización, etc.), Ni podrá participar en cierres masivos, en tanto no se reciba la correspondiente reactivación.
Una reactivación de transacción es un comando que indica a Payworks que una transacción que se encontraba en estado de suspensión podrá volver a ser referenciada por una nueva transacción y podrá asimismo considerarse para futuros cierres masivos.
De acuerdo al tipo de transacción deberán incluirse cada uno de los posibles campos en el envío de la operación a El Banco. El motor reconocerá las variables dependientes para cada una de las operaciones y si es necesario enviara una respuesta de error con el nombre de la variable faltante en el envío.
Obtención de llave
Una obtención de llave es un comando que indica a Payworks que se está solicitando una llave de encripción para un dispositivo en específico. Antes de enviar el comando para la obtención de la llave es necesario realizar la solicitud de la información de dispositivo y del selector. Después de recibir la llave se debe inyectar en el dispositivo.
Este comando es necesario únicamente cuando el punto de venta no tiene conexión directa a El Banco.
Referencias
El motor de pagos permite el envío de diferentes variables que pueden ser utilizadas como referencias. Las variables son:
Tabla 4. Referencias del cliente
Nombre Español Nombre Inglés Descripción
REF_CLIENTE1 CUSTOMER_REF1 Dato para uso exclusivo del cliente.
REF_CLIENTE2 CUSTOMER_REF2 Dato para uso exclusivo del cliente.
REF_CLIENTE3 CUSTOMER_REF3 Dato para uso exclusivo del cliente.
REF_CLIENTE4 CUSTOMER_REF4 Dato para uso exclusivo del cliente.
REF_CLIENTE5 CUSTOMER_REF5 Dato para uso exclusivo del cliente.
Tipos de Moneda
Los tipos de moneda que soporta el motor de Pagos Payworks son pesos y dólares. Este se especifica en la configuración interna, por lo tanto, no es necesario enviar una variable para especificar este valor.
Es importante aclarar que las afiliaciones en dólares solo aceptan pagos de tarjetas emitidas en el extranjero y el monto deberá ser enviado únicamente en dólares y no en pesos. Es decir si el cliente quiere cobrar 10 USD el monto que deberá enviar es 10.00.
NOTA: Recordar que cada afiliación únicamente puede ser configurada en pesos o dólares, no existe una operativa dual.
Pagos Diferidos
Para Pagos Diferidos Q6 se utiliza la misma afiliación normal, solo se adiciona configuración para también enviar una transacción con diferimiento o promoción. Para operar los pagos diferidos en las transacciones de envío las siguientes 3 variables:
Tabla 5. Parámetros para pagos diferidos
Variable español Variable inglés Descripción
DIFERIMIENTO_INICIAL
INITIAL_DEFERMENT Indica el no.
De meses a los que se difiere el pago
(compre hoy y pague después). Si no hay diferimiento inicial, el valor reportado deberá
ser 00.
NUMERO_PAGOS
PAYMENTS_NUMBER Indica el no. De meses en los que se diluye el
pago. Si sólo hay diferimiento inicial, el valor reportado deberá ser 00.
TIPO_PLAN
PLAN_TYPE Indica el tipo de plan de la promoción sobre la que se hace la transacción. Valores posibles:
Si hay diferimiento inicial: 07 - Si hay no. de pagos:
03 - sin intereses 05 - con intereses
Categoría Programación y Tecnología
Subcategoría Aplicaciones de escritorio
¿Es un proyecto o una posición? Un proyecto
Actualmente tengo Tengo las especificaciones
Disponibilidad requerida Tiempo completo
Experiencia en este tipo de proyectos Sí (He administrado este tipo de proyectos anteriormente)
Integraciones de API Otros (Otras APIs)
Plataformas requeridas Windows
Plazo de Entrega: No definido
Habilidades necesarias