Manual TPVM 1.4

7/23/2019 Manual TPVM 1.4

1/16

Direccin de Informtica

rea de DesarrolloMedios de Pago y Banca Electrnica

Manual del Comerciante para el Uso de laPasarela de Pagos de Unicaja TPV/M


2/16

Medios de Pago y Banca ElectrnicaPasarela de Pagos de Unicaja TPV/M

2 de 14

NOMBRE DEL DOCUMENTO

Manual TPV para el comerciante.doc

HISTORIAL DE CAMBIOS

FECHA VERSIN CAMBIOS PRODUCIDOS

17/02/2009 1.0 Primera versin16/11/2009 1.1 Pequeas correcciones

Confidencialidad

Este documento es de uso estrictamente confidencial. Su contenido es reservado yqueda prohibida su divulgacin, copia o distribucin a terceros sin la previaautorizacin escrita de Unicaja.

Febrero 2011 1.2 Pequeas actualizaciones

Mayo2012 1.3 Pequeas actualizaciones

Junio2012 1.4 Logo del comercio en pginas del TPV


3/16


3 de 14

ndice

Funcionamiento de la Pasarela de Pagos ............................................................ 5

Datos a aportar por el Comercio ....................................................................... 14

Herramientas para la Gestin de la Tienda Virtual............................................ 14

Anexo 1 ....................................................................................................... 15

Anexo 2 ....................................................................................................... 16


4/16

Medios de Pago y Banca Electrnica

Pasarela de Pagos de Unicaja TPV/M

4 de 14

Introduccin

En este documento se explica cmo utilizar la Pasarela de Pagos de Unicaja TPV/M

por parte del comerciante.La Pasarela de Pagos, tambin llamada TPV virtual, es un programa informticoque permite la realizacin de pagos a travs de Internet dentro de un entorno decomercio electrnico.

Para poder disfrutar del TPV virtual es preciso que previamente el comerciantedisponga de un sitio web con una aplicacin de comercio electrnico, es decir, confunciones de seleccin de productos de un catlogo, totalizacin de elementos aadquirir, etc. Ser a la hora de que el cliente desee realizar el pago con cargo auna tarjeta cuando entre el funcionamiento el TPV virtual.

El TPV virtual realiza las mismas funciones que un TPV real de los que se utilizannormalmente en las tiendas: permite solicitar autorizacin de pago contra unatarjeta y abonar el importe en la cuenta que el comercio debe tener en Unicajacomo entidad adquiriente.

El TPV incluye los mecanismos de seguridad necesarios para que tanto elcomerciante como el cliente puedan tener confianza en el entorno comercial sobreinternet. El cliente puede confiar en que sus datos de tarjeta de pago slo sernconocidos por Unicaja y los artculos adquiridos slo conocidos por el comerciante.

La Pasarela de Pagos de Unicaja TPV/M es totalmente independiente de laplataforma tecnolgica, ya que no necesita instalar componente alguno en el

servidor del comercio. Como contrapartida, el comercio tiene que soportar unsencillo interfaz de mensajera, que requiere de un pequeo desarrollo.


5/16


5 de 14

Funcionamiento de la Pasarela de Pagos

Una vez que el cliente del comercio virtual ha efectuado la seleccin de susartculos, ser invitado a realizar el pago. En la pgina web del comercio desde laque se comience la operacin de pago con tarjeta, existir un botn rotuladotpicamente PAGO CON TARJETA .

Este botn deber llamar al servidor de Unicaja mediante la URL https://www.unicaja.es/cgi-bin/tpv/ServletTPVM, pasndole los parmetros que sedescriben a continuacin, por mtodo POST (Ver Anexo 1.1):

Parmetro Descripcin Sintaxis Longitudtienda Identificador del

comercio, que es asignadopor Unicaja en el

momento de formalizar elcontrato

Caracteres alfanumricosASCII 9

referencia Referencia de la compra,valor creado por elsoftware de comercioelectrnico delcomerciante


