Manual TPV para el comerciante

Pasarela de Pagos de Unicaja (TPV Virtual):
Manual del Comercio
V3.2 02/01/2009
UNICAJA

Introducción
En este documento se explica cómo instalar y utilizar la Pasarela de Pagos de Unicaja por
parte del comerciante en plataformas Windows NT, Linux, AIX, Solaris y Java (para aquellas
plataformas hardware no mencionadas antes y que soporten Java).
La Pasarela de Pagos, también llamada TPV virtual, es un programa informático que permite
la realización de pagos a través de Internet dentro de un entorno de comercio electrónico.
Para poder instalar el TPV virtual es preciso que previamente el comercio disponga de un sitio
Web con una aplicación de comercio electrónico, es decir, con funciones de selección de
productos de un catálogo, totalización de elementos a adquirir, etc. Será a la hora de que el
comprador desee realizar el pago con cargo a una tarjeta cuando entre en funcionamiento el
TPV virtual de Unicaja.
El TPV virtual realiza las mismas funciones que un TPV real de los que se utilizan
normalmente en las tiendas: permite solicitar autorización de pago contra una tarjeta de pago
y abonar el importe en la cuenta que el comercio debe tener en Unicaja como entidad
adquiriente.
El TPV incluye los mecanismos de seguridad necesarios para que tanto el comerciante como
el cliente puedan tener confianza en el entorno comercial sobre internet. El cliente puede
confiar en que sus datos de tarjeta de pago sólo serán conocidos por Unicaja y los artículos
adquiridos sólo conocidos por el comerciante.
La Pasarela de Pagos de Unicaja consta de dos componentes: un módulo software que reside
en el servidor de comercio electrónico del comerciante y otro módulo que reside en los
sistemas de Unicaja. Esta división en dos módulos obedece a simplificar al máximo la puesta
en marcha de la tienda virtual, no exigiendo a ésta adaptaciones complejas en su sistema, ni a
disponer de un certificado digital.
Funcionamiento de la Pasarela de Pagos
Una vez que el cliente del comercio virtual ha efectuado la selección de sus artículos, será
invitado a realizar el pago. En la página Web del comercio desde la que se comience la
operación de pago con tarjeta, existirá un botón, rotulado típicamente “PAGO CON
TARJETA” (figura 1). Este botón deberá llamar a un programa “tpvxxx” 1 , que será
1 El prefijo xxx hace referencia a la plataforma seleccionada, de manera que el fichero tendrá un nombre distinto
para cada plataforma (tpvwnt.exe, tpvlinux, tpvsolar, tpvaix). En el caso de la plataforma Java, no se invocará
a este programa, sino al servlet ServletTPV, con los mismos parámetros especificados para tpvxxx.
Manual TPV virtual para el comerciante
2

suministrado por Unicaja, pasándole los parámetros que se describen a continuación, con el
método “POST”:
Parámetro Descripción Sintaxis Longitud
“tienda”
“referencia”
“importe”
Identificador del comercio, que es
asignado por Unicaja en el
momento de formalizar el contrato
Referencia de la compra, valor
creado por el software de comercio
electrónico del comerciante
Importe de la compra en Euros
(con o sin decimales)
Caracteres alfanuméricos ASCII 9
Caracteres alfanuméricos ASCII.
No se aceptarán caracteres
nacionales como’ñ’, vocales
acentuadas, ...
Caracteres numéricos ASCII. En
caso de llevar decimales, la coma
será el carácter ASCII “,” al que le
seguirán un máximo de dos dígitos
decimales
“divisa” Divisa de la compra Debe tener el valor “EUR” 3
“idioma” Idioma (opcional)
“urlOK”
“urlKO”
URL OK para este pago (opcional)
Parámetro opcional. Lo puede
utilizar el comercio si necesita
indicar una URL OK adaptada a los
requisitos concretos del pago en
curso. Si no se indica, se empleará
la que se tenga como parte de los
datos del comercio. Véase el
apartado “Datos a aportar por el
Comercio” para más detalles.
URL KO para este pago (opcional)
Parámetro opcional. Lo puede
utilizar el comercio si necesita
indicar una URL KO adaptada a los
requisitos concretos del pago en
curso. Si no se indica, se empleará
la que se tenga como parte de los
datos del comercio. Véase el
apartado “Datos a aportar por el
Comercio” para más detalles.
Código de dos letras minúsculas
ASCII representando el idioma, de
acuerdo con la norma ISO 639.
Los valores permitidos son: ‘es’
para español, ‘de’ para alemán y
‘en’ para inglés
Una URL completamente
especificada con protocolo,
nombre o IP de la máquina, puerto,
ruta de archivo, identificador. de
sesión, parámetros.
Una URL completamente
especificada con protocolo,
nombre o IP de la máquina, puerto,
ruta de archivo, identificador. de
sesión, parámetros.
Es necesario que se respete el nombre de los parámetros, reflejados en la primera columna de
la tabla anterior, así como no sobrepasar la longitud máxima de estos parámetros.
* El importe tiene una longitud máxima de 16 caracteres incluyendo la coma decimal. Si no lleva coma decimal, la longitud debe
ser 13. De cualquier forma, el importe no tiene por qué ser completado con ceros por la izquierda.
Manual TPV virtual para el comerciante
10
16 *
2
256
256
3

La llamada a este programa “tpvxxx” hará que el comprador se conecte de forma segura a la
Pasarela de Pagos de Unicaja, donde se le pedirán los datos de pago, concretamente el número
de tarjeta y la fecha de caducidad. Una vez introducidos estos datos, la Pasarela iniciará el
procedimiento de autorización (figura 2).
Mi Tienda On Line
Resumen de la compra
Referencia: A23J2456
Importe: 200,00 EUR
I.V.A. 32,00 EUR
Portes: 5,00 EUR
TOTAL: 237,00 EUR
Pago con tarjeta
Importe a pagar: 237,00 EUR
Num. tarjeta
Mi Tienda On Line
Fecha caducidad
PAGAR
Figura 1 Figura 2
Finalizado el procedimiento de autorización, si el comercio desea ser informado 2
automáticamente del resultado de la operación de pago, la Pasarela llamará al programa que el
comerciante haya especificado en la dirección “Urlconf” 3 , mediante GET, con los parámetros:
Parámetro Descripción
Identificador del comercio, que es
Sintaxis Longitud
“tienda”
asignado por Unicaja en el
momento de formalizar el contrato
Referencia de la compra, valor
Caracteres ASCII 9
“referencia” creado por el software de comercio
electrónico del comerciante
Caracteres alfanuméricos ASCII 10
“autorizacion” Número de autorización Caracteres numéricos ASCII 6
“secuencia”
Número de secuencia asignada a la
transacción por Unicaja
Caracteres numéricos ASCII
Dígitos numéricos ASCII. En caso
5
“importe”
Importe de la compra en Euros
(con o sin decimales)
de llevar decimales, la coma será
el carácter ASCII “,” al que le
seguirán un máximo de dos dígitos
decimales
16
“icontravalor”
Equivalente en pesetas del importe
de la compra
Dígitos numéricos ASCII. 18
“divisa” Divisa de la compra El nemónicos “EUR” en ASCII 3
“dcontravalor” Divisa del contravalor El nemónicos “ESP” en ASCII 3
“fecha” Fecha de la operación Formato dd/mm/aaaa 10
2 La notificación del resultado de la operación al comerciante es opcional. El comerciante puede conocer el
resultado de las operaciones conectándose al servicio de banca on-line UniVía.
3 Véase apartado de “Datos a Aportar por el Comercio”
Manual TPV virtual para el comerciante
4