fecha Fecha de la compra. Caracteres alfanumricosASCII en formato fecha:

dd/mm/aaaa

10

Resumen de la compra

Referencia: A23J2456

Importe: 13.200 PTAI.V.A. 2.112 PTAPortes: 700 PTATOTAL: 16.012 PTA

Pago con tarjeta

Mi Tien da On Line


6/16


6 de 14

Es necesario que se respete el nombre de los parmetros, reflejados en la primeracolumna de la tabla anterior, as como no sobrepasar la longitud mxima de stosparmetros.

El TPV/M de Unicaja, para obtener el resto de la informacin que hace falta para elpago, llamar a un programa residente en el servidor del comercio, y desarrolladopor el mismo, cuya URL habr sido aportada por el comercio en el momento dedarse de alta en el servicio (UrlVerificacin).

Es recomendable, aunque no obligatorio, que la UrlVerificacin sea segura (https),ya que si la conexin con el comercio se realiza mediante SSL, el TPV verifica elcertificado digitalpresentado por el servidor del comercio, autenticndolo as.

El servidor de Unicaja realiza la llamada a la URL de verificacin de comerciopor mtodo GET con los siguientes parmetros:

Parmetro Descripcin Sintaxis Longitudreferencia Referencia de la compra,

valor creado por elsoftware de comercioelectrnico delcomerciante y recibido enla llamada inicial quehace el comercio aUnicaja


fecha Fecha de la compra. Formato dd/mm/aaaa 10

El programa residente en el servidor del comercio deber devolver una cadena deparmetros con el siguiente formato (Ver Anexo 1.2):

Los parmetros a incluir en la cadena son:

Parmetro Descripcin Sintaxis Longitudtienda Identificador de la tienda

o comercio, que esasignado por Unicaja en elmomento de formalizar elcontrato

Caracteres ASCII9

referencia Referencia de la compra,valor creado por elsoftware de comercio

electrnico delcomerciante


nombre del parmetro1=valor1&nombre del parmetro2=valor2&.....


7/16



7 de 14

importe Importe de la compra (cono sin decimales)

Dgitos numricos ASCII.En caso de llevardecimales, la coma ser

el carcter ASCII , alque le seguirn unmximo de dos dgitosdecimales

18

divisa Divisa de la compra EUR en ASCII 3fecha Fecha de la operacin Formato dd/mm/aaaa 10idioma Idioma (opcional) Cdigo de dos letras

minsculas ASCIIrepresentando el idioma,de acuerdo con la normaISO 639. Los valorespermitidos son:es para espaol,de para alemn yen para ingls

2

urlOK

URL OK para este pago(opcional).

Lo puede usar el comerciosi necesita indicar una

URL OK adaptada a losrequisitos concretos delpago en curso. Si no seindica se emplear la quese tenga como parte delos datos del comercio.Vase el apartado Datosa aportar por elComercio para msdetalles.

Una URL completamenteespecificada con

protocolo,nombre o IP de lamquina, puerto,ruta de archivo,identificador. desesin, parmetros.

256


8/16


8 de 14

urlKO

URL KO para este pago(opcional).

Lo puede usar el comerciosi necesita indicar unaURL KO adaptada a losrequisitos concretos delpago en curso. Si no seindica se emplear la quese tenga como parte delos datos del comercio.Vase el apartado Datosa aportar por elComercio para ms

detalles.

Una URL completamenteespecificada conprotocolo,nombre o IP de lamquina, puerto,ruta de archivo,identificador. desesin, parmetros.

256

Una vez que el servicio TPV de Unicaja conoce todos los datos procedentes delservidor del comercio, ste presentar una pgina al cliente donde se le pedir losdatos necesarios de su tarjeta para realizar el pago. En esta pgina incluir el logodel comercio si ste ha sido aportado en el alta del servicio1.

1Vase apartado de Datos a aportar por el Comercio.


9/16


9 de 14

Una vez el cliente ha introducidos los datos de su tarjeta, se presenta otra pginapara que confirme el pago.

El comprador, a continuacin, ver en su pantalla el resultado de la operacin depago, junto con la invitacin a imprimir la pgina como justificante de latransaccin.


10/16


10 de 14

Cuando el cliente pinche CONTINUAR se mostrar una pgina que ser elegidapor el comerciante (Urlok)1 y residente en su tienda virtual, tpicamente comoagradecimiento de la compra o para confirmar el plazo de entrega de los bienes oservicios.

Si el pago no se pudiera llegar a realizar, el comprador ver otra pgina donde se

indica el motivo del rechazo. En este caso, cuando el cliente pinche sobreCONTINUAR, se mostrar la pgina, tambin elegida por el comerciante yresidente en la tienda virtual, con el mensaje que el comerciante estime dar anteesta situacin (Urlko)2.

1Vase apartado de Datos a aportar por el Comercio.2Vase apartado de Datos a aportar por el Comercio.

Muchas gracias por su visita

En 48 horas recibir supedido en su domicilio

Mi Tie n da On Lin e


11/16



11 de 14

Cuando se realiza el pago, si el comerciante desea ser informado3automticamente del resultado de la operacin de pago, la Pasarela llamar alprograma que el comerciante haya especificado en la direccin Urlconf4, a travs

de mtodo GET, con los siguientes parmetros:

Parmetro Descripcin Sintaxis Longitud(mx)

tienda Identificador de la tiendao comercio, que esasignado por Unicaja en elmomento de formalizar elcontrato

Caracteres ASCII9

referencia Referencia de la compra,

valor creado por elsoftware de comercioelectrnico delcomerciante

Caracteres alfanumricos

ASCII 10

autorizacion Nmero de autorizacin Caracteres numricosASCII

6

secuencia Nmero de secuenciaasignada a la transaccinpor Unicaja

Caracteres numricosASCII

5

3La notificacin del resultado de la operacin al comerciante es opcional.4Vase apartado de Datos a Aportar por el Comercio


12/16


12 de 14

importe Importe de la compra (cono sin decimales)

Dgitos numricos ASCII.En caso de llevar

decimales, la coma ser

el carcter ASCII , alque le seguirn un

mximo de dos dgitosdecimales

18

icontravalor Importe de la compra enpesetas (opcional)

Dgitos numricos ASCII.En caso de llevar

decimales, la coma serel carcter ASCII , al

que le seguirn unmximo de dos dgitos

decimales

18

divisa Divisa de la compra Nemnico EUR en ASCII 3dcontravalor

Divisa del contravalor(opcional)

Nemnico ESP en ASCII 3

fecha Fecha de la operacin Formato dd/mm/aaaa 10seguro Indicador de pago seguro

(Slo si el comercio tieneactivo el pago seguro).

Nemnico 3DSECUREen ASCII.

8

cadTar Fecha de caducidad de latarjeta (Solo para loscomercios que lo

requieran y estnautorizados )

Formato mm/aaaa 7

numTar Cuatro ltimos dgitos dela tarjeta(el resto escapado con *)(Solo para los comerciosque lo requieran y estnautorizados )

Formato ************nnnn 12

firma*Ver Anexo 2

Firma de la respuesta deUnicaja.5

32 dgitos enhexadecimal del MD5 dela cadena de parmetros

enviados ms la clavecompartida que Unicajaproporcionar alcomercio.

32

5El comerciante puede usar la firma para certificar la validez de la respuesta.


13/16


13 de 14

En el caso de que el pago no termine correctamente, el comerciante tambinpodr conocer este hecho si ha elegido que se le notifique la operacin mediante elparmetro Urlconf. Si se da esta circunstancia, se llamar a Urlconf con lossiguientes parmetros:

Parmetro Descripcin Sintaxis Longitud(mx)

tienda Identificador de la tiendao comercio, que esasignado por Unicaja en elmomento de formalizar elcontrato

Caracteres ASCII9

referencia Referencia de la compra,valor creado por elsoftware de comercioelectrnico delcomerciante