“seguro”
“numTar”
“cadTar”
“firma”
Si viene este parámetro, indica que
el pago se ha realizado mediante el
protocolo 3-D Secure
El número de la tarjeta de crédito
que se ha utilizado para el pago.
Sólo se envía a los comercios que
lo han solicitado.
Fecha de caducidad de la tarjeta de
crédito que se ha utilizado para el
pago. Sólo se envía a los comercios
que lo han solicitado.
Firma digital de la cadena de
parámetros
La sintaxis de la cadena de parámetros de vuelta será del tipo:
“3DSECURE” 8
Número de tarjeta parcialmente
oculto. Los últimos dígitos se
ocultan con asteriscos “*”.
Fecha en formato “MMAAAA” 6
20
Caracteres alfanuméricos ASCII 32
“nombre del parámetro1”=”valor1”&”nombre del parámetro2”=”valor2”&”.....
Un ejemplo de confirmación de pago podría ser:
tienda=123456789&referencia=REF11&autorizacion=123456&secuencia=12345&importe=6
,00&icontravalor=1000&divisa=EUR&dcontravalor=ESP&fecha=12/01/2002&firma=XX...X
X
El comprador, a continuación, verá en su pantalla el resultado de la operación de pago, junto
con la invitación a imprimir la página como justificante de la transacción (figura 3).
Figura 3 Figura 4
Mi Tienda On Line
PAGO ACEPTADO
Comercio: Mi Tienda On Line
Referencia compra: A23J2456
Importe: 237,00 EUR
Fecha: 22-06-01
Autorización: 25859
Imprima para su control
Mi Tienda On Line
Muchas gracias por su visita
En 48 horas recibirá su
pedido en su domicilio
Así mismo se permitirá al comprador navegar a una página web elegida por el comercio
(Urlok) 4 y residente en su tienda virtual, usada habitualmente para mostrar el típico mensaje
Manual TPV virtual para el comerciante
5

de agradecimiento por la compra o para confirmar el plazo de entrega de los bienes o
servicios (figura 4).
En caso de no haberse podido realizar el pago, el comprador será informado y se le permitirá
navegar a otra página, también elegida por el comercio y residente en la tienda virtual, con el
mensaje que el comerciante estime dar ante esta situación (Urlko) 5 .
En el caso de que la transacción no se pueda completar por falta de autorización, el comercio
podrá conocer este hecho si ha elegido que se le notifique la operación mediante el parámetro
“Urlconf”. Si se da esta circunstancia, se llamará a “Urlconf”, mediante GET, con los
siguientes parámetros:
Parámetro Descripción
Identificador del comercio, que es
Sintaxis Longitud
“tienda” asignado por Unicaja en el
momento de formalizar el contrato
Referencia de la compra, valor
Caracteres ASCII
9
“referencia” creado por el software de comercio
electrónico del comerciante
Caracteres alfanuméricos ASCII
10
“error” Descripción del error
Si viene este parámetro, indica que
Caracteres alfanuméricos ASCII 20
“seguro” el pago se ha intentado realizar
mediante el protocolo 3-D Secure
“3DSECURE” 8
“firma”
Firma digital de la cadena de
parámetros
Manual TPV virtual para el comerciante
Caracteres alfanuméricos ASCII 32
6

Firma digital de la cadena de parámetros
En las notificaciones opcionales enviadas al comercio tras una operación de pago, se envía
como último parámetro el campo “firma”. Este campo es una firma digital de toda la cadena
de parámetros que acompañan a la notificación más el código secreto que se encuentra cifrado
en el fichero de configuración (con extensión “cfg”) que se entrega al comercio.
Mediante la presencia de la firma digital, el comercio puede tener la garantía de que la
información contenida en la cadena de parámetros no ha sido modificada y, por tanto, se trata
de una información auténtica.
Para comprobar la autenticidad de la información, el comerciante debe invocar al programa
“firmxxx” 6 (donde xxx identifica el sistema operativo donde corre el software del comercio),
suministrado en el paquete software del TPV virtual.
La invocación al programa se hará pasándole como parámetro toda la cadena de parámetros
de la notificación. El programa devolverá un valor numérico cero si la firma es correcta y por
lo tanto la información auténtica. El comercio deberá descartar esa notificación si la firma no
es correcta. La forma de invocar el programa varía según en el entorno en que se encuentre
comercio virtual.
Manual TPV virtual para el comerciante
7

Ejemplo de uso del programa de comprobación de firma desde un CGI en Linux y lenguaje C:
……
switch (fork()) {
case -1: /*Error en fork()*/
…
break;
case 0: /*proceso hijo*/
execl (path ejecutable firmlinux,
break;
"firmlinux",
getenv("QUERY_STRING"),
0);
default: /*proceso padre*/
/*espera fin ejecución hijo*/
wait (&retorno_hijo);
/*Si los ocho bits más bajos y los más altos de retorno_hijo tienen el valor 0 indicará que la
ejecución de firmlinux se ha realizado correctamente y que la firma es correcta:
}
8bitsBajos == 0 ejecución firmlinux sin problemas.
8bitsAltos == 0 firma correcta. */
break;
Manual TPV virtual para el comerciante
8

Ejemplo de uso del programa de comprobación de firma desde un CGI en Windows NT y
lenguaje C:
#include
…………
int result;
……
result = spawnl(P_WAIT,
if (result == 0){
}else{
}
"c:\\cgi\\firmnt.exe",
"firmnt.exe",
getenv("QUERY_STRING"),
0);
/*La firma es correcta*/
/*La comprobación de firma no se ha llevado a cabo o no es correcta la firma*/
Aunque no es aconsejable, el comercio podría preferir no verificar la firma digital ya que
siempre puede comprobar sus operaciones comerciales a través del servicio UniVía. En este
caso, basta con ignorar el parámetro “firma”. La verificación de la firma es aconsejable para
garantizar la autenticidad del origen de la confirmación de la compra, es decir, que es
realmente Unicaja quien le comunica esa información. Por este motivo, si el comercio soporta
el mecanismo de confirmaciones de pago, es sumamente aconsejable la verificación de la
firma.
Datos a aportar por el comercio
En el momento de registrar una tienda virtual en Unicaja, el comercio deberá proporcionar
una serie de direcciones a través de las cuales la pasarela de pagos se comunicará con el
comercio virtual.
Manual TPV virtual para el comerciante
9

Estas direcciones son las siguientes:
URL Descripción
Urlok Dirección URL de un programa del comercio a la que se accederá desde
la pasarela de pagos si la operación de compra ha sido satisfactoria.
Podrá indicar una Urlok diferente por cada idioma soportado por Unicaja.
Urlko Dirección URL de un programa del comercio a la que se accederá desde
la pasarela de pagos si la operación de compra no se ha podido realizar.
Podrá indicar una Urlko diferente por cada idioma soportado por Unicaja
Urlconf Dirección URL de un programa del comercio a la que se accederá si el
comerciante quiere que se le notifiquen automáticamente los datos de la
compra. Este parámetro es opcional. Si no existe, el comerciante no será
notificado del resultado de las operaciones, pero podrá consultarlas a
través del servicio UniVía.
En el momento del registro del comercio, Unicaja proporcionará al comerciante un módulo
software que deberá instalar en su servidor de comercio electrónico, según se detalla en el
apartado siguiente.
Instalación del módulo software de la pasarela de
pagos en el servidor del comercio
En este apartado se describe el proceso de instalación del módulo residente en el servidor del
comercio.
La pasarela de Pagos de Unicaja es multitienda, pudiendo ser usada tanto por comercios
individuales como por galerías de comercios. Para ello, junto al ejecutable “tpvxxx”, se
entrega al comerciante un fichero de configuración codigocomercio.cfg por cada uno de los
comercios que vaya a hacer uso del servicio.
Por ejemplo, si tenemos una galería con tres comercios, y al dar de alta en Unicaja a cada uno
de ellos se les asignan los códigos 130000001, 130000002 y 130000003; junto al ejecutable
suministrado a la galería deben ir los ficheros 130000001.cfg, 130000002.cfg y
130000003.cfg, que contienen el código secreto cifrado asociado a cada uno de los comercios.
Instalación en Linux, Solaris y AIX
Al comerciante se le entregará (mediante disquete, correo electrónico u otros medios) un
fichero llamado “cgi_genera.tar”, que tendrá formato tar, y que contendrá en forma
empaquetada los ficheros “codigocomercio.cfg”, el programa “tpvlinux”, “tpvsolar” o
“tpvaix”, según la plataforma sea Linux, Solaris, o AIX y el programa “firmlinux”,
Manual TPV virtual para el comerciante
10

“firmsolar” o “firmaix” según la plataforma. Posteriormente se podrán agregar nuevos
ficheros de configuración “codigocomercio.cfg”.
Para extraer estos ficheros (una vez que este “cgi_genera.tar” esté en el disco del sistema), se
ejecutará el comando UNIX “tar xvf cgi_genera.tar” y como resultado se obtendrán, en el
directorio en curso, los ficheros antes mencionados.
Estos ficheros se deberán copiar en el directorio que los programas ejecutables vean como
directorio en curso.
Los ficheros “tpvxxx” se deberán copiar o mover al directorio donde la configuración del
servidor web indique que deben ir los ejecutables (/cgi-bin, ...) o en un subdirectorio de éste
(p. ej. /cgi-bin/tpv). El fichero o ficheros “codigocomercio.cfg” deberán residir en el
directorio que los programas ejecutables vean como directorio en curso. Los ficheros
“firmxxx” deben situarse en el mismo directorio que los “tpvxxx”.
En determinados servidores WEB, los programas ejecutables no se reconocen por estar
situados en el directorio /cgi-bin, sino porque tienen un nombre especial (por ejemplo, todos
acaban en “.cgi”. Si este es el caso, se debe cambiar el nombre al fichero tpvxxx y llamarle de
acuerdo a como deban llamarse los ejecutables para ese servidor (por ejemplo: tpvsolar.cgi).
Se recomienda consultar con el administrador del sitio Web acerca de cómo debe llamarse o
dónde situar el programa ejecutable del TPV virtual.
El fichero o ficheros “codigocomercio.cfg” contiene datos de configuración del programa
“tpvxxx” para un comercio en particular. Cada vez que el “tpvxxx” es ejecutado accede al
fichero de configuración del comercio contra el cual se esté realizando la transacción de pago.
Es necesario que este fichero no sea modificado, ya que esto implicaría que el programa
“tpvxxx” no funcionase.
El fichero “firmxxx” es un ejecutable que verifica la firma digital que acompaña a la
notificación opcional de los datos de la compra.
Instalación en Windows NT.
Al comerciante se le entregará (mediante disquete, correo electrónico u otros medios) un
fichero llamado “cgi_genera.tar”, que tendrá formato tar, y que contendrá en forma
empaquetada los ficheros “tpvwnt.exe”, “codigocomercio.cfg” y “firmnt.exe”.
Posteriormente se podrán agregar nuevos ficheros de configuración “codigocomercio.cfg”.
Para extraer estos ficheros (una vez que este “cgi_genera.tar” esté en el disco del sistema), se
ejecutará la aplicación “winzip” o similar, que permitirá extraer en el directorio que se desee
los ficheros antes mencionados.
El fichero “tpvwnt.exe” se deberá copiar o mover al directorio donde la configuración del
servidor web indique que deben ir los ejecutables (/cgi-bin, /scripts,...) o en un subdirectorio
de éste (p. ej. /cgi-bin/tpv). El fichero “codigocomercio.cfg” debe residir en el directorio que
Manual TPV virtual para el comerciante
11

los programas ejecutables vean como directorio en curso. El fichero “firmnt.exe” debe
situarse en el mismo directorio que “tpvwnt.exe”.
El fichero o ficheros “codigocomercio.cfg” contiene datos de configuración del programa
“tpvwnt.exe” para un comercio en particular. Cada vez que el “tpvwnt.exe” es ejecutado
accede al fichero de configuración del comercio contra el cual se esté realizando la
transacción de pago. Es necesario que este fichero no sea modificado, ya que esto implicaría
que el programa “tpvwnt.exe” no funcionase.
Si se quieren añadir más comercios al tpv, solamente es necesario añadir sus ficheros de
configuración “codigocomercio.cfg” al directorio que los programas ejecutables vean como
directorio en curso.
Instalación en un servidor Web con soporte para Servlets
Java.
Esta versión del TPV implementa el cliente de la Pasarela de Pagos de Unicaja (el módulo
que el comerciante debe instalar en su servidor) mediante un Servlet Java. De esta manera
cualquier comercio que disponga de un servidor Web Java con soporte para Servlets podrá
hacer uso del servicio TPV de Unicaja.
Al comercio se le entregará (mediante disquete, correo electrónico u otros medios) un fichero
llamado “cgi_genera.tar”, que tendrá formato tar, y que contendrá en forma empaquetada los
ficheros “ClienteTPV.jar”, “codigocomercio.cfg” y “entrust.jar”. Posteriormente se podrán
agregar nuevos ficheros de configuración “codigocomercio.cfg”.
Para extraer estos ficheros (una vez que este “cgi_genera.tar” esté en el disco del sistema), se
ejecutará la aplicación “winzip 9 ” o similar, que permitirá extraer en el directorio que se desee
los ficheros antes mencionados.
El fichero “ClienteTPV.jar” es el que contiene el servlet, llamado ServletTPV, y todas las
clases utilizadas por éste. Tanto el servlet como las clases auxiliares pertenecen al paquete
es.unicaja.tpv. El comercio deberá situar este fichero en el directorio que su servidor Web
tenga asignado para los servlets y configurar el mismo para que sepa como obtener la clase
“ServletTPV.class” del correspondiente paquete Java. No se debe descomprimir el fichero
ClienteTPV.jat
El fichero “entrust.jar” contiene un conjunto de clases Java que proporcionan los
mecanismos de encriptado necesarios para garantizar el intercambio de información con
Unicaja de forma robusta y segura. Es necesario que este archivo se coloque en un directorio
accesible por el motor de Servlets Java incluido en el servidor Web de su plataforma (añadir
su ubicación a la variable de entorno CLASSPATH del sistema o copiarlo al directorio de
librerias de extensión Java en el sistema (“…\jre\lib\ext” en Windows y “…/jre/lib/ext” en
Linux, por ejemplo)). No se debe descomprimir el fichero entrust.jar.
Manual TPV virtual para el comerciante
12

El fichero o ficheros “codigocomercio.cfg” contienen los datos de configuración de los
comercios y cada vez que el servlet es ejecutado accede a el fichero de configuración
correspondiente al comercio contra el que se realiza la transacción de pago. Es necesario que
estos ficheros no sean modificados, ya que esto implicaría que el servlet no funcionase.
El servlet acepta la propiedad de inicialización configFilePath, mediante la cual el
comerciante puede establecer el directorio donde el servlet debe buscar los ficheros de
configuración del comercio. Este camino también se le puede suministrar al servlet mediante
el atributo es.unicaja.tpv.configFilePath. En caso que el comerciante no suministre la
propiedad ni el atributo, el servlet buscará los ficheros de configuración de los comercios en
el directorio que el motor de servlets tenga configurado como su directorio de documentos.
Dentro del archivo ClienteTPV.jar que contiene al servlet y a sus clases auxiliares, hay una
clase es.unicaja.tpv.FirmaJava. Dicha clase permite verificar la firma digital que acompaña
a la notificación opcional de los datos de la compra 10 .Para ello dispone del siguiente método:
public static int checkFirma(String queryString,String confFilePath)
El primer parámetro, queryString, debe contener la lista de parámetros asociada a la
invocación de la URL de confirmación. El segundo parámetro, confFilePath, debe contener el
directorio donde está colocado el fichero de configuración del comercio codigocomercio.cfg.
Por ejemplo, si el camino al fichero de configuración es c:\dir1\subdir1\codigocomercio.cfg,
debe especificar como valor del parámetro confFilePath la cadena “c:\\dir1\\subdir1\\”.
El método devuelve el valor cero si la firma es válida. Si es distinto de cero, la firma no es
válida.
Herramientas para la gestión de la tienda virtual
El comercio, una vez que ha registrado su tienda virtual, se podrá conectar al servicio de
banca on-line UniVía. Dentro de este servicio podrá acceder, siguiendo los menús, al TPV
virtual asociado a su tienda.
Desde donde podrá realizar la Consulta de operaciones, mediante esta función, el
comerciante podrá ver los detalles de los pagos efectuados y abonados en su cuenta
correspondientes a compras realizadas en su tienda virtual.
Manual TPV virtual para el comerciante
13