error Descripcin del error Caracteres alfanumricosASCII

80

seguro Indicador de pago seguro(Slo si el comercio tieneactivo el pago seguro).

Los nemnicos3DSECURE SPA en

ASCII.

8

firma

*Ver Anexo 2

Firma de la respuesta de

Unicaja.6

32 dgitos en

hexadecimal del MD5 dela cadena de parmetrosenviados ms la clavecompartida que Unicajaproporcionar alcomercio.

32

6El comerciante puede usar la firma para certificar la validez de la respuesta.


14/16


14 de 14

Datos a aportar por el Comercio

En el momento de registrar una tienda virtual en Unicaja, el comerciante deberproporcionar una serie de direcciones a travs de las cuales la pasarela de pagos secomunicar con el comercio virtual.

Estas direcciones son las siguientes:

URL Descripcin

Urlok URL del comercio que se mostrar si la operacin decompra ha terminado correctamente.Se pueden proporcionar varias, una para cada idiomaque se pretenda usar en la web del cliente.

Urlko URL del comercio que se mostrar si la operacin decompra NO se ha podido realizar.Se pueden proporcionar varias, una para cada idiomaque se pretenda usar en la web del cliente.

Urlconf URL del comercio a la que se acceder si elcomerciante quiere que se le notifiquenautomticamente los datos de la compra. Esteparmetro es opcional. Si no existe, el comerciante

no ser notificado del resultado de las operaciones,pero, en cualquier caso, podr consultarlas a travsdel servicio UniVa.

UrlVerificacion* Ver Anexo1.1

URL del comercio a la que la Pasarela de Pagos deUnicaja invoca cada vez que un cliente comienza unatransaccin de pago para obtener toda la informacinque le hace falta sobre la compra que se va a

Herramientas para la Gestin de la Tienda Virtual

El comerciante, a travs de la banca electrnica de Unicaja, Univia(www.unicaja.es), tiene a su disposicin una serie de consultas que lepermitira gestionar y conocer informacin adicional de las operacionesrealizadas a travs de su TPV virtual.

Logo Logo del comercio. Altura mxima de la imagen250pxeles ypeso mximo 256k. Las extensiones

vlidas son GIF,JPG,JPEGyPNGEste d to es opcion l. Si se proporcion se

mostr r

en l s pgin s del TPV de Unic j .


15/16

Medios de Pago y Banca ElectrnicaPasarela de Pagos de Unicaja TPV/MMedios de Pago y Banca Electrnica


ANEXO 1

1.2 Script bsico de ejemplo en php del uso de la url de verificacin, la cual debe

solamente devolver texto plano con la cadena de parmetros completa.

Le recomendamos que para las pruebas iniciales de conexin, utilice ejemplos bsicospara minimizar los posibles errores antes de integrarlo en su web.

1.1 En la llamada inical utilice por ejemplo un fichero en php que pueda invocarsedesde el navegador

tienda
referencia
fecha


16/16


ANEXO 2

Firma en TPV/M - Opcional

La cadena de parmetros que hay que pasarle al MD5 es la respuesta que enviamosnosotros a la url de confirmacin, esto es, todos los parmetros (incluidos los &)excepto el de firma y concatenando al final de la cadena la clave compartida

Por ejemplo, si usa variables, podra ser algo as:

$firma_digital =md5("tienda=".$_REQUEST['tienda']."&referencia=".$_REQUEST .......

para despus hacer la comparacin con el parmetro firma. La cadena sobre la quetiene que calcular el md5 debera ser por ejemplo algo tal que:

tienda=130123123&referencia=000000000&autorizacion=574465&secuencia=00002&importe=0%2C15&icontravalor=25&divisa=EUR&dcontravalor=ESP&fecha=12%2F04%2F2010&seguro=3DSECURECLAVECOMPARTIDA

Sustituyendo la palabra CLAVECOMPARTIDA por la clave compartida correspondiente

Manual TPVM 1.4

Documents

Transcript of Manual TPVM 1.4