IntegracionTpvpcImplantado

Integracion TpvpcImplantado Versión: 2.27 28/08/2014

Referencia SM.DE.DNC.MAN.0046

Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA

Ref SM.DE.DNC.MAN.0046 Versión: 2.27

28/08/2014 i

Integracion TpvpcImplantado

La propiedad intelectual de este documento pertenece a Redsys. Queda prohibida su reproducción, venta, o cesión a terceros

Autorizaciones y control de versión

AUTOR: Redsys

VALIDADO POR:

APROBADO POR:

EMPRESA: Redsys

EMPRESA: Redsys

EMPRESA: Redsys

Firma:

Firma:

Firma:

Fecha: 01/04/2011

Fecha: 01/04/2011

Fecha: 01/04/2011

Comentarios: La gestión de la documentación impresa es responsabilidad de la persona que la imprime. Las versiones impresas de los documentos no garantizan ser la última versión aprobada. Para consultar la última versión acceder a la base de datos de Alejandría.

Versión

Fecha

Afecta

Breve descripción del cambio

2.8

12/02/10

Documentación

Se actualiza el formato del documento.

2.9

12/05/10

Documentación

Se añade un la ruta de un ejemplo de Integración en Visual Basic .Net

2.10

12/05/10

Documentación

Arreglados errores en sección consultas

2.11

29/09/10

Documentación

Agregados errores AX-TPVPCXXXX del componente ActiveX de comunicación con PinPad.

2.12

18/10/10

Documentación

Se elimina la operativa PAN en claro antes de transacción.

2.13

25/11/10

Documentación

Se añade la operativa de devoluciones con lectura.

2.14

01/12/10

Documentación

Actualización de códigos de denegación

2.15

28/12/10

Documentación

Actualización de códigos de error de operación

2.16

04/02/11

Documentación

Integración versión Linux

2.17

16/02/11

Documentación

Integración versión JAVA

2.18

01/03/11

Documentación

Se especifica que la devolución con tarjeta no es válida para Windows Mobile



28/08/2014 ii



Se añaden varios códigos de error para las diferentes funciones.

2.19

10/03/11

Anexo III

2.20

24/05/11

Documentación

Se añade la operativa de repeticiones de pagos con tarjeta en archivo. Nueva plantilla de documentación.

2.21

12/12/11

Documentación

Se añade la operativa de reemplazo de preautorizaciones en el interfaz ActiveX.

2.22

19/04/12

Documentación

Se actualizan las etiquetas del mensaje DCC. Se actualizan referencias a REDSYS.

2.23

6/6/12

Documentación

Adaptación imágenes Redsys

2.24

27/7/12

Documentación

Inclusión de operativa contactless Inclusión de recibos de operaciones AMEX, identificación e información añadida.

2.25

13/06/14

Documentación

2.26

23/06/14

Documentación

Recibos de Devolucines y Devoluciones sin original

2.27

28/08/14

Documentación

Actualizado listado de marcas con CUP

Actualización de información en recibos Contactless.



28/08/2014 iii



ÍNDICE DE CONTENIDO

1.

Introducción ........................................................................................ 1

2.

Destinatarios ........................................................................................ 1

3.

Integración TpvpcImplantado .............................................................. 2

3.1

Iniciar Comunicación en Modo Transparente .......................................... 3

3.2

Iniciar Comunicación en Modo Interfaz de Usuario .................................. 4

3.3

Detener la Comunicación .................................................................... 5

3.4

Realizar un Pago o una Preautorización utilizando un dispositivo PinPad .... 6

3.5

Realizar un Pago o Preautorización introduciendo manualmente los datos de la tarjeta ....................................................................................... 7

3.6

¿Cómo validar si la operación resultó AUTORIZADA? ..............................10

3.7

Realizar una operación de Confirmación o Devolución ............................11

3.8

¿Cómo realizar una Devolución/Confirmación desde otro terminal? ..........13

3.9

Realizar una operación de Devolución con lectura desde el Pinpad ...........14

3.10 ¿Cómo validar si la operación resultó AUTORIZADA? ..............................16 3.11 Realizar una operación de Devolución sin Original ..................................16 3.12 Realizar una operación de Devolución sin Original introduciendo manualmente los datos de la tarjeta ....................................................18 3.13 ¿Cómo validar si la operación resultó AUTORIZADA? ..............................19 3.14 Realizar consultas de Operaciones .......................................................20 3.15 Realizar Consulta de Totales ...............................................................23 3.16 Realizar Operación DCC ......................................................................25 3.17 Realizar Operación DCC con Entrada Manual de Datos ............................27 3.18 Ejemplo de Operación DCC .................................................................28 3.19 Realizar una repetición de pago con tarjeta en archivo ...........................32 4.

ANEXO I. Integración ActiveX ............................................................ 34

5.

ANEXO II. Integración Windows Mobile (Pocket PC) ......................... 37

6.

ANEXO III. Errores devueltos............................................................. 39

7.

ANEXO IV. Versiones Librería ............................................................. 45

7.1

¿Cuándo debe realizarse una actualización de esta Librería? ...................45



28/08/2014 iv


8.

ANEXO V. Diccionario de Datos .......................................................... 47

9.

ANEXO VI. Códigos Error TPVPC ......................................................... 51


10. ANEXO VII. Códigos de Denegación ................................................... 58 11. ANEXO VIII. Ejemplos Impresión de Recibos .................................... 60 11.1 Recibo para una operación realizada con Lectura de Banda o Entrada Manual de Datos ...............................................................................60 11.2 Recibo para una operación realizada con una Tarjeta con Chip EMV .........61 11.3 Recibo para una operación realizada con una Tarjeta DCC ......................62 11.4 Ejemplo de Recibo de una operación en la que se recibe el elemento .........................................................................63 11.5 Ejemplo de Recibo cuando se recibe elemento ........64 11.6 Ejemplo de Recibo cuando se recibe elemento ..........65 11.7 Ejemplo de Recibo cuando Deniega Tarjeta EMV ....................................67 11.8 Ejemplo de Recibo cuando se realiza una operación con tarjeta AMEX ......69 11.9 Ejemplo de recibo de una devolución ...................................................71 11.10 Ejemplo de recibo de devolución sin original .........................................72 12. ANEXO IX. Al llamar a la función de Pago, Preautorización, Confirmación o Devolución nos devuelve el código -2 ........................ 74 13. ANEXO X. Operativas Adicionales ....................................................... 76 13.1 Operativa DCC realizadas directamente en PinPad. ................................76 13.2 Inhibición de recibo. ..........................................................................78 13.3 Ejemplo de Integración ActiveX desde página HTML ...............................79 13.4 Ejemplo de Integración de Librería .dll desde Aplicación en C#................79 13.5 Ejemplo de Integración de ActiveX desde Aplicación Visual Basic 6.0 .......79 13.6 Ejemplo de Integración de ActiveX desde Aplicación Visual Basic .NET (2005) .............................................................................................79 13.7 Ejemplo de Integración de ActiveX desde Aplicación PowerBuilder 11 .......80 13.8 Ejemplo de Integración de Librería desde C# para Windows Mobile (Pocket Pc) .......................................................................................80 13.9 Ejemplo de Integración de ActiveX desde Aplicación Java .......................80 13.10 Ejemplo de Integración de Librería en Visual C++ 6.0 ............................81 14. ANEXO XI. Tratamiento Firma Digitalizada ......................................... 82 15. ANEXO XII. Tratamiento PIN.............................................................. 85



28/08/2014 v


16. ANEXO XIII. Integración Librería nativa C++ Linux ........................... 87 16.1 Requisitos mínimos de uso de la librería C++ Linux ...............................87


16.2 Integración entorno Linux ...................................................................87 16.3 Ejemplo de Integración de Librería en Linux: Librería dinámica ...............90 17. ANEXO XIV. Integración Librería JAVA ............................................... 92 17.1 Requisitos mínimos de la librería JAVA .................................................92 17.2 Desarrollo .........................................................................................92 17.3 Ejecución ..........................................................................................92



28/08/2014 vi


1.

Introducción Este documento describe la integración de aplicaciones propietarias usadas en comercios, con TpvpcImplantado. Para facilitar la integración de las distintas aplicaciones, se suministra una librería dinámica (DLL) que es compatible con prácticamente el 100% de los entornos de desarrollos utilizados en sistemas operativos Microsoft Windows. La librería puede utilizarse en dos Modos:

•

•

Modo Interfaz de Usuario / Latente, en este modo, toda intervención o mensajes que se deban mostrar al Titular de la Tarjeta, lo realizará la propia aplicación TpvpcImplantado. La aplicación del comercio, sólo recibirá el xml con el resultado de la operación. Modo Transparente, la aplicación del comercio será la encarga de mostrar todos los mensajes necesarios al comercio, la aplicación o librería TpvpcImplantado no mostrará ningún mensaje.

La aplicación TpvpcImplantado cuando se inicia en Modo Latente, recibe las peticiones utilizando un puerto de comunicación local (socket), con lo que si el equipo dispone de Antivirus o algún programa de control, se deberá permitir a la aplicación TpvpcImplantado, actuar como servidor. Esta configuración solo se ha de tener en cuenta cuando se inicie la librería en modo Latente.

Esta librería se irá actualizando en función de los nuevos requerimientos o funcionalidades. Se enviarán notificaciones de estas actualizaciones a la dirección de correo electrónica indicada en la solicitud de alta. Si el sistema detecta que se está usando una versión antigua, también lo informará con un campo especifico en las respuestas, en el Anexo II se indica esta información.

2.

Destinatarios Este documento está destinado a: • •

COMERCIOS ENTIDADES



28/08/2014 1


3.

Integración TpvpcImplantado A continuación se describen todas las funciones exportadas por la librería y un ejemplo de acceso a estas funciones en el lenguaje C# .NET. Antes de poder realizar cualquier operación, es necesario inicializar la comunicación con TpvpcImplantado, para ello existen dos modos: 1. Modo Transparente, la aplicación del comercio se encargará de interactuar con el usuario. 2. Modo Interfaz de Usuario, la aplicación del comercio pasará los datos a la aplicación TpvpcImplantado, y esta se encargará de interactuar con el usuario.

La operación de inicialización, sólo se debe realizar cada vez que se inicie la aplicación, una vez inicializada, ya no es necesario realizar este proceso. En las siguientes URLs se pueden obtener las últimas versiones del TpvpcImplantado, y la librería de integración, para aplicaciones propietarias: Entorno de Real: http://sis-d.sermepa.es/TPV_PC/implantado.html

Entorno de Pruebas: http://sas-d.sermepa.es/TPV_PC/implantado.html

Muy importante, aclarar que la versión de librería del entorno de pruebas sólo es válida para este entorno, una vez realizadas las pruebas en el entorno de pruebas, se debe utilizar y distribuir en el caso de que fuese necesario, la versión descargada desde la URL indicada en “Entorno de Real”.



28/08/2014 2


3.1

Iniciar Comunicación en Modo Transparente Parámetros de entrada/salida: cComercio, número de comercio. Este dato es facilitado por la entidad. cTerminal, número de terminal. Este dato es facilitado por la entidad. cClaveFirma, clave de firma del comercio. Este dato es facilitado por la entidad. cConfPuerto, parámetro opcional que indica la configuración de puerto. A partir de la versión 1.0.4.0, este parámetro no debe indicarse, se recuperará la configuración establecida en el TPVPC. Para PinPad conectados a puerto serie: COM:,19200,N,8,1 Para PinPad conectados a puerto USB, se define dependiendo del modelo: • •

Modelo i6280, se debe utilizar la cadena USB,2816,25216,2,2. Modelo i6550, se debe utilizar la cadena USB,2816,25936,2,2.

cVersion, parámetro opcional que indica la versión de protocolo a utilizar. A partir de la versión 1.0.4.0, este parámetro no debe indicarse, se recuperará la configuración establecida en el TPVPC. Valores posibles “3.0”, “3.1”, “4.0”, “4.1” o “4.2”. Esta versión varía en función de la versión de software del modelo de pinpad. La versión actual es la versión “4.1”.

Valor devuelto: 0, se inició correctamente la aplicación. Distinto de 0, indica un error en la operación. En el Anexo I, se describen los errores devueltos por todas las funciones.

int fnDllIniTpvpcLatente(LPCTSTR cComercio, LPCTSTR cTerminal, LPCTSTR cClaveFirma, LPCTSTR cConfPuerto, LPCTSTR cVersion);

Ejemplo de llamada en C# .NET:

[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllIniTpvpcLatente(String cComercio, String cTerminal, String cClaveFirma, String cConfPuerto, String cVersion);



28/08/2014 3


Ejemplo de llamada en Visual Basic .NET Public Declare Function fnDllIniTpvpcLatente Lib "dllTpvpcLatente.dll" (ByVal cComercio As String, ByVal cTerminal As String, ByVal cClaveFirma As String, ByVal cConfPuerto As String, ByVal cVersion As String) As Integer

3.2

Iniciar Comunicación en Modo Interfaz de Usuario Parámetros de entrada/salida:

cUsr, nombre o identificador de usuario. Este dato es facilitado por la entidad. cClave, clave de acceso del usuario. Este dato es facilitado por la entidad. cModo, indica el TpvpcImplantado.

modo

en

el

que

se

inicializará

la

aplicación

“1” -> Modo Interfaz de Usuario.

int fnDllIniTpvpcLatenteExt(LPCTSTR LPCTSTR cModo);

cUsr,

LPCTSTR

cClave,


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllIniTpvpcLatenteExt(String cUsuario, String cClave, String cModo);

Ejemplo de llamada en Visual Basic .NET

Public Declare Function fnDllIniTpvpcLatenteExt Lib "dllTpvpcLatente.dll" (ByVal cUsuario As String, ByVal cClave As String, ByVal cModo As String) As Integer



28/08/2014 4


Una vez inicializada la aplicación en cualquiera de sus modos, ya se pueden realizar cualquiera de las operaciones ofrecidas por la librería. Muy importante, recordar que esta función sólo es necesario llamarla la primera vez que se inicie la aplicación, o cuando se quiera cambiar los datos de comercio o usuario.

3.3

Detener la Comunicación No tiene parámetros de entrada. Fuerza la parada de TPVPC Latente. No devuelve errores.

int fnDllParaTpvpcLatente();


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllParaTpvpcLatente();


Public Declare Function fnDllParaTpvpcLatente "dllTpvpcLatente.dll" () As Integer

Lib



28/08/2014 5


3.4

Realizar un Pago o una Preautorización utilizando un dispositivo PinPad Parámetros de entrada/salida:

cImporte, importe de la transacción en formato XXXXXXXXX.XX. Ejemplo: 1.23, 33.05, 0.01, etc. cFactura, referencia de compra. Este valor lo puede especificar el comercio para ayudarle a identificar la transacción. cTipoOper, indica el tipo de operación a realizar. Valores posibles: “PAGO” -> Se realizará un Pago. “PREAUTORIZACION” -> Se realizará una preautorización. “PAGO_TJT_ARCHIVO” -> Se realizará un pago inicial con tarjeta en archivo. Sólo para aquellos comercios que tengan contratado este servicio con su entidad. cXMLResp, buffer, que almacenará una cadena XML con el resultado de la operación de pago o preautorización. El formato de este XML se encuentra detallado en la documentación "Conexión con TPVPC a través de WEB SERVICE" versión 6.0. iTamMaxResp, indica el tamaño máximo del buffer donde se almacenará la cadena XML con el resultado de la operación. Se recomienda al menos un tamaño de 1024 bytes.

Valor de retorno: Valor 0, indica que la operación se ha procesado correctamente. Muy importante resaltar que este resultado NO INDICA QUE LA OPERACIÓN ESTË AUTORIZADA, tan sólo es el resultado de su proceso. Valor distinto de 0, Código de error indicando el motivo del fallo. En el Anexo III, se detallan estos errores. Siempre que se devuelva el código -2, es necesario realizar una consulta de la última operación realizada por el comercio, para ver si la operación resultó autorizada.

int fnDllOperPinPad(LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp);



28/08/2014 6



[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperPinPad(String cImporte, String cFactura, String cTipoOper, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllOperPinPad Lib "dllTpvpcLatente.dll" (ByVal cImporte As String, ByVal cFActura As String, ByVal cTipoOper As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer

3.5

Realizar un Pago o Preautorización introduciendo manualmente los datos de la tarjeta Dependiendo del Modo elegido, se dispone de dos métodos distintos. Si se eligió el Modo Transparente, la aplicación del comercio deberá solicitar y validar los datos de la tarjeta.

Modo Transparente: Parámetros de entrada/salida:

cTarjeta, número de tarjeta. Las tarjetas tienen una longitud entre 15 y 19 caracteres. Campo Opcional en Modo Usuario, si no se pasa lo pedirá el TpvpcImplantado. cCaducidad, cadena con la caducidad de la tarjeta. El formato es AAMM. Ejemplo 06/13, el formato sería 1306. Campo Opcional en Modo Usuario, si no se pasa lo pedirá el TpvpcImplantado. cCVC2, cadena con el valor de CVC2. Código de tres dígitos de seguridad que viene impreso generalmente en el reverso de la tarjeta, y que será necesario dependiendo de la actividad del comercio. Campo Opcional en Modo Usuario, si no se pasa lo pedirá el TpvpcImplantado. cImporte, importe de la transacción en formato XXXXXXXXX.XX. Ejemplo: 1.23, 33.05, 0.01, etc. cFactura, referencia de compra. Este valor lo puede especificar el comercio para ayudarle a identificar la transacción. Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 7


cTipoOper, indica el tipo de operación a realizar. Valores posibles: “PAGO” -> Se realizará un Pago. “PREAUTORIZACION” -> Se realizará una preautorización. “PAGO_TJT_ARCHIVO” -> Se realizará un pago inicial con tarjeta en archivo. Sólo para aquellos comercios que tengan contratado este servicio con su entidad. cXMLResp, buffer que almacenará una cadena XML con el resultado de la operación de pago o preautorización. El formato de este XML se encuentra detallado en la documentación "Conexión con TPVPC a través de WEB SERVICE" versión 6.0. iTamMaxResp, indica el tamaño máximo del buffer donde se almacenará la cadena xml con el resultado de la operación. Se recomienda al menos un tamaño de 1024 bytes.

Valor de retorno: Valor 0, indica que la operación se ha procesado correctamente. Muy importante indicar que este resultado NO INDICA QUE LA OPERACIÓN ESTÉ AUTORIZADA, tan sólo es el resultado de su proceso. Valor distinto de 0, Código de error indicando el motivo del fallo. En el Anexo III, se detallan estos errores. Siempre que se devuelva el código -2, es necesario realizar una consulta de la última operación realizada por el comercio, para ver si la operación resultó autorizada.

int fnDllOperManualExt(LPCTSTR cTarjeta, LPCTSTR cCaducidad, LPCTSTR cCVC2, LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperManualExt(String cTarjeta, String cCaducidad, String cCVC2, String cImporte, String cFactura, String cTipoOper, StringBuilder cXMLResp, int iTamMaxResp);

Ejemplo de llamada en Visual Basic .NET Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 8


Public Declare Function fnDllOperManualExt Lib "dllTpvpcLatente.dll" (ByVal cTarjeta As String, ByVal cCaducidad As String, ByVal cCVC2 As String, ByVal cImporte As String, ByVal cFActura As String, ByVal cTipoOper As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer

Modo Interfaz de Usuario:

Esta función recibe los mismos parámetros de entrada que la función fnDllOperPinPad.

int fnDllOperManual(LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperManual(String cImporte, String cFactura, String cTipoOper, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllOperManual Lib "dllTpvpcLatente.dll" (ByVal cImporte As String, ByVal cFActura As String, ByVal cTipoOper As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer



28/08/2014 9


3.6

¿Cómo validar si la operación resultó AUTORIZADA? En la cadena con el resultado de operación, siempre deben aparecer los siguientes elementos con el valor que se indica a continuación: F Autorizada

Si la respuesta no contiene estos valores, debe tomarse como una transacción DENEGADA Ejemplo de cadena con el resultado de la operación de PAGO o PREAUTORIZACION:

PAGO 1.01 978 ************0018 ************0018 2 1210 777888991 1 10549 DEB 070001070319153828378272 FAC-LATENTE 2007-03-19 15:38:28.484 F Autorizada 080922 NO REFUND 664AD45F54C3EB4D06A354E3158A17966012A1B8 true 001391 00 A0000000043060 00 0800208000

Como se puede observar en el ejemplo, la transacción resultó AUTORIZADA, ya que aparecen los campos estado con valor F, y resultado con el literal Autorizada. Cualquier otro valor, debe tomarse como una transacción Denegada.



28/08/2014 10


3.7

Realizar una operación de Confirmación o Devolución Una confirmación se realiza siempre preautorización realizadas con anterioridad.

sobre

operaciones

de

Una devolución, como su propio nombre indica, realiza el abono o devolución del importe indicado, a la tarjeta con la que se realizó la operación original.

Parámetros de Entrada:

cNumPedido, número de pedido de la operación original. El campo pedido se encuentra en todas las respuestas de peticiones de operaciones realizadas al TPVPC. Valor obligatorio en Modo Transparente. cRTSOriginal, identificador RTS de la transacción original. El campo identificadorRTS se encuentra en todas las respuestas de peticiones de operaciones realizadas al TPVPC. Valor Opcional, en cualquiera de los modos. En modo Transparente se recomienda su uso. cImporte, importe que se quiere devolver o confirmar, en formato XXXXXXXXX.XX. Ejemplo: 1.23, 33.05, 0.01, etc. Valor obligatorio en Modo Transparente. cFactura, campo suministrado por el comercio, para asociar una descripción o valor a la operación. Este valor es generado por el comercio y el TPVPC no realizará ninguna validación sobre el mismo. cTipoOper, indica el tipo de operación a realizar. Puede tomar dos posibles valores: CONFIRMACION, realizará una confirmación PREAUTORIZACIÓN que se autorizó con anterioridad.

sobre

una

DEVOLUCION, realizará una devolución de una operación que se autorizó con anterioridad. Valor obligatorio en Modo Transparente.

cXMLResp, buffer que almacenará una cadena XML con el resultado de la operación de DEVOLUCION o CONFIRMACION. El formato de este XML se encuentra detallado en la documentación "Conexión con TPVPC a través de WEB SERVICE" versión 6.0.

iTamMaxResp, indica el tamaño máximo del buffer donde se almacenará la cadena xml con el resultado de la operación. Se recomienda al menos un tamaño de 1024 bytes.



28/08/2014 11


Valor de retorno: Valor 0, indica que la operación se ha procesado correctamente. Muy importante indicar que este resultado NO INDICA QUE LA OPERACIÓN ESTÉ AUTORIZADA, tan sólo es el resultado de su proceso. Valor distinto de 0, Código de error indicando el motivo del fallo. En el Anexo III, se detallan estos errores.

int fnDllOperComContable(LPCTSTR cNumPedido, LPCTSTR cRTSOriginal, LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperComContable(String cNumPedido, String cRTSOriginal, String cImporte, String cFactura, String cTipoOper, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllOperComContable Lib "dllTpvpcLatente.dll" (ByVal cNumPedido As String, ByVal cRTSOriginal As String, ByVal cImporte As String, ByVal cFactura As String, ByVal cTipoOper As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer



28/08/2014 12


3.8

¿Cómo realizar una Devolución/Confirmación desde otro terminal? Cuando se quiere realizar una devolución (o confirmación) desde un Terminal distinto al que realizó la operación original, existen dos opciones:

1º) Devolución/Confirmación a partir del número de pedido de la operación original. Cuando sólo se dispone del número de pedido para identificar la operación original, es necesario especificar el Terminal por el que se realizó dicha operación. Se encuentra disponible la siguiente función:

int fnDllOperComContableTerminal(LPCTSTR cNumTerminal, LPCTSTR cNumPedido, LPCTSTR cRTSOriginal, LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperComContableTerminal(String cNumTerminal, String cNumPedido, String cRTSOriginal, String cImporte, String cFactura, String cTipoOper, StringBuilder cXMLResp, int iTamMaxResp);

Ejemplo de llamada en Visual Basic .NET Public Declare Function fnDllOperComContableTerminal Lib "dllTpvpcLatente.dll" (ByVal cNumTerminal As String, ByVal cNumPedido As String, ByVal cRTSOriginal As String, ByVal cImporte As String, ByVal cFactura As String, ByVal cTipoOper As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer

2º) Devolución/Confirmación a partir del identificador RTS de la transacción original. Cuando se dispone del identificador de operación idRTS, basta con realizar la llamada a la función fnDllOperComContable como si fuese desde el Terminal original, pero una vez inicializado con un Terminal diferente.



28/08/2014 13


Nota: esta operativa no funcionará si el tpv tiene asignado un código de comercio distinto al de la operación original.

3.9

Realizar una operación de Devolución con lectura desde el Pinpad Una devolución, como su propio nombre indica, realiza el abono o devolución del importe indicado, a la tarjeta con la que se realizó la operación original. Para mayor seguridad, se puede obligar a pasar la tarjeta original con la que se hizo el pago, de forma que el cliente esté presente. Es importante señalar que este tipo de devolución no está soportada en Windows Mobile.


cImporte, importe que se quiere devolver, en formato XXXXXXXXX.XX. Ejemplo: 1.23, 33.05, 0.01, etc. Valor obligatorio en Modo Transparente. cFactura, campo suministrado por el comercio, para asociar una descripción o valor a la operación. Este valor es generado por el comercio y el TPVPC no realizará ninguna validación sobre el mismo. cNumPedido, número de pedido de la operación original. El campo pedido se encuentra en todas las respuestas de peticiones de operaciones realizadas al TPVPC. Valor obligatorio en Modo Transparente. cRTSOriginal, identificador RTS de la transacción original. El campo identificadorRTS se encuentra en todas las respuestas de peticiones de operaciones realizadas al TPVPC. Valor Opcional, en cualquiera de los modos. En modo Transparente se recomienda su uso. cXMLResp, buffer, que almacenará una cadena XML con el resultado de la operación de DEVOLUCION. El formato de este XML se encuentra detallado en la documentación "Conexión con TPVPC a través de WEB SERVICE" version 6.0. iTamMaxResp, indica el tamaño máximo del buffer donde se almacenará la cadena xml con el resultado de la operación. Se recomienda al menos un tamaño de 1024 bytes.



28/08/2014 14



int fnDllComContableTrj(LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cNumPedido, LPCTSTR cRTSOriginal, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllComContableTrj(String cImporte, String cFactura, String cNumPedido, String cRTSOriginal, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllComContableTrj Lib "dllTpvpcLatente.dll" (ByVal cImporte As String, ByVal cFactura As String, ByVal cNumPedido As String, ByVal cRTSOriginal As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer



28/08/2014 15


3.10

¿Cómo validar si la operación resultó AUTORIZADA? En la cadena con el resultado de operación, siempre deben aparecer los siguientes elementos con el valor que se indica a continuación: F Autorizada

Si la respuesta no contiene estos valores, debe tomarse como una transacción DENEGADA. Ejemplo de cadena con el resultado de la operación de DEVOLUCION o CONFIRMACION:

1.01 978 777888991 1 10550 FAC_384572 070001070319164116378278 10549 2007-03-19 16:41:16 F Autorizada DBBCA72FC4A5FEBB76E3260789DDCF51A3903D4F

En el ejemplo descrito la operación ha resultado autorizada.

3.11

Realizar una operación de Devolución sin Original Para realizar este tipo de operación, el comercio debe tener previamente habilitada la operativa. Estas devoluciones realizan el abono del importe especificado en la tarjeta leída desde el Pinpad. Como su nombre indica, esta operación no valida contra ninguna operación realizada con anterioridad.

Parámetros de entrada:



28/08/2014 16


cImporte, importe que se quiere devolver o confirmar, en formato XXXXXXXXX.XX. Ejemplo: 1.23, 33.05, 0.01, etc. Valor obligatorio en Modo Transparente. cFactura, campo suministrado por el comercio, para asociar una descripción o valor a la operación. Este valor es generado por el comercio y el TPVPC no realizará ninguna validación sobre el mismo. cXMLResp, buffer que almacenará una cadena XML con el resultado de la operación de DEVOLUCION. iTamMaxResp, indica el tamaño máximo del buffer donde se almacenará la cadena xml con el resultado de la operación. Se recomienda al menos un tamaño de 1024 bytes


int fnDllDevSinOrigTrj (LPCTSTR cImporte, LPCTSTR cFactura, LPTSTR cXMLResp, int iTamMaxResp)


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllDevSinOrigTrj(String cImporte, String cFactura, StringBuilder cXMLResp, int iTamMaxResp);

Ejemplo de llamada en Visual Basic .NET:

Public Declare Function fnDllDevSinOrigTrj Lib "dllTpvpcLatente.dll" (ByVal cImporte As String, ByVal cFactura As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer



28/08/2014 17


3.12

Realizar una operación de Devolución sin Original introduciendo manualmente los datos de la tarjeta Para realizar este tipo de operación, el comercio debe tener previamente habilitada la operativa. Estas devoluciones realizan el abono del importe especificado en la tarjeta indicada. Como su nombre indica, esta operación no valida contra ninguna operación realizada con anterioridad.


cTarjeta, número de tarjeta. Las tarjetas tienen una longitud entre 15 y 19 caracteres. Campo Opcional si está trabajando en Modo Interfaz de Usuario, en este modo lo solicitará la aplicación TpvpcImplantado. cCaducidad, cadena con la caducidad de la tarjeta. El formato es AAMM. Ejemplo 06/13, el formato sería 1306. Campo Opcional si está trabajando en Modo Interfaz de Usuario, en este modo lo solicitará la aplicación TpvpcImplantado. cImporte, importe que se quiere devolver o confirmar, en formato XXXXXXXXX.XX. Ejemplo: 1.23, 33.05, 0.01, etc. Valor obligatorio en Modo Transparente. cFactura, campo suministrado por el comercio, para asociar una descripción o valor a la operación. Este valor es generado por el comercio y el TPVPC no realizará ninguna validación sobre el mismo. cXMLResp, buffer que almacenará una cadena XML con el resultado de la operación de DEVOLUCION. iTamMaxResp, indica el tamaño máximo del buffer donde se almacenará la cadena xml con el resultado de la operación. Se recomienda al menos un tamaño de 1024 bytes

Valor de retorno: Valor 0, indica que la operación se ha procesado correctamente. Muy importante indicar que este resultado NO INDICA QUE LA OPERACIÓN ESTÉ AUTORIZADA, tan sólo es el resultado de su proceso. Valor distinto de 0, Código de error indicando el motivo del fallo. En el Anexo III, se detallan estos errores

int fnDllOperDevSinOrig(LPCTSTR cTarjeta, LPCTSTR cCaducidad, LPCTSTR cImporte, LPCTSTR cFactura, LPTSTR cXMLResp, int iTamMaxResp)



28/08/2014 18



[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperDevSinOrig(String cTarjeta, String cCaducidad, String cImporte, String cFactura, StringBuilder cXMLResp, int iTamMaxResp);

Ejemplo de llamada en Visual Basic .NET :

Public Declare Function fnDllOperDevSinOrig "dllTpvpcLatente.dll" (ByVal cTarjeta As String, cCaducidad As String, ByVal cImporte As String, cFactura As String, ByVal cXMLResp As String, iTamMaxREsp As Integer) As Integer

3.13

Lib ByVal ByVal ByVal

¿Cómo validar si la operación resultó AUTORIZADA? En la cadena con el resultado de operación siempre deben aparecer los siguientes elementos con el valor que se indica a continuación: F Autorizada

Si la respuesta no contiene estos valores, debe tomarse como una transacción DENEGADA



28/08/2014 19


Ejemplo de cadena con el resultado de la operación de DEVOLUCION SIN ORIGINAL: 1.01 978 123443210 1 11205 070001070413140553434193 1 2007-04-13 14:05:53 F Autorizada 09BCDC2AB6B9178D3F3ADF7EBEC879BE9F631D80

En este ejemplo la operación ha resultado autorizada.

3.14

Realizar consultas de Operaciones Esta operativa permite realizar consultas de operaciones sobre el comercio-terminal en la función de Inicialización. Los XML de respuesta se describen con detalle en el documento TPVPC WS Consultas. En este documento se mostrarán algunos XML de ejemplo, pero no se entrará en detalle en la explicación de sus campos.


cNumPedido, número de pedido de la operación a recuperar. Se puede especificar un valor NULL si no se desea realizar búsquedas por este campo. cRTS, identificador de transacción, sólo se devolverán los datos de la operación solicitada. Se puede especificar un valor NULL, si no se desea realizar búsquedas por este campo. Si se indica este campo, se ignorará el resto de los campos especificados. cFactura, campo de factura o referencia que puede especificar el comercio en las operaciones realizadas en el TPVPC, o NULL, si no se desea realizar búsquedas por este campo. cFechaIni, fecha de inicio de operación. El formato debe ser el siguiente: YYYYMMdd HHmmss, 20070415 172905. Se puede especificar un valor NULL, si no se desea realizar búsquedas por este campo.



28/08/2014 20


cFechaFin, fecha de fin de operación. El formato debe ser el siguiente: YYYYMMdd HHmmss, 20070415 182905. Se puede especificar un valor NULL, si no se desea realizar búsquedas por este campo. cTipo, tipo de Operación. Se pueden -> PAGO

indicar los siguientes valores:

-> PREAUTORIZACION -> CONFIRMACION -> DEVOLUCION Se puede especificar un valor NULL, si no se desea realizar búsquedas por este campo. cResultado, resultado de la operación. Se podrá consultar las operaciones Autorizadas o Denegadas. Se pueden indicar los siguientes valores: -> AUTORIZADA, recupera sólo las operaciones autorizadas. -> DENEGADA, recupera sólo las operaciones denegadas. Se puede especificar un valor NULL, si no se desea realizar búsquedas por este campo. cNumPagina, indica el número de página a recuperar. El WebService realiza una paginación de consulta, aquí se indica, en caso de devolver varias páginas, el número de página a recuperar. Si se quiere recuperar la primera página, se debe indicar el número 0. cXMLResp, buffer que almacenará la cadena con el XML de respuesta recibido desde el TPVPC. El XML se describe en detalle en el documento TPVPC WS Consultas 2d1. iTamMaxResp, tamaño máximo de la cadena que puede almacenar el buffer cXMLResp.

Valor de retorno: = 0, la operación se procesó correctamente. Este resultado no indica que se haya autorizado o denegado, simplemente que la petición se ha realizado con éxito. Para ver el resultado de la operación se debe analizar la respuesta recibida en cXMLResp. != 0, Código de error indicando el motivo del fallo. Descripción de los posibles códigos de error: -1 No se han establecido correctamente los datos de configuración. Es necesario volver a llamar a la función fnDllIniTpvpcLatente. Si el problema persiste contactar con la entidad.



28/08/2014 21


-2 Se produjo un error interno del sistema al realizar la operación. Si el problema persiste contacte con su entidad. -3 Error en los parámetros de entrada. Si el problema persiste contactar con la entidad.

int fnDllOperConsulta(LPCTSTR cNumPedido, LPCTSTR cRTS, LPCTSTR cFactura, LPCTSTR cFechaIni, LPCTSTR cFechaFin, LPCTSTR cTipo, LPCTSTR cResultado, LPCTSTR cNumPagina, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperConsulta(String cNumPedido, String cRTS, String cFactura, String cFechaIni, String cFechaFin, String cTipo, String cResultado, String cNumPagina, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllOperConsulta Lib "dllTpvpcLatente.dll" (ByVal cNumPedido As String, ByVal cRTS As String, ByVal cFactura As String, ByVal cFechaIni As String, ByVal cFechaFin As String, ByVal cTipo As String, ByVal cResultado As String, ByVal cNumPagina As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer

Ejemplo de respuesta:

Autorizacion ************5532 0702 0.01 978 1 1110 070001070423122035346136 2007-04-23 12:20:35.628 IDOPER_PINPAD F AUTORIZADA 0 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 22


Autorizacion ************5532 0702 0.01 978 1 1118 070001070423094540346125 2007-04-23 09:45:40.436 IDOPER_PINPAD F AUTORIZADA 0 2 1 1 777888991 20070423 125118 8E7C43989E4586F3CA3ED781EF3CB2E1270C0075

3.15

Realizar Consulta de Totales Esta operativa devuelve el total de operaciones realizadas por el comercio/terminal en la fecha indicada.


cFecha, fecha del día para recuperar los totales. Si no se especifica, se utilizará el día actual. cDesgloseVM, "S" indica que se realice un desglose por marca de Tarjeta Visa / Master. cDesgloseMarcas, "S" indica que se realice un desglose por Marcas de Tarjeta.

Valor de retorno: = 0, la operación se procesó correctamente. Este resultado no indica que se haya autorizado o denegado, simplemente que la petición se ha realizado con éxito. Para ver el resultado de la operación se debe analizar la respuesta recibida en cXMLResp. != 0, Código de error indicando el motivo del fallo. Descripción de los posibles códigos de error:



28/08/2014 23


-1 No se han establecido correctamente los datos de configuración. Es necesario volver a llamar a la función fnDllIniTpvpcLatente. Si el problema persiste contactar con la entidad. -2 Se produjo un error interno del sistema al realizar la operación. Si el problema persiste contacte con su entidad. -3 Error en los parámetros de entrada.

int fnDllOperTotales(LPCTSTR cFecha, LPTSTR cDesgloseVM, LPTSTR cDesgloseMarcas, LPTSTR cXMLResp, int iTamMaxResp)


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperTotales(String cFecha, String cDesgloseVM, String cDesgloseMarcas, StringBuilder cXMLResp, int iTamMaxResp)


Public Declare Function fnDllOperTotales Lib "dllTpvpcLatente.dll" (ByVal cFecha As String, ByVal cDesgloseVM As String, ByVal cDesgloseMarcas As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer

Ejemplo de Respuesta:

2007-04-23 978 #.##0,00 0 0 0.0 0 0 0.0 0 0 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 24


0.0 0 0 0.0 0.00 20070423 085423 D8C17407BFB547749864A68250B611F41377C502

3.16

Realizar Operación DCC Realiza una operación de Pago o Preautorización utilizando la opción Pago en Divisas o DCC (Dinamyc Currency Conversion). Este método sólo es llamado con los datos de respuesta obtenidos en la llamada a la función fnDllOperPinPad.

Parámetros de entrada/salida:

cImporte, importe de la transacción en formato XXXXXXXXX.XX. Ejemplo: 1.23, 33.05, 0.01, etc. Mismo valor que el que se utilizó en fnDllOperPinPad cFactura, referencia de compra. Este valor lo puede especificar el comercio. Mismo valor que el que se utilizó en fnDllOperPinPad cTipoOper, operación Pago o Preautorización. Mismo valor que el que se utilizó en fnDllOperPinPad cCodDivisa, código de divisa en el que se desea realizar la transacción. Se debe especificar el código de la moneda que ha seleccionado el Titular, es decir, el valor del campo codigoDivisa, si el titular seleccionó pagar en su moneda, o el campo monedaOriginal. cXMLResp, Devuelve un XML de Respuesta con el resultado de la operación de pago o preautorización. La librería validará que la firma recibida es correcta. El formato de este XML se encuentra detallado en la documentación "Conexión con TPVPC a través de WEB SERVICE" versión 6.0. iTamMaxResp, indica el tamaño máximo del buffer de respuesta. Se recomienda al menos un tamaño de 1024 bytes.

Valor de retorno:



28/08/2014 25


En caso de que la operación se enviase correctamente la función devolverá 0. Si el TPVPC devuelve un XML con un código de error, la función también devolverá 0, ya que este código sólo indica si se pudo enviar correctamente la petición. = 0, petición realizada correctamente. Es necesario revisar el XML con la respuesta de la transacción. != 0, Código de error indicando el motivo del fallo. Descripción de los posibles códigos de error: -1 No se han establecido correctamente los datos de configuración. Es necesario volver a llamar a la función fnDllIniTpvpcLatente. Si el problema persiste contactar con la entidad. -2 Se ha sobrepasado el TimeOut especificado por la aplicación. -3 Error del Sistema. Es necesario reiniciar aplicación. -4 Los datos de entrada no tienen un formato correcto. Revisar lista de parámetros.

int fnDllOperPinPadDCC(LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPCTSTR cCodDivisa, LPTSTR cXmlResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperPinPadDCC(String cImporte, String cFactura, String cTipoOper, String cCodDivisa, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllOperPinPadDCC Lib "dllTpvpcLatente.dll" (ByVal cImporte As String, ByVal cFActura As String, ByVal cTipoOper As String, ByVal cCodDivisa As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer



28/08/2014 26


3.17

Realizar Operación DCC con Entrada Manual de Datos Realiza una operación de Pago o Preautorización utilizando la opción Pago en Divisas o DCC (Dinamyc Currency Conversion). Este método sólo es llamado con los datos de respuesta obtenidos en la llamada a la función fnDllOperManualExt.

Parámetros de entrada/salida:

cCodDivisa, código de divisa en el que se desea realizar la transacción. Se debe especificar el código de la moneda que ha seleccionado el Titular, es decir, el valor del campo codigoDivisa, si el titular seleccionó pagar en su moneda, o el campo monedaOriginal. cXMLResp, Devuelve un XML de Respuesta con el resultado de la operación de pago o preautorización. La librería validará que la firma recibida es correcta. El formato de este XML se encuentra detallado en la documentación "Conexión con TPVPC a través de WEB SERVICE" versión 6.0. iTamMaxResp, indica el tamaño máximo del buffer de respuesta. Se recomienda al menos un tamaño de 1024 bytes.

Valor de retorno: En caso de que la operación se enviase correctamente la función devolverá 0. Si el TPVPC devuelve un XML con un código de error, la función también devolverá 0, ya que este código sólo indica si se pudo enviar correctamente la petición. = 0, petición realizada correctamente. Es necesario revisar el XML con la respuesta de la transacción. != 0, Código de error indicando el motivo del fallo. Descripción de los posibles códigos de error: -1 No se han establecido correctamente los datos de configuración. Es necesario volver a llamar a la función fnDllIniTpvpcLatente. Si el problema persiste contactar con la entidad. -2 Se ha sobrepasado el TimeOut especificado por la aplicación. -3 Error del Sistema. Es necesario reiniciar aplicación. -4 Los datos de entrada no tienen un formato correcto. Revisar lista de parámetros.



28/08/2014 27


int fnDllOperManualDCC(LPCTSTR cCodDivisa, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperManualDCC(String cCodDivisa, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllOperManualDCC Lib "dllTpvpcLatente.dll" (ByVal cCodDivisa As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer

3.18

Ejemplo de Operación DCC Primero: Se realizará una operación de Pago o Preautorización estándar. Ejemplo: fnDllOperPinPad (“25.36”, “OPER-DCC-TST”, “PAGO”, cXmlResp, 1024);

Si la operación es DCC, en la variable cXmlResp obtendremos el siguiente XML de respuesta: 25.36 978 17.81 826 POUND STERLING GBP 2 1.7500 1.424209 1.449133 777888991 5 4000 REDSYS 3CB335CF2F15DDDC6623B3A30C48AD9B6873679F 826 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 28


1 1 VISA

Segundo: Se mostrará al titular una pantalla donde se solicitará que seleccione la moneda con la que quiere realizar la transacción. Ejemplo (los literales en negrita deben aparecer siempre y en inglés):

Muestre el siguiente mensaje al cliente:

You have the choice of paying your bill in either: EUR or Service and Exchange rate provided by : 1.00 = EUR INCLUDES % MARK UP over source rate provided by . NO COMMISSION

Seleccione divisa según indicaciones del cliente:

EURO



28/08/2014 29


Como se ve en el ejemplo, hay que utilizar la información devuelta en el anterior XML de respuesta.

Tercero: Realizar la transacción en la moneda seleccionada por el titular: fnDllOperPinPadDCC(“25.36”, “OPER-DCC-TST”, “PAGO”, “826”, cXmlResp, 1024);

El XML de Respuesta:

PAGO 25.36 978 ************8095 ************8095 1 0000 777888991 5 2336 070001080616130833332827 OPER-DCC-TST 2008-06-16 13:00:10.0 826 17.81 1.424209 1.449133 1.7500 F Autorizada 067331 I ACCEPT THAT I HAVE BEEN OFFERED A CHOICE OF CURRENCIES FOR PAYMENT. I ACCEPT THE CONVERSION RATE AND FINAL AMOUNT. I UNDERSTAND THAT THE CHOICE OF TRANSACTION CURRENCY IS FINAL. TRANSACTION CURRENCY GBP WHOLESALE RATE PROVIDED BY VISA MARK-UP: 1.7500 % NO COMMISSION SERVICE AND#N#EXCHANGE RATE PROVIDED BY#N#REDSYS GBP 1.00 = 1.424209 EUR Questions, if any, please#N#call (+34) 91 343 32 18#N# AEC91DBE60EE3A12EE8F95E16CA18EFECE41556D

A continuación mostramos un recibo (formato sólo texto) con la información a imprimir y elemento xml que la contiene.



28/08/2014 30


En algunos elementos se puede recibir el carácter #N#, este carácter indica un retorno de carro o nueva línea.

El elemento linCambio sólo debe mostrarse en el recibo o copia que se quedará el comercio.



28/08/2014 31


3.19

Realizar una repetición de pago con tarjeta en archivo Una repetición de pago con tarjeta en archivo se realiza siempre sobre una operación inicial de pago con tarjeta en archivo realizada con anterioridad. Se pueden realizar hasta 99 repeticiones de un pago con tarjeta en archivo, siempre con el mismo importe y la misma tarjeta que el pago original.


cNumPedido, número de pedido de la operación original. El campo pedido se encuentra en todas las respuestas de peticiones de operaciones realizadas al TPVPC. Valor obligatorio en Modo Transparente. cRTSOriginal, identificador RTS de la transacción original. El campo identificadorRTS se encuentra en todas las respuestas de peticiones de operaciones realizadas al TPVPC. Valor obligatorio en Modo Transparente. cFactura, campo suministrado por el comercio, para asociar una descripción o valor a la operación. Este valor es generado por el comercio y el TPVPC no realizará ninguna validación sobre el mismo. cXMLResp, buffer que almacenará una cadena XML con el resultado de la operación. El formato de este XML se encuentra detallado en la documentación "Conexión con TPVPC a través de WEB SERVICE" versión 6.0. iTamMaxResp, indica el tamaño máximo del buffer donde se almacenará la cadena XML con el resultado de la operación. Se recomienda al menos un tamaño de 1024 bytes.




28/08/2014 32


int fnDllOperPagoTjtArchivo(LPCTSTR cNumPedido, LPCTSTR cRTSOriginal, LPCTSTR cFactura, LPTSTR cXMLResp, int iTamMaxResp);


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllOperPagoTjtArchivo(String cNumPedido, String cRTSOriginal, String cFactura, StringBuilder cXMLResp, int iTamMaxResp);


Public Declare Function fnDllOperPagoTjtArchivo Lib "dllTpvpcLatente.dll" (ByVal cNumPedido As String, ByVal cRTSOriginal As String, ByVal cFactura As String, ByVal cXMLResp As String, ByVal iTamMaxREsp As Integer) As Integer



28/08/2014 33


4.

ANEXO I. Integración ActiveX La librería suministrada también dispone de un componente ActiveX, que permite la integración de TpvpcImplantado con aquellos entornos de desarrollo o aplicaciones que no pueden integrar librerías dinámicas. Un claro ejemplo sería una aplicación Web que utilice el Navegador Internet Explorer. Para realizar la integración se adjunta el CLSID y nombre del Objeto. En la mayoría de los entornos de desarrollo, se dispone de asistentes para el uso de componentes Activex (conocidos también como objetos COM).

CLSID: DB09CE0A-6E1B-4107-A465-1DBA1C2DDA66 Identificador Objeto: DllTpvpcLatente.TpvpImplantado

A continuación se define la correlación entre los métodos del ActiveX y las funciones de la librería. El ActiveX simplemente hace de envoltorio para realizar las llamadas a la librería, se indica el nombre del método en el ActiveX y su correspondencia con la librería.

int IniTpvpcLatente(BSTR bstComercio, BSTR bstTerminal, BSTR bstClaveFirma, BSTR bstConfPuerto, BSTR bstVersion)

int fnDllIniTpvpcLatente(LPCTSTR cComercio, LPCTSTR cTerminal, LPCTSTR cClaveFirma, LPCTSTR cConfPuerto, LPCTSTR cVersion)

int OperPinPad(BSTR bstImporte, BSTR bstFactura, BSTR bstTipoOper, BSTR *bstXMLResp)

int fnDllOperPinPad(LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp);

int OperManualExt(BSTR bstTarjeta, BSTR bstCaducidad, BSTR bstCVC2, BSTR bstImporte, BSTR bstFactura, BSTR bstTipoOper, BSTR *bstXMLResp)

int fnDllOperManualExt(LPCTSTR cTarjeta, LPCTSTR cCaducidad, LPCTSTR cCVC2, LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp)

int OperComContable(BSTR bstNumPedido, BSTR bstRTSOriginal, BSTR bstImporte, BSTR bstFactura, BSTR bstTipoOper, BSTR *bstXMLResp)



28/08/2014 34


int fnDllOperComContable(LPCTSTR cNumPedido, LPCTSTR cRTSOriginal, LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPTSTR cXMLResp, int iTamMaxResp)

int TrataPetComContableTrj (BSTR bstImporte, BSTR bstFactura, BSTR bstNumPedido, BSTR bstRTSOriginal, BSTR *bstXMLResp)

int fnDllComContableTrj(LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cNumPedido, LPCTSTR cRTSOriginal LPTSTR cXMLResp, int iTamMaxResp)

int TrataPetDevSinOrigTrj(BSTR bstImporte, BSTR bstFactura, BSTR *bstXMLResp)

int fnDllDevSinOrigTrj(LPCTSTR cImporte, LPCTSTR cFactura, LPTSTR cXMLResp, int iTamMaxResp)

int OperDevSinOriginal(BSTR bstTarjeta, BSTR bstCaducidad, BSTR bstImporte, BSTR bstFactura, BSTR *bstXMLResp)

int fnDllOperDevSinOrig(LPCTSTR cTarjeta, LPCTSTR cCaducidad, LPCTSTR cImporte, LPCTSTR cFactura, LPTSTR cXMLResp, int iTamMaxResp)

int OperConsulta(BSTR bstNumPedido, BSTR bstRTS, BSTR bstFactura, BSTR bstFechaIni, BSTR bstFechaFin, BSTR bstTipo, BSTR bstResultado, BSTR bstNumPagina, BSTR *bstXMLResp)

int fnDllOperConsulta(LPCTSTR cNumPedido, LPCTSTR cRTS, LPCTSTR cFactura, LPCTSTR cFechaIni, LPCTSTR cFechaFin, LPCTSTR cTipo, LPCTSTR cResultado, LPCTSTR cNumPagina, LPTSTR cXMLResp, int iTamMaxResp);

int OperTotales(BSTR bstFecha, BSTR bstDesgloseVM, BSTR bstDesgloseMarcas, BSTR *bstXMLResp)

int fnDllOperTotales(LPCTSTR cFecha, LPTSTR cDesgloseVM, LPTSTR cDesgloseMarcas, LPTSTR cXMLResp, int iTamMaxResp)

int OperPinPadDCC(BSTR bstImporte, BSTR bstFactura, BSTR bstTipoOper, BSTR bstCodDivisa, BSTR *bstXMLResp) Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 35


int fnDllOperPinPadDCC(LPCTSTR cImporte, LPCTSTR cFactura, LPCTSTR cTipoOper, LPCTSTR cCodDivisa, LPTSTR cXmlResp, int iTamMaxResp);

int TrataPetPagoTjtArchivo(BSTR bstNumPedido, BSTR bstRTSOriginal, BSTR BSTR bstFactura, BSTR *bstXMLResp)

int fnDllOperPagoTjtArchivo(LPCTSTR cNumPedido, LPCTSTR cRTSOriginal, cFactura, LPTSTR cXMLResp, int iTamMaxResp);

int OperAnulPreaut(BSTR bstNumPedido, bstFactura, BSTR *bstXMLResp);

BSTR

int fnDllOperAnulPreaut(LPCTSTR cNumPedido, cFactura, LPTSTR cXMLResp, int iTamMaxResp);

bstRTSOriginal,

LPCTSTR

cRTSOriginal,

LPCTSTR

BSTR

LPCTSTR

int OperReemplazoPreaut(BSTR bstImporte, BSTR bstNumPedido, BSTR bstRTSOriginal, BSTR bstFactura, BSTR *bstXMLResp);

int fnDllOperReempPreaut(LPCTSTR cNumPedido, LPCTSTR cRTSOriginal, cImporte, LPCTSTR cFactura, LPTSTR cXMLResp, int iTamMaxResp);

LPCTSTR



28/08/2014 36


5.

ANEXO II. Integración Windows Mobile (Pocket PC) En este anexo se detallarán las modificaciones que afectan a la integración de la librería en esta plataforma.

Funcionalidad no disponible para: •

Modo Interfaz de Usuario. No está disponible, sólo se puede iniciar la librería en Modo Transparente.

•

Acceso utilizando ActiveX. No está disponible este modo de acceso, se deberá utilizar la integración con la librería dinámica o DLL.

Respecto a la documentación, nombre de funciones y parámetros son exactamente iguales, la única consideración a tener en cuenta es el nombre de la librería que para Windows Mobile cambia de dllTpvpcLatente.dll a dllTpvpcImplantadoWM.dll.

En los ejemplos de llamada para entorno de Desarrollo .NET que se muestran en este documento, lo único que es necesario cambiar es el nombre de la librería. A continuación mostramos un ejemplo de estos cambios:


[DllImport("dllTpvpcLatente.dll")] public static extern int fnDllIniTpvpcLatente(String cComercio, String cTerminal, String cClaveFirma, String cConfPuerto, String cVersion);

Ejemplo de llamada en C# .NET para Windows Mobile:

[DllImport("dllTpvpcImplantadoWM.dll")] public static extern int fnDllIniTpvpcLatente(String cComercio, String cTerminal, String cClaveFirma, String cConfPuerto, String cVersion);




28/08/2014 37


Public Declare Function fnDllIniTpvpcLatente Lib " dllTpvpcLatente.dll" (ByVal cComercio As String, ByVal cTerminal As String, ByVal cClaveFirma As String, ByVal cConfPuerto As String, ByVal cVersion As String) As Integer

Ejemplo de llamada en Visual Basic .NET para Windows Mobile: Public Declare Function fnDllIniTpvpcLatente Lib "dllTpvpcImplantadoWM.dll" (ByVal cComercio As String, ByVal cTerminal As String, ByVal cClaveFirma As String, ByVal cConfPuerto As String, ByVal cVersion As String) As Integer



28/08/2014 38


6.

ANEXO III. Errores devueltos

FUNCIÓN

CÓD

DESCRIPCIÓN Error Interno del Sistema. Será necesario reiniciar la carga de la librería dinámica. Si el problema persiste, notificar problema a entidad. Error al cargar el XML con los datos de configuración

fnDllIniTpvpcLatente

-1


-2


-3

No se ha especificado ningún valor en el elemento datosConf/datosComercio/comercio.


-4

No se ha especificado ningún valor en el elemento datosConf/datosComercio/terminal


-5

No se ha especificado ningún valor en el elemento datosConf/datosComercio/clave

-6

No se ha especificado ningún valor en el elemento datosConf/accesoUsuario/usuario


-7

No se ha especificado ningún valor en el elemento datosConf/accesoUsuario/clave


-8

No se ha especificado ningún valor en el elemento datosConf/modo

-9

No se ha especificado ni acceso con datos de comercio ni usuario. Es obligatorio especificar uno de los dos accesos.




-10

No se ha especificado ningún valor en el elemento datosConf/confDispositivo/puerto. Si no se quiere usar un pinpad, no es necesario incluir el elemento confDispositivo. Si se incluye se deben configurar todos los elementos.


-11

No se ha especificado ningún valor en el elemento datosConf/confDispositivo/version.


-12

Error Interno del sistema.


-13

Error al realizar el descubrimiento del PinPad. Se superó el TimeOut máximo de espera.


-14

No se pudo iniciar la interfaz gráfica del



28/08/2014 39


TPVPC Latente.

-16

Problema en la comunicación con el Servicio Web del TPVPC. Revisar conexión a Internet, e intentar una nueva inicialización cuando el servicio esté restablecido.

-18

Se envía correctamente la petición al TPVPC, pero alguno de los datos establecidos no es correcto. Revise código de comercio, terminal y la clave de firma.


-19

El Pinpad no está configurado correctamente, es necesario contactar con la entidad.


-20

El Puerto de comunicación especificado no es correcto.


-21

Se ha especificado una versión que es incompatible con el PinPad instalado. Consultar con la entidad el valor correcto.


-40

La versión de la librería ha caducado y debe actualizarse.



fnDllIniTpvpcLatenteExt

-1

Error Interno del Sistema. Será necesario reiniciar la carga de la librería dinámica. Si el problema persiste, notificar problema a entidad.

-2

Error al cargar el XML con los datos de configuración. Revisar que se han instalado todas las librerías.


-3

No se ha especificado ningún valor en el elemento datosConf/datosComercio/comercio.


-4

No se ha especificado ningún valor en el elemento datosConf/datosComercio/terminal


-5

No se ha especificado ningún valor en el elemento datosConf/datosComercio/clave


-6

No se ha especificado ningún valor en el elemento datosConf/accesoUsuario/usuario


-7

No se ha especificado ningún valor en el elemento




28/08/2014 40


datosConf/accesoUsuario/clave fnDllIniTpvpcLatenteExt


-8

No se ha especificado ningún valor en el elemento datosConf/modo

-9

No se ha especificado ni acceso con datos de comercio ni usuario. Es obligatorio especificar uno de los dos accesos.

-10

No se ha especificado ningún valor en el elemento datosConf/confDispositivo/puerto. Si no se quiere usar un pinpad, no es necesario incluir el elemento confDispositivo. Si se incluye se deben configurar todos los elementos.


-11

No se ha especificado ningún valor en el elemento datosConf/confDispositivo/version.


-12



-13

Error al realizar el descubrimiento del PinPad. Se superó el TimeOut máximo de espera.


-14

No se pudo iniciar la interfaz gráfica del TPVPC Latente.

fnDllOperManualExt

-1

No se han establecido correctamente los datos de configuración. Es necesario volver a llamar a la función fnDllIniTpvpcLatente. Si el problema persiste contactar con la entidad.

fnDllOperManualExt

-2

Se ha sobrepasado el TimeOut especificado por la aplicación.

fnDllOperManualExt

-3

Error del Sistema. Es necesario reiniciar aplicación.

fnDllOperManualExt

-4

Los datos de entrada no tienen un formato correcto. Revisar lista de parámetros.

fnDllOperManualExt

-17

El Tamaño del buffer de respuesta no es suficiente. Se recomienda utilizar el valor indicado en la documentación.

-18

El formato de algún parámetro es incorrecto. Por ejemplo, revise que el parámetro cImporte tiene formato #000.00. 3000 euros cImporte= 3000.00.


fnDllOperManualExt



28/08/2014 41


fnDllOperPinPad

-1


fnDllOperPinPad

-2


fnDllOperPinPad

-3


fnDllOperPinPad

-4


fnDllOperPinPad

-17


-18

El formato de algún parámetro es incorrecto. Por ejemplo, revise que el parámetro cImporte tiene formato #000.00. 3000 euros cImporte= 3000.00

-1


-2

Se produjo un error interno del sistema al realizar la operación. Si el problema persiste contacte con su entidad.

fnDllOperComContable

-3

Error en los parámetros de entrada. Si el problema persiste contactar con la entidad.


-12

fnDllOperPinPad




-1


fnDllOperConsulta

-2


fnDllOperConsulta

-3

Error en los parámetros de entrada.

fnDllOperConsulta

-12


fnDllOperConsulta

-15

Operación no soportada.

fnDllOperConsulta



28/08/2014 42


fnDllOperTotales

-1


fnDllOperTotales

-2


fnDllOperTotales

-3

Error en los parámetros de entrada.

fnDllOperTotales

-12


fnDllOperTotales

-15


fnDllOperPinPadDCC

-1


fnDllOperPinPadDCC

-2


fnDllOperPinPadDCC

-3


fnDllOperPinPadDCC

-4


fnDllOperPinPadDCC

-15


fnDllOperPinPadDCC

-17


-18

El formato de algún parámetro es incorrecto. Por ejemplo, revise que el parámetro cImporte tiene formato #000.00. 3000 euros cImporte= 3000.00

fnDllDevSinOrigTrj

-1


fnDllDevSinOrigTrj

-2


fnDllDevSinOrigTrj

-3

Error del Sistema. Es necesario reiniciar la aplicación.

fnDllOperPinPadDCC



28/08/2014 43


-4

Se produjo un error interno del sistema al realizar la operación. Si el problema persiste, contacte con su entidad.

fnDllDevSinOrigTrj

-5

Error en los parámetros de entrada. Si el problema persiste, contactar con la entidad.

fnDllDevSinOrigTrj

-15


-17

El tamaño del buffer de respuesta no es suficiente. Se recomienda usar el valor indicado en la documentación.

-18


fnDllDevSinOrigTrj

fnDllDevSinOrigTrj

fnDllDevSinOrigTrj

fnDllComContableTrj

-1


fnDllComContableTrj

-2


fnDllComContableTrj

-3


fnDllComContableTrj

-15


fnDllComContableTrj

-17

El tamaño del buffer de respuesta no es suficiente. Se recomienda usar el valor indicado en la documentación.

fnDllComContableTrj

-18




28/08/2014 44


7.

ANEXO IV. Versiones Librería Siempre que la librería sufra alguna modificación, se actualizará la información en el servidor, para que las distintas aplicaciones que usen esta librería se actualicen, si lo consideran necesario, con la última versión. Se aconseja mantener siempre la última versión disponible de la librería. En algunas de estas actualizaciones, el uso de una nueva versión de la librería, implicará cambios en la aplicación del comercio. La interfaz de llamadas a las funciones no se verá nunca afectada, se modificarán los XML de Respuesta, o se agregarán funciones nuevas.

7.1

¿Cuándo debe realizarse una actualización de esta Librería? Siempre que la función de inicio fnDllIniTpvpcLatente devuelva el código de error -40, indicará que es necesario realizar la actualización, ya que la versión actual se encuentra caducada. También se podrá detectar En los XML de respuesta de las operaciones fnDllOperPinPad, fnDllOperComContable, fnDllOperManual, aparecerá un elemento versdllimpl con la última versión disponible.

Ej.: Se realiza una petición de Devolución de una operación autorizada con anterioridad utilizando la función fnDllOperComContable.

XML de Respuesta recibido: 1.01 978 777888991 1 2550 070001071212171835457307 1 2548 2007-12-12 17:23:32.0 F Autorizada 140D936EE212A03B823F766FF43E4C03365AC429 1.0.4.1



28/08/2014 45


En el documento de Actualización de Versiones, se detalla todo el proceso necesario para realizar una actualización cuando ésta se encuentre disponible.



28/08/2014 46


8.

ANEXO V. Diccionario de Datos A continuación se describen todos los campos que se pueden encontrar en los XML de respuesta de los distintos métodos de la librería. •

•

•

• • • • • •

• • •

• • • •

tarjeta: número de tarjeta. Constará de 15 a 19 posiciones. Este campo solamente podrá ser informado si el comercio que realiza la transacción tiene permiso para realizar entrada manual de datos. Consulte con su Entidad si su comercio dispone de esta posibilidad. caducidad: caducidad de la tarjeta en formato AAMM. Este campo solamente podrá ser informado si el comercio que realiza la transacción tiene permiso para realizar entrada manual de datos. Consulte con su Entidad si su comercio dispone de esta posibilidad. cvc2: código de tres dígitos de seguridad que viene impreso generalmente en el reverso de la tarjeta, y que será necesario dependiendo de la actividad del comercio. Consulte con su Entidad si su comercio debe enviar obligatoriamente este campo. importe: Importe de la operación en formato N.NN. Ej: 1.00 moneda: código de la moneda de la operación. Valores -> 978 (Euros), 840 (Dólares). Este dato depende de la moneda que tenga asociada el terminal por el que se realice la operación. comercio: FUC o código del comercio. Consta de 9 dígitos. terminal: terminal en el que se realiza la operación. Numérico del 1 al 99. Es imprescindible que el terminal se encuentre dado de alta en REDSYS antes de realizar alguna operación sobre él. csb: Merchant al que pertenece el terminal. Consta de 4 dígitos. factura: cadena alfanumérica que el comercio podrá utilizar como identificador para asociar una venta con su transacción TPVPC correspondiente. REDSYS no validará el formato ni la duplicidad de esta cadena, siendo responsabilidad del comercio. El tamaño máximo de esta cadena puede ser de 20 caracteres. pedido: número de pedido u operación asociado a la transacción. Este número es devuelto por el TPVPC y servirá para identificar una determinada operación en un comercio / terminal definido. identificadorRTS: identificador de la operación Esta cadena de 24 posiciones es devuelta por el TPVPC y servirá para identificar una determinada operación en un comercio / terminal definido. tipoPago: tipo de operación que desea realizarse. Valores: PAGO -> autorización normal, PREAUTORIZACION -> preautorización, RECARGA > recarga de móviles, PREAUT_REEMPLAZO -> reemplazo de preautorizaciones, ANULACION -> anulación de preautorizaciones. firma: contiene la firma del mensaje en formato Hexadecimal (40 caracteres) fechaOperacion: fecha y hora de la operación en formato YYYY-MM-DD hh:mm:ss.miliseg estado: estado de la operación. Valores -> F (finalizada), P(en proceso), T(fallo técnico), G(Denegada) resultado: resultado de la operación. Valores -> Autorizada, Denegada.



28/08/2014 47


•

• • •

• • • • • •

• • • • • • • • • •

codigoRespuesta: contiene el código de autorización de la operación, en el caso de operación Aceptada, o el código de denegación en caso de que la operación hay sido Denegada (ver Anexo VII). Este campo no se informa en el caso de las Devoluciones/Confirmaciones Autorizadas. pedidoBase: número de pedido de la operación sobre la que se quiere realizar una operación de devolución, confirmación, anulación o reemplazo. idRTSOriginal: identificadorRTS de la operación original sobre la que se realizará una operación de devolución, confirmación, anulación o reemplazo. timestamp: fecha y hora en la que se monta el mensaje de petición, en formato yyyyMMdd HHmmss. Este dato permitirá conocer si un mensaje está caducado, con el fin de impedir que una persona no autorizada reutilice el mensaje para realizar operaciones. descripcion: detalle del error producido. En caso de un error de formato, se incluye el campo que provoca el error. La inclusión de este campo en el mensaje de salida es opcional. mensaje: mensaje de información del error. codigo: código de error devuelto por el TPVPC codigoDivisa: código numérico asociado a la moneda en la que se desea realizar la transacción DCC (Dynamic Currency Conversion). importeDivisa: Importe resultante de la operación DCC en la divisa especificada en el codigoDivisa. importeOriginal: Importe del que se desea obtener el cambio en la correspondiente divisa para operaciones DCC. El código de la moneda asociada a dicho importe se especifica en el atributo ‘codMoneda’. Si no se informa dicho atributo, toma el valor por defecto ‘978’ (EURO). tasaCambio: cambio aplicado para realizar la conversión de moneda para la operativa DCC. nombreDivisa: nombre de la moneda en la que se desea realizar la transacción DCC (Dynamic Currency Conversion). simboloDivisa: codigo reducido que identifica a la moneda en la que se desea realizar la transacción DCC. formatoDivisa: número de decimales de la moneda en la que se desea realizar la transacción DCC. porcentajeComision: comisión (en %) que se aplica para calcular el importe de la divisa. tasaDivisaConComision: cambio aplicado para realizar la conversión de moneda para la operativa DCC (igual que tasaCambio). tasaDivisaSinComision: cambio aplicado para realizar la conversión de moneda para la operativa DCC sin aplicarle el porcentaje de la comisión. literal: literales que devuelve el TPVPC y que deben aparecer en la boleta que imprime el comercio, en el orden en que se envían en el mensaje de respuesta. numTeléfono (datosRecarga): número de teléfono a recargar. idOperador: identificador del operador al que está asociada la tarjeta telefónica. Sus valores son 0 -> AMENA, 1 -> MOVISTAR, 2 -> VODAFONE, 3 -> EUSKALTEL, 4 -> XFERA.



28/08/2014 48


• • • • • • • • • • • • • •

• • • •

idTransOperador: número de referencia asignado a la transacción por el operador correspondiente. Este valor debe aparecer en el recibo de la operación. plazoPago: código de fraccionamiento que indica el tipo de aplazamiento que se realizará. tarjetaComercioRecibo: número de la tarjeta que se imprimirá en el recibo del comercio. Esta se imprimirá en la boleta asteriscada o no dependiendo de la configuración del comercio para su propia boleta. tarjetaClienteRecibo: número de la tarjeta que se imprimirá en el recibo del cliente. Esta se imprimirá en la boleta asteriscada o no dependiendo de la configuración del comercio para la boleta del cliente. titularTarjeta: nombre del titular de la tarjeta. tipoOperacion: tipo de la operación realizada (Autorizacion, Preaurorizacion, Devolucion, Confirmacion). fechaOper: fecha de la operación en formato YYYY-MM-DD para las consulta de una operación. operacionemv: Indica que se trata de una operación EMV. conttrans: Contador de transacciones recibido de tarjeta EMV. sectarjeta: Campo recibido de tarjeta EMV. idapp: Campo recibido de tarjeta EMV. etiquetaApp: Campo recibido de tarjeta EMV resverificacion: Campo recibido de tarjeta EMV. marcaTarjeta: Indica la marca de la tarjeta utilizada en la operación. Sus posibles valores son:

Marca

Indicador

VISA

1

MASTERCARD

2

DINERS

6

AMEX

8

JCB

9

CUP

22

paisTarjeta: Indica el código ISO-3166 numérico de 3 cifras de la tarjeta. Sólo disponible en determinadas operativas. tipoTasaAplicada: Indica la tasa aplicada (Crédito / Débito) en la respuesta de las autorizaciones OK de tarjetas nacionales en terminales nacionales. Sus valores son Crédito -> CRED, Débito -> DEB. ReciboSoloCliente: Indicador para imprimir sólo el recibo para el cliente. reciboOpcional: Indicador que permite no imprimir recibos, siempre que se reciba en la respuesta con valor TRUE.



28/08/2014 49


•

autenticadoPorPin: Indicador de autenticación por pin, afecta a la impresión de recibo. No se debe imprimir el recuadro de firma, en el Recibo para el comercio, ya que el usuario se autentico introduciendo el PIN de su tarjeta.



28/08/2014 50


9.

ANEXO VI. Códigos Error TPVPC A continuación se detallan los códigos de error más comunes que puede devolver el TPVPC: SOAP-TPVPC0000

Se ha producido un error al validar el mensaje.

SOAP-TPVPC0001

Error genérico.

SOAP-TPVPC0002

Firma incorrecta.

SOAP-TPVPC0003

La versión del mensaje no está soportada.

SOAP-TPVPC0004

El mensaje no contiene los elementos requeridos.

SOAP-TPVPC0005

Algunos elementos no contienen los valores esperados.

SOAP-TPVPC0006

El mensaje está caducado.

SOAP-TPVPC0007

Se ha producido un error desconocido.

SOAP-TPVPC0008

La versión del mensaje no soporta la operativa especificada.

SOAP-TPVPC0009

El mensaje de petición de consulta no puede incluir banda y número de tarjeta en el mismo mensaje.

SOAP-TPVPC0010 SOAP-TPVPC0014 SOAP-TPVPC0015

El método al que se envía la no es el adecuado. No existe una operación con esos datos. Clave no localizada

TPVPC0009

El importe de la devolución supera el importe de la operación original.

TPVPC0014

Se ha producido un error en el sistema. Inténtelo más tarde, o póngase en contacto con el Administrador.

TPVPC0015

Faltan datos para llevar a cabo la operación solicitada.

TPVPC0016

El comercio no posee ningún terminal TPVPC válido.

TPVPC0018

La tarjeta no se ha leído correctamente. Asegúrese de que la asociación lector/terminal es la correcta, e inténtelo de nuevo.

TPVPC0019

La tarjeta no se ha leído correctamente. Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 51


Asegúrese de que la asociación lector/terminal es la correcta, e inténtelo de nuevo. TPVPC0020

Se ha producido un error al realizar la operación. Inténtelo de nuevo.

TPVPC0021

No se han recibido todos los datos necesarios para modificar su contraseña.

TPVPC0024

La contraseña especificada no puede ser utilizada por motivos de seguridad. Por favor, indique otra.

TPVPC0025

El formato del número de tarjeta introducido no es válido.

TPVPC0026

La tarjeta no se ha leído correctamente. Asegúrese de que la tarjeta está en buen estado, e inténtelo de nuevo.

TPVPC0027

El formato de la fecha de caducidad introducida no es válido.

TPVPC0030

El sistema está ocupado. Reinténtelo de nuevo en unos instantes. Si el problema persiste, póngase en contacto con su administrador.

TPVPC0031


TPVPC0032

El sistema no puede acceder a las operaciones requeridas en este momento.

TPVPC0033

Faltan datos para realizar la autenticación.

TPVPC0034

El usuario con el que intenta acceder ha sido bloqueado. Póngase en contacto con su administrador para desbloquearlo.

TPVPC0035

El usuario con el que intenta acceder está dado de baja. Póngase en contacto con su administrador.

TPVPC0036

Faltan datos para llevar a cabo la operación solicitada.

TPVPC0037

El sistema no puede acceder al usuario especificado en este momento.

TPVPC0039

El perfil del usuario especificado sólo tiene acceso al Módulo de Administración TPVPC. Por favor, indique otro usuario.

TPVPC0040

El sistema no ha podido completar la operación especificada. Por favor, inténtelo de nuevo.

TPVPC0042

El sistema no soporta actualmente el método de Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 52


autenticación especificado. Por favor, modifíquelo en intente de nuevo la operación. TPVPC0043

Está intentando realizar una operación de alta sobre un usuario ya existente.

TPVPC0044

El formato del número de teléfono introducido no es válido.

TPVPC0048

El medio de pago especificado no es válido, o no es soportado por el comercio. Por favor, póngase en contacto con su administrador.

TPVPC0051

No se han definido criterios suficientes para realizar la operación solicitada.

TPVPC0052

La contraseña no es correcta, inténtelo de nuevo.

TPVPC0053

El usuario especificado no existe.

TPVPC0055

El comercio no tiene habilitada la operativa de Entrada Manual de datos.

TPVPC0056

El usuario ha sido creado satisfactoriamente, pero se ha producido un error al término de la operación. Si este problema persiste en el futuro, póngase en contacto con su administrador.

TPVPC0057

El código de entidad especificado no existe.

TPVPC0058

La moneda especificada no coincide con la moneda del terminal.

TPVPC0059

El sistema no puede acceder al terminal especificado. Asegúrese de que el terminal existe, e intente de nuevo la operación.

TPVPC0060

No existe ningún terminal apropiado para tratar la marca de tarjeta introducida.

TPVPC0061


TPVPC0062

El usuario ha sido modificado satisfactoriamente, pero se ha producido un error al término de la operación. Si este problema persiste en el futuro, póngase en contacto con su administrador.

TPVPC0063


TPVPC0064

El usuario ha sido dado de baja satisfactoriamente, pero se ha producido un error al término de la operación. Si este Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 53


problema persiste en el futuro, póngase en contacto con su administrador. TPVPC0065

El usuario especificado ya está dado de baja.

TPVPC0066

No se han encontrado usuarios que cumplan los criterios de búsqueda definidos.

TPVPC0071

El comercio no tiene habilitada la operativa de Preautorizaciones.

TPVPC0072

La operación no puede completarse debido a que no se ha recibido el dato de autenticación de la tarjeta: CVC2.

TPVPC0074

El CVC2 introducido no coincide con el especificado en la tarjeta. Asegúrese de que ha introducido correctamente los dígitos que figuran en el reverso de la tarjeta.

TPVPC0075

El perfil del usuario especificado no tiene acceso al TPVPC.

TPVPC0077

Acceso denegado al sistema. El mensaje de acceso no es válido. Comprueba el formato del mensaje, la firma y la fecha del mismo.

TPVPC0078

Está intentando realizar una operación sobre la que no tiene permisos asignados. Por favor, póngase en contacto con su Administrador.

TPVPC0079

El comercio / terminal que ha especificado no existe. Asegúrese de que ha introducido correctamente los datos y póngase en contacto con su Administrador.

TPVPC0081

Contraseña incorrecta. Para realizar la operación requerida es necesario que especifique su contraseña actual.

TPVPC0083

La configuración de su lector no es la correcta. Por favor, reintente la operación y consulte con su Administrador.

TPVPC0084

La tarjeta no se ha leído correctamente. Compruebe el estado de la tarjeta y que el lector sea el correcto, o póngase en contacto con su Administrador

TPVPC0085

La tarjeta no se ha leído correctamente. Asegúrese de que la tarjeta está en buen estado, e inténtelo de nuevo.

TPVPC0087

El sistema está ocupado. Reinténtelo de nuevo en unos instantes. Si el problema persiste,



28/08/2014 54


póngase en contacto con su administrador. TPVPC0089


TPVPC0090

El terminal no tiene asociado ningún lector válido. Por favor, configure el terminal o póngase en contacto con el Administrador.

TPVPC0091

Se ha producido un error. La operación especificada no existe.

TPVPC0092


TPVPC0093


TPVPC0094

No es posible realizar más confirmaciones sobre la preautorización original.

TPVPC0096

Se ha producido un error en el sistema. El formato de los datos pasados no es correcto.

TPVPC0097

Su contraseña no puede modificarse. Ya ha realizado las modificaciones permitidas para hoy.

TPVPC0099

El comercio no está habilitado para operar con la tarjeta de fidelización indicada.

TPVPC0100

No puede realizar una DEVOLUCION/CONFIRMACION sobre la operación especificada.

TPVPC0101

La firma no es correcta.

TPVPC0102

El certificado no es válido o no está firmado por una CA en la que se confíe.

TPVPC0103

El certificado que está intentando asociar ya está asociado a otro usuario.

TPVPC0104

La tarjeta no está asociada a ningún usuario válido en TPV_PC.

TPVPC0107

El comercio no tiene configurada la moneda especificada.

TPVPC0108

Se ha producido un error al realizar la conversión de divisas.

TPVPC0109

La tarjeta no admite el pago en la divisa especificada.

TPVPC0110

El número de plazos indicado no es válido.

TPVPC0112

El importe de una recarga para la operadora Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 55


especificada debe ser múltiplo de 5.00 Euros. TPVPC0113

El importe de una recarga para la operadora especificada debe ser múltiplo de 10.00 Euros.

TPVPC0114

El comercio no tiene habilitada la operativa de Entrada Manual de datos.

TPVPC0115

La tarjeta utilizada no admite aplazamiento de pagos.

TPVPC0117

El sistema ya está procesando una operación con los mismos datos. Si desea realizar una nueva operación, reinténtelo en unos instantes.

TPVPC0118

El sistema ha detectado que existe una operación anterior con los mismos datos, con resultado AUTORIZADA. Si desea duplicar la operación, reinténtelo en unos instantes.

TPVPC0119

El sistema ha detectado que existe una operación anterior con los mismos datos, con resultado de ERROR. Si desea repetir de nuevo la operación, reinténtelo en unos instantes.

TPVPC0120

El sistema ha detectado que existe una operación anterior con los mismos datos, con resultado RECHAZADA. Si desea repetir de nuevo la operación, reinténtelo en unos instantes.

TPVPC0121

No se puede realizar la acción requerida sobre la operación.

TPVPC0122

No se ha podido llevar a cabo la operación solicitada debido a un error en el importe.

TPVPC0123

No se puede realizar la acción requerida sobre una operación que resultó errónea o denegada.

TPVPC0124

No se puede realizar la acción requerida debido a un error.

TPVPC0126

La tarjeta utilizada no es válida.

TPVPC0127

No existe ninguna lista negra para el comercio especificado.

TPVPC0128

No se puede actualizar la información de la descarga para el comercio.

TPVPC0129

No se puede asignar la operativa de Lista Negra al comercio. No existe ninguna lista negra definida para ese comercio.

TPVPC0131

El comercio no tiene activada esta operativa.



28/08/2014 56


TPVPC0135

Error al tratar mensaje PUP.

TPVPC0148

No es posible realizar el aplazamiento del pago.

TPVPC_EMV0000

Error interno en el protocolo TPVPC EMV

TPVPC_EMV0001


TPVPC_EMV0002


TPVPC_EMV0003


TPVPC_EMV0004

Error en el proceso TLS.

TPVPC_EMV0005

Pin OnLine Solicitado no Introducido.

TPVPC_EMV0006

Terminal no Operativo. Sin Claves Simétricas.

AX-TPVPC0001

La configuración especificada no es correcta. Revise el campo descripción para más información.

AX-TPVPC0002

Error en la comunicación con TPVPC. Revisar conexión con Internet.

AX-TPVPC0003

Error en la comunicación con el PinPad. Revise configuración y conexión física con el dispositivo.

AX-TPVPC0004

Problema en la configuración del Puerto de comunicaciones.

AX-TPVPC0005

Error en el componente ActiveX de comunicación con Pinpad. Es necesario reinstalar aplicación.

AX-TPVPC0006

Error en el PinPad, mensaje recibido no valido.



28/08/2014 57


10.

ANEXO VII. Códigos de Denegación Cuando una petición de autorización da como resultado una operación denegada, en el campo codigoRespuesta se devuelve el código de denegación asociado a dicha respuesta. Este código indica el motivo por el cual se ha denegado la operación. Los códigos más comunes se detallan a continuación:

Código

Descripción

101

La tarjeta está caducada

102

Tarjeta bloqueada por el banco emisor

104

Operación no permitida para esa tarjeta o terminal

106

Intentos de PIN excedidos

107, 167

Por favor, contacte con el banco emisor de la tarjeta

109

Identificación inválida de terminal o establecimiento

110

Importe inválido

112

Se requiere PIN obligatorio

114

Tarjeta no soporta el tipo de operación solicitado

116

Disponible insuficiente

117

PIN incorrecto

118

Tarjeta no registrada

119

Desconocido

120

Operaciones denegadas por SIS

121

Excede límite de importe en anticipos de efectivo

122

Denegación por controles sobre el VCA

123

CAUV erróneo

124

Titular necesita cambio de PIN previo a operar

125

Tarjeta no efectiva

126

Bloque de PIN inválido

129

Tarjeta no operativa (error en CVC2)

130

Moneda no soportada por el emisor

160

El terminal indica que la operación de consumo CEPS no ha finalizado correctamente

161

Marca no admitida por el emisor



28/08/2014 58


180

Tarjeta no soportada por el sistema

181

Tarjeta con restricciones débito

182

Tarjeta con restricciones crédito

183

Tarjeta con restricciones débito (cuenta de crédito)

184

Error en autenticación

185

Control dispositivos no adaptados EMV

187

Error en criptografía EMV

190

Denegada por el banco emisor de la tarjeta, por diversos motivos

191

Fecha de caducidad errónea

192

Datos de case no encontrados

193

Importe excedido

194

Rechazo por el operador telefónico

195

Control Fallback

198

Denegación DCC para envío de contravalores

201

Tarjeta caducada. Orden de retirar la tarje

202, 208, Tarjeta bloqueada por el banco emisor. Orden de retirar la tarjeta 209 204

Operación no permitida para esa tarjeta o terminal

206

Intentos de PIN excedidos. Retener tarjeta

207

Tarjeta en condiciones especiales. Retener tarjeta

210

Retención por controles sobre el VCA

280

CVV1/CVC1 o CVV2/CVC2 erróneo. Retener tarjeta

290

Denegada por diversos motivos. Orden de retirar la tarjeta

912

Número de tarjeta inexistente



28/08/2014 59


11.

ANEXO VIII. Ejemplos Impresión de Recibos A continuación se muestran ejemplos de cómo las aplicaciones de los comercios deberán imprimir los recibos, cuando realicen la integración con TpvpcImplantado en Modo Transparente.

11.1

Recibo para una operación realizada con Lectura de Banda o Entrada Manual de Datos



28/08/2014 60


11.2

Recibo para una operación realizada con una Tarjeta con Chip EMV



28/08/2014 61


11.3

Recibo para una operación realizada con una Tarjeta DCC



28/08/2014 62


11.4

Ejemplo de Recibo de una operación en la que se recibe el elemento

En algunos PinPad, existe la posibilidad de capturar la firma por el propio PinPad, con lo que no es necesario imprimir el “Ejemplar para el comercio”.



28/08/2014 63


11.5

Ejemplo de Recibo

cuando

se

recibe

elemento

Cuando se reciba el elemento autenticadoPorPin, se debe imprimir en lugar del recuadro de firma, el literal que se recibe en el elemento literales/autenticadoPorPin. PAGO 0.01 978 ************5532 ************5532 1 0207 777888991 1 5221 CRED 070001070104095223003876 IDOPER_PINPAD 2007-01-04 09:52:23.656 F Autorizada 000262 OPERACION CON PIN. FIRMA NO NECESARIA. 2F88A699FD6E68E4C5BD6E33058B3101DB0E68D4 true 000996 01 A0000000031010 VISA CLASSIC 00 0880008000 TRUE



28/08/2014 64


11.6

Ejemplo de Recibo

cuando

se

recibe

elemento

Cuando se reciba el elemento operContactLess con valor TRUE, se debe imprimir la imagen que indica el tipo de operativa en el recibo. Esto es necesario realizarlo independientemente a otras posibles etiquetas que se incluyan en la respuesta, como pueden ser el caso de “autenticadoPorPin” o “ReciboSoloCliente”. PAGO 0.01 978 ************5532 ************5532 1 0207 777888991 1 5221 CRED 070001070104095223003876 IDOPER_PINPAD 2012-12-04 09:52:23.656 F Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 65


Autorizada 000262 OPERACION CON PIN. FIRMA NO NECESARIA. 2F88A699FD6E68E4C5BD6E33058B3101DB0E68D4 true 000996 01 A0000000031010 VISA CLASSIC 00 0880008000 TRUE TRUE

Las etiquetas específicas que pueden acompañar a una operación Contactless: : identifica la operación como Contactless. Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 66


: no es obligatorio imprimir la copia del comercio de acuerdo a los parámetros de configuración del terminal y los datos de la operación. Siempre que aparezca esta etiqueta, no se deberá imprimir la caja de firma. : la operación ha sido autenticada mediante el método de verificación de PIN de la tarjeta. En este caso tampoco es necesario imprimir la boleta del comercio. Siempre que aparezca esta etiqueta, no se deberá imprimir la caja de firma. : literal que sebe imprimirse siempre que aparezca. Puede tener varios valores, como por ejemplo: • •

OPERACIÓN CON PIN. FIRMA NO NECESARIA. OPERACIÓN CONTACTLESS. FIRMA NO NECESARIA.

11.7

Ejemplo de Recibo cuando Deniega Tarjeta EMV Cuando una operación se realiza con una tarjeta con chip EMV, puede suceder que el TPVPC de cómo autorizada la operación, pero sea la tarjeta quien deniegue. En este caso, se recibirán en el xml de resultado de la operación unos nuevos elementos cuyo valor será necesario imprimirlos en el recibo. A continuación detallamos estos nuevos elementos (el valor de estos debe ser impreso tal cual se devuelve en el recibo o ticket):

• • • • • • • • • • • • • • •

Val5F20, en el recibo el nombre debe aparecer como 5F20 Val5F25, en el recibo el nombre debe aparecer como 5F25 Val5F2A, en el recibo el nombre debe aparecer como 5F2A Val82, en el recibo el nombre debe aparecer como 82 Val9A, en el recibo el nombre debe aparecer como 9A Val9C, en el recibo el nombre debe aparecer como 9C Val9F10, en el recibo el nombre debe aparecer como 9F10 Val9F1A, en el recibo el nombre debe aparecer como 9F1A Val9F17, en el recibo el nombre debe aparecer como 9F17 Val9F26, en el recibo el nombre debe aparecer como 9F26 Val9F27, en el recibo el nombre debe aparecer como 9F27 Val9F33, en el recibo el nombre debe aparecer como 9F33 Val9F40, en el recibo el nombre debe aparecer como 9F40 Val9F34, en el recibo el nombre debe aparecer como 9F34 Val9F37, en el recibo el nombre debe aparecer como 9F37

PAGO 1.01 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 67


978 ************0010 ************0010 1 0000 777888991 1 5987 078090081014092317180596 DENIEGA-TARJ 2008-10-14 09:23:14.0 F Denegada 190 4D52D852A674557958BAB9236B567792D4ED082D true 000001 01 A0000000031010 4000008000 46554C4C2046554E4354494F4E414C 101231 0978 5C00 081017 00 06011A03900000 0724 03 395E4D911AB0196D 00 E0F0C0 4000F0B001 410302 37AEC214



28/08/2014 68


11.8

Ejemplo de Recibo cuando se realiza una operación con tarjeta AMEX Cuando se reciba el elemento marcaTarjeta con valor 8, esto indica que la tarjeta con la que se ha hecho la operación es una tarjeta AMEX, y los cambios en el recibo son los siguientes: • •

Cambiar el logo en el recibo, tal y como se muestra en el ejemplo. Imprimir la caducidad de la tarjeta.



28/08/2014 69


En el siguiente XML de ejemplo se muestra el en negrita el elemento con el que reconoceremos que la operación se corresponde con una hecha con tarjeta AMEX:

PAGO 1.01 978 ***********1005 374907*****1005 8 840 1249 777888991 2 2703 078090140522120226081226 FAC-LATENTE 2014-05-22 12:02:24.0 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 70


F Autorizada 081226 42687D0CCDDB630F2B72D58413D2C7E26442DA82

11.9

Ejemplo de recibo de una devolución

0.80 978 777888991 1 18792 FAC-LATENTE 078090140623105218139127 1 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 71


18790 2014-06-23 09:53:08.0 F Autorizada D2E1164A4642A108AB2A59669582E567B09D4E10

11.10 Ejemplo de recibo de devolución sin original

1.00 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 72


978 777888991 1 ************2229 0000 18796 078090140623110001139128 1 2014-06-23 11:26:57.0 F Autorizada 358357AA8B1D5CF83A12C45C292E3CBC5DA02DA



28/08/2014 73


12.

ANEXO IX. Al llamar a la función de Pago, Preautorización, Confirmación o Devolución nos devuelve el código -2 En algunos casos, debido en la mayoría de los casos por un problema en la línea de conexión a Internet, o fallo en el dispositivo (en el caso de las operaciones de Pago o Preautorización realizadas desde el PinPad) las siguientes funciones nos pueden devolver el código de retorno -2:

¿Qué hacer en estos casos?

Esta práctica no es obligatoria, pero sí muy recomendable, ya que evitará el tener que consultar la operación manualmente desde el módulo de administración, para comprobar si la operación resultó Autorizada o Denegada. De esta forma, la aplicación del comercio, automáticamente, podrá decidir si es necesario volver a enviar la transacción o simplemente, imprimir el recibo con el justificante del Pago.

Ejemplo: Se realiza una operación por 1.00 Euros

Capturamos la hora actual del Sistema: Por ejemplo, 20080109 101525. Todos los lenguajes de desarrollo disponen de funciones para recuperar la hora del Sistema. Resultado = fnDllOperPinPad(“1.00”, “FAC123456789”, “PAGO”, cXMLResp, 1024)

Si Resultado es igual a -2:

Realizamos una operación de consulta con el intervalo temporal definido entre diez minutos antes y diez minutos después de la hora de la operación original. ResultCstr = fnDllOperConsulta(null, null, “FAC123456789”, “20080109 100525”, “20080109 102525”, “PAGO”, null, “0”, cXMLResp, 1024);



28/08/2014 74


Si ResultCstr es igual a 0, en la variable cXMLResp tendremos un xml como el que se muestra a continuación:

Autorizacion ************2219 4912 1.00 978 1 2756 070001080109120353167980 2008-01-09 12:03:52.0 FAC123456789 F AUTORIZADA 2 1 0 1 777888991 20080109 120422 089A2555411FF75D1E0DE794421411CF110EF638

NOTA: En este caso la operación resulto Autorizada.

Si ResultCstr es igual a -2, se deberá revisar la conexión a Internet, si el problema persiste, contactar con la entidad para informar de la Incidencia.



28/08/2014 75


13.

ANEXO X. Operativas Adicionales En este Anexo, se describe la operativa adicional que sale del flujo normal de las transacciones descritas en los puntos anteriores. Esta operativa no se activa por defecto, por tanto, será responsabilidad del comercio solicitar su activación a la entidad. La configuración se realiza en base al comercio y al número de terminal.

13.1

Operativa DCC realizadas directamente en PinPad. Algunos modelos de PinPad disponen de la posibilidad de que el Titular seleccione la moneda de la transacción en el propio dispositivo, con lo que para la aplicación que utilice la librería será transparente y no tendrá que mostrar ningún mensaje al Titular. Lo que si tendrá que hacer es analizar el xml de respuesta recibido, para, en caso de que fuese necesario, imprimir el recibo con los datos DCC.

Siempre que en el xml de Respuesta aparezca el elemento , será necesario imprimir el recibo con los datos DCC. En el punto “Ejemplo de Operación DCC” se encuentra un ejemplo de cómo imprimir un recibo DCC.

Ejemplos de Operaciones DCC realizada en un dispositivo con capacidad DCC:

Llamada:

resultado = fnDllOperPinPad(“10.00”, “OPER DCC PINPAD”, “PAGO”, cXMLResp, 1024)

Respuesta:

El Titular decide pagar en su moneda: PAGO 10.00 978 ************8095 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 76


************8095 1 0000 777888991 5 2334 070001080616124524332822 OPER DCC PINPAD 2008-06-16 12:45:15.0 826 7.02 1.424209 1.449133 1.7500 F Autorizada 022824 I ACCEPT THAT I HAVE BEEN OFFERED A CHOICE OF CURRENCIES FOR PAYMENT. I ACCEPT THE CONVERSION RATE AND FINAL AMOUNT. I UNDERSTAND THAT THE CHOICE OF TRANSACTION CURRENCY IS FINAL. TRANSACTION CURRENCY GBP WHOLESALE RATE PROVIDED BY VISA MARK-UP: 1.7500 % NO COMMISSION SERVICE AND#N#EXCHANGE RATE PROVIDED BY#N#REDSYS GBP 1.00 = 1.424209 EUR Questions, if any, please#N#call (+34) 91 343 32 18#N# 84F71795299CC2AA4657E26E9070CD3DE697CDEB

El Titular decide pagar en la moneda del comercio (no hay operativa DCC): PAGO 10.00 978 ************8095 ************8095 1 0000 777888991 5 2335 070001080616124952332823 OPER EURO PINPAD Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 77


2008-06-16 12:49:42.0 F Autorizada 062324 BDD7ED68B1E775594DC9540CBE9E77A68540E2F4

13.2

Inhibición de recibo. Cuando el comercio tenga activada esta operativa, no es obligatorio imprimir el recibo de la operación si el importe de la operación no supera un determinado umbral. Este control es realizado por TPVPC, y en la respuesta a la operación puede indicar la necesidad de imprimir el recibo.

Siempre que en el XML de respuesta aparezca el elemento , con el valor TRUE no es obligatorio imprimir el recibo de la operación (tanto el recibo cliente como el recibo del comercio). Asimismo, tampoco es necesario solicitar firma al cliente.

Ejemplo de Operación en la que la impresión del recibo es opcional:

Llamada: resultado = fnDllOperPinPad(“10.00”, “OPER SIN RECIBO PINPAD”, “PAGO”, cXMLResp, 1024)

Respuesta: PAGO 10.00 978 ************8095 ************8095 1 0000 777888991 5 2334 Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 78


070001080616124524332822 OPER SIN RECIBO PINPAD 2008-06-16 12:45:15.0 F Autorizada 022824 TRUE 84F71795299CC2AA4657E26E9070CD3DE697CDEB

13.3

Ejemplo de Integración ActiveX desde página HTML En la siguiente URL, se encuentra ejemplo de uso del ActiveX. En este ejemplo no vienen descritos todos los métodos. No se debe tomar este ejemplo como una referencia de uso, su propósito es sólo ayudar en el proceso de integración.

http://sas-d.sermepa.es/TPV_PC/TpvpcImplantado.htm

13.4

Ejemplo de Integración de Librería .dll desde Aplicación en C# Ejemplo de Integración ActiveX desde aplicación C# .NET, se muestra cómo usar la integración de la librería dinámica. En el ejemplo se usa la clase ClsTpvpcLatente.cs, como interfaz de comunicación con la librería. Siempre existe la posibilidad de realizar la integración utilizando el ActiveX.

http://sas-d.sermepa.es/TPV_PC/ActiveX/EjTpvpcImplantadoNET.zip

13.5

Ejemplo de Integración de ActiveX desde Aplicación Visual Basic 6.0 Antes de abrir este proyecto, es necesario tener instalada y registrada la librería de comunicación.

http://sas-d.sermepa.es/TPV_PC/ActiveX/EjTpvpcImplantadoVB6.zip

13.6

Ejemplo de Integración de ActiveX desde Aplicación Visual Basic .NET (2005) Antes de abrir este proyecto, es necesario tener instalada y registrada la librería de comunicación

http://sas-d.sermepa.es/TPV_PC/ActiveX/ClienteVB_2005_Net.zip Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 79


13.7

Ejemplo de Integración de ActiveX desde Aplicación PowerBuilder 11 Antes de abrir este proyecto, es necesario tener instalada y registrada la librería de comunicación.

http://sas-d.sermepa.es/TPV_PC/ActiveX/ClientePowerBuilder_11.zip

13.8

Ejemplo de Integración de Librería desde C# para Windows Mobile (Pocket Pc) Antes de abrir este proyecto, es necesario tener instalada la librería dllTpvpcImplantadoWM.dll. Esta librería debe estar en el mismo directorio que el archivo ejecutable.

http://sas-d.sermepa.es/TPV_PC/ActiveX/AppPrueba.zip

13.9

Ejemplo de Integración de ActiveX desde Aplicación Java Antes de abrir este proyecto, es necesario tener instalada y registrada la librería de comunicación. Para este proyecto se ha usado la librería JACOB (JAva-COM Bridge). Para más información ver http://sourceforge.net/projects/jacob-project/

Esta librería usa dos componentes: o

o

Por un lado utiliza (tanto para compilar como para ejecutar) un fichero jar (jacob.jar). Por lo tanto, a la hora de ejecutar el ejemplo es necesario tener en el classpath la ruta a dicho fichero. Por otra parte, utiliza un fichero DLL (jacob-1.14.3-x86.dll o jacob-1.14.3-x64.dll, dependiendo de la arquitectura de la máquina donde se ejecute) para comunicación con la librería nativa. Es necesario especificar la ruta donde reside el fichero que corresponde a nuestra arquitectura mediante el parámetro java.library.path. Por ejemplo, a la hora de ejecutar el programa de ejemplo: java –classpath ;%CLASSPATH% –Djava.library.path=C:\_trabajo\jacob-1.14.3\dll es.sermepa.tpvpc.implantado.TpvpcLatenteJACOB

http://sas-d.sermepa.es/TPV_PC/ActiveX/ClienteImplantadoJava.zip



28/08/2014 80


13.10 Ejemplo de Integración de Librería en Visual C++ 6.0 Una vez descomprimido el archivo .zip, existe una carpeta SDK, que contiene los archivos .lib y .h necesarios para compilar el ejemplo o cualquier proyecto que realice la integración con VC. Importante tener en cuenta, que es necesario inicializar el modelo de hilos para librerías COM.

Ej.: CoInitialize(NULL);

http://sas-d.sermepa.es/TPV_PC/ActiveX/ClienteVC.zip



28/08/2014 81


14.

ANEXO XI. Tratamiento Firma Digitalizada Cuando una operación tiene asociada una firma digital, el comercio sólo tendrá la obligación de generar la boleta para el cliente sin la necesidad de firma. En este caso, se recibirá en el XML de respuesta el tag igual a TRUE: PAGO 0.04 978 ************2219 ************2219 1 0000 123443210 1 41722 CRED 070001090121162300446374 2009-01-21 17:24:31.0 REDSYS/SERVIRED F Autorizada 000061 E9A797406B8D56949B7B64A092F45AD8D4C20A45 TRUE



28/08/2014 82


Aunque el comercio y el Pinpad tengan la posibilidad de firma Digitalizada, si el cliente no firma en el dispositivo (*), se deberá imprimir tanto el recibo cliente como el comercio (con la cajetilla de firma). En este caso no se recibirá el tag :

PAGO 0.02 978 ************2229 ************2229 1 0000 123443210 1 41724 CRED 070001090121150317006247 2009-01-21 17:32:25.0 REDSYS/SERVIRED F Autorizada 012434 7064C7A60A974BF59A2B1D50CBD64E549803C281



28/08/2014 83


(*) NOTA: aun firmando el cliente en el Pinpad, la etiqueta puede no aparecer (la operación se considerará autorizada y sin firma) debido a un problema en la recepción de esta. En este caso, el comercio deberá imprimir las dos boletas como arriba expuesto, y el cliente firmar la copia para el comercio.



28/08/2014 84


15.

ANEXO XII. Tratamiento PIN Cuando una operación requiere autenticación de titular mediante PIN desde el dispositivo PinPad, no es necesario la realización de firma (ya sea manual o digitalizada) por parte del titular de la tarjeta. El resultado se mostrará en la respuesta mediante el elemento como se muestra en el ejemplo siguiente:

PAGO 0.04 978 ************0018 ************0018 2 0000 123443210 1 41726 DEB 078090090121171735362923 2009-01-21 18:19:03.0 DE PRUEBAS N1/TARJETA F Autorizada 070567 OPERACION CON PIN. FIRMA NO NECESARIA. 24008043E0FEEE639C930EC7B82294A6FA7A8BFF true 000000C000 000724 00 A0000000043060 MAESTRO 00 TRUE

Cuando aparece el tag igual a TRUE, no es obligatorio imprimir la boleta del comercio, pero sí la boleta del cliente. Si se desea imprimir la boleta del comercio se deberá imprimir el literal de la etiqueta Literales/autenticadoPorPin en lugar de la cajetilla de la firma:



28/08/2014 85




28/08/2014 86


16. 16.1

16.2

ANEXO XIII. Integración Librería nativa C++ Linux Requisitos mínimos de uso de la librería C++ Linux •

Kernel: 2.4.20 (i386)

•

Compilador: gcc 3.2.2

Integración entorno Linux La integración de TpvpcImplantado es también posible con sistemas Linux. Para ello se ha desarrollado una librería específica compatible con estos sistemas operativos, en concreto se trata de una librería dinámica: libImplantadoLinux.so. Esta librería exporta las funciones de TpvpcImplantado ya descritas anteriormente, de tal forma que el desarrollador puede usar un fichero de cabecera (TpvpcLatente.h) que tiene las definiciones de las funciones para poder desarrollar su aplicación y, posteriormente, usar las librerías para realizar el enlazado y la ejecución. La única diferencia con las funciones de TpvpcImplantado ya descritas anteriormente radica en los tipos de datos, que pasan a ser tipos de datos básicos de C++. Este es el contenido del fichero de cabecera TpvpcLatente.h:

/* Función que inicia la aplicación TPVPC LATENTE */ extern "C" int fnDllIniTpvpcLatente(char * cComercio, char * cTerminal, char * cClaveFirma, char * cConfPuerto, char * cVersion);

/* Fuerza la parada de TPVPC Latente. No devuelve errores. */ extern "C" int fnDllParaTpvpcLatente();

/* Función que realiza una petición de Pago o Preautorización al TPVPC utilizando un dispositivo PINPAD */ extern "C" int fnDllOperPinPad(char * cImporte, char * cFactura, char * cTipoOper, char * cXMLResp, int iTamMaxResp);

/* Función que confirma como se quiere realizar una operación que es DCC. Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 87


* Este método sólo debe ser llamado después de fnDllOperPinPad */ extern "C" int fnDllOperPinPadDCC(char * cImporte, char * cFactura, char * cTipoOper, char * cCodDivisa, char * cXmlResp, int iTamMaxResp);

/* Función que confirma como se quiere realizar una operación que es DCC. * Este método sólo debe ser llamado después de fnDllOperManualExt */ extern "C" int fnDllOperManualDCC(char * cCodDivisa, char * cXMLResp, int iTamMaxResp);

/* Función que realiza una petición de Pago o Preautorización al TPVPC tecleando * manualmente la tarjeta, caducidad y cvc2 */ extern "C" int fnDllOperManualExt(char * cTarjeta, char * cCaducidad, char * cCVC2, char * cImporte, char * cFactura, char * cTipoOper, char * cXMLResp, int iTamMaxResp);

/* Función que realizará una petición de Devolución/Confirmación de una operación realizada en el TPVPC */ extern "C" int fnDllOperComContable(char * cNumPedido, char * cRTSOriginal, char * cImporte, char * cFactura, char * cTipoOper, char * cXMLResp, int iTamMaxResp);

/* Función que realizará una petición de Devolución/Confirmación de una operación realizada en el TPVPC */ extern "C" int fnDllOperComContableTerminal(char * cNumTerminal, char * cNumPedido, char * cRTSOriginal, char * cImporte, char * cFactura, char * cTipoOper, char * cXMLResp, int iTamMaxResp);

/*

Función que realizará una petición de Devolución Sin Original */

extern "C" int fnDllOperDevSinOrig(char * cTarjeta, char * cCaducidad, char * cImporte, char * cFactura, char * cXMLResp, int iTamMaxResp);

/* Función para realizar consulta de operaciones realizadas con el * comercio terminal especificado en la función de Inicialización */ Redsys · C/ Francisco Sancha, 12 · 28034 · Madrid · ESPAÑA


28/08/2014 88


extern "C" int fnDllOperConsulta(char * cNumPedido, char * cRTS, char * cFactura, char * cFechaIni, char * cFechaFin, char * cTipo, char * cResultado, char * cNumPagina, char * cXMLResp, int iTamMaxResp);

/* Función que realiza una consulta de Totales, sobre el comercio/terminal especificado al iniciar la librería */ extern "C" int fnDllOperTotales(char * cFecha, char * cDesgloseVM, char * cDesgloseMarcas, char * cXMLResp, int iTamMaxResp);

/* Función que realizará una Anulación de una operación de Preautorización realizada en el TPVPC */ extern "C" int fnDllOperAnulPreaut(char * cNumPedido, char * cRTSOriginal, char * cFactura, char * cXMLResp, int iTamMaxResp);

/* Función que realizará un Reemplazo de una operación de Preautorización realizada en el TPVPC */ extern "C" int fnDllOperReempPreaut(char * cNumPedido, char * cRTSOriginal, char * cImporte, char * cFactura, char * cXMLResp, int iTamMaxResp);

/* Método que continua una operación de la que se han devuelto Opciones de Pago */ extern "C" int fnDLLTrataOpcionesPago(char * cOpcionPago, char * cXMLResp, , int iTamMaxResp);

También existe una interfaz para usar un objeto C++ que se puede encontrar en la definición de la librería “LibTPVPC.h”

Para integrar la aplicación con la librería, es necesario incluir el fichero de cabecera en todos los ficheros que realicen las llamadas a las funciones de la librería. Supongamos que tenemos un fichero que contiene el código fuente de la aplicación. Es necesario incluir en este fichero una referencia al fichero de cabecera con la definición de las funciones de la librería:

#include "TpvpcLatente.h"



28/08/2014 89


Junto con la librería se distribuye un archivo caTpvpcImplantado.pem con los certificados de Verisign necesarios para la comunicación SSL en el entorno de REAL. La librería se ha compilado utilizando la librería openSSL, no es necesario tenerla instalada en el sistema, pero si debe estar accesible en el directorio de ejecución de la aplicación el archivo caTpvpcImplantado.pem.

Si fuese necesaria la actualización de estos certificados, se podrá descargar la última versión disponible de la librería, solicitar este archivo a [email protected] o realizarlo de forma manual (openssl necesario para generar el formato PEM). Para la descarga manual, se pueden descargar desde un navegador de la URL https://tpvpc.sermepa.es/TPV_PC/html/

Si la librería requiere la generación de un fichero de Log, éste se activará de manera remota en caso de incidencia. Se generará en el directorio de ejecución de la aplicación con el nombre logDllImplantado.txt.

16.3

Ejemplo de Integración de Librería en Linux: Librería dinámica

Este proceso consiste en tener la librería en un fichero separado del ejecutable, que es cargado de forma dinámica durante la ejecución de la aplicación, únicamente cuando alguna de las funciones de la librería es llamada. De esta forma, se optimiza el tamaño del fichero ejecutable, se ahorra memoria y es más fácil el mantenimiento de la aplicación ante nuevas versiones de la librería. Una vez finalizado el desarrollo, para generar el programa ejecutable, debemos proceder de la siguiente forma: •

Copiar el fichero con la librería (libImplantadoLinux.so) en un directorio de librerías del sistema (por ejemplo, /opt/lib)

•

Compilar el programa indicando la ruta de las librerías con el parámetro –L e indicar, con el parámetro –l el nombre de la librería a usar (sin el prefijo ‘lib’):

g++ -Wall –L/opt/lib aplicación.cpp –lTpvpcImplantado –lpthread –o



28/08/2014 90


donde ejecutable de la aplicación •

es

nombre

del

fichero

A la hora de ejecutar la aplicación, al tratarse de una librería dinámica, ésta debe estar en el PATH de búsqueda del sistema. Para ello existen diferentes posibilidades, en este documento se recomiendan dos opciones, pero la decisión de cómo configurar este acceso es responsabilidad del desarrollador: -

Opción A: es necesario incluir en la variable de sistema LD_LIBRARY_PATH la ruta donde se ha almacenado la librería dinámica, en el caso de que no esté incluida:

export LD_LIBRARY_PATH=/opt/lib:$LD_LIBRARY_PATH

Esta instrucción se puede guardar en uno de los ficheros de arranque del sistema para que sólo se deba hacer una única vez. -

Opción B: crear un enlace simbólico a la librería en el directorio /usr/lib:

cd /usr/lib sudo ln –s /libImplantadoLinux.so libImplantadoLinux.so



28/08/2014 91


17.

ANEXO XIV. Integración Librería JAVA La integración de TpvpcImplantado es también posible con sistemas Linux y MAC OS. Para ello se ha desarrollado una librería en JAVA (multiplataforma) que es compatible con estos sistemas operativos. Como es multiplataforma, también puede ser usada en el sistema operativo Windows. Si bien esta librería es multiplataforma, usa una librería nativa de comunicación con puertos serie, que es específica para cada plataforma. Por otra parte, esta librería JAVA tiene la posibilidad de usar aquellos Pinpad cuya conexión sea Ethernet. Esta librería exporta las funciones de TpvpcImplantado ya descritas anteriormente. El desarrollador únicamente debe importar la clase es.sermepa.implantado.SerClsTpvpcLatente, que contiene los métodos a usar. Asimismo, deberá añadir al classpath de ejecución de la aplicación los ficheros JAR contenidos en la carpeta Include.

17.1

Requisitos mínimos de la librería JAVA •

17.2

JDK o JRE 1.5.0 o superior

Desarrollo Las funciones descritas anteriormente se implementan en la clase es.sermepa.implantado.SerClsTpvpcLatente como métodos estáticos. Esta clase se encuentra en el fichero implantado.jar. Como particularidad, el método fnDllIniTpvpcLatente recibe sólo 3 parámetros, ya que recupera la configuración del puerto desde el Módulo de Administración de TPVPC. Existe, asimismo, la versión con 5 parámetros, pero está marcada como obsoleta, ya que en futuras versiones se eliminará. Ejemplo de llamada al método fnDllIniTpvpcLatente:

import es.sermepa.implantado.SerClsTpvpcLatente; ………. String cComercio = “123443210”; String cTerminal = “1”; String cClaveFirma = “AAABBB”; int retorno = SerClsTpvpcLatente.fnDllIniTpvpcLatente(cComercio, cTerminal, cClaveFirma);

17.3

Ejecución



28/08/2014 92


Es necesario incluir en el CLASSPATH de la aplicación los ficheros implantado.jar, latente.jar y todos los ficheros JAR que se incluyen en la carpeta “include”. Para configurar el acceso a puertos serie, es necesario instalar la librería nativa RXTX, incluida en el directorio include/rxtx-2.1-7. Dentro de este directorio, hay subdirectorios para cada sistema: •

Para Linux: Seleccionar el fichero librxtxSerial.so que se encuentra en una de las subcarpetas de include/rxtx-2.1-7/Linux.

•

Para Mac_OS_X: Seleccionar el fichero librxtxSerial.jnilib que se encuentra en la carpeta include/Mac_OS_X.

•

Para Windows: Seleccionar el fichero rxtxSerial.dll que se encuentra en la carpeta include/Windows.

Una vez seleccionado el fichero deseado (y copiado al directorio requerido), es necesario añadir un parámetro de ejecución de máquina virtual Java (parámetro java.library.path). Para configurar la ejecución con esta librería: •

Windows: o

Incluir el fichero jar RXTXcomm.jar en el CLASSPATH de la aplicación. Este fichero se encuentra en el directorio “include” de la aplicación.

o

Guardar el fichero include\rxtx-2.1-7\Windows\rxtxSerial.dll en una carpeta referenciable o bien en el directorio \jre\lib\ext

o

Ejecutar la aplicación java con el parámetro java.library.path referenciando la carpeta donde se ha guardado el fichero. Ejemplo: java -Djava.library.path=%PATH_APP%\include\rxtx-2.1-7\Windows ……….

•

Linux/Mac_OS_X: o

Incluir el fichero jar RXTXcomm.jar en el CLASSPATH de la aplicación. Este fichero se encuentra en el directorio “include” de la aplicación.

o

Para Mac OS X: Guardar el fichero Mac_OS_X\librxtxSerial.jnilib en la carpeta /Library/Java/Extensions

o

Para Linux: Guardar el fichero librxtxSerial.so correspondiente a su arquitectura (seleccionar una de la carpeta Linux) en el directorio \jre\lib\ext

o

Ejecutar la aplicación java con el parámetro java.library.path referenciando la carpeta donde se ha guardado el fichero. Ejemplo:



28/08/2014 93


java -Djava.library.path=/Library/Java/Extensions …….

o

El usuario que ejecuta debe tener permisos de administrador en el equipo, además de pertenecer a los grupos uucp y lock (en algunas máquinas, _uucp y _lock): -

Un usuario se añade a los grupos lock o uucp editando el fichero /etc/groups

-

Por ejemplo: para añadir el usuario "tpvpcimplantado" al grupo lock: [Situación previa] lock:x:54: [Situación final] lock:x:54:tpvpcimplantado

-

o

En este momento, el usuario "tpvpcimplantado" ya pertenece ya al grupo lock

Es necesario tener permiso de escritura en los directorios /var/spool/uucp /var/lock Para permitir permiso de lectura-escritura, ejecutar: chmod 666 /var/spool/uucp chmod 666 /var/lock

o

Es necesario también verificar que el usuario tiene permisos de lectura y escritura en el puerto serie seleccionado: Por ejemplo, siendo el puerto serie siguiente: /dev/ttyS1, ejecutar el comando: chmod 666 /dev/ttyS1

Para ejecución con Proxy, es necesario usar los parámetros de máquina virtual (-D) http.proxyHost (Host del proxy), http.proxyPort (Puerto de escucha del proxy), http.proxyUser (Usuario de acceso al Proxy, en caso de existir), http.proxyPassword (Password del usuario de acceso al Proxy) Un ejemplo de script con ejecución completa de la aplicación de pruebas se puede encontrar en el fichero “implantado.bat”, incluido en la carpeta “samples” de la instalación de TpvpcImplantado.



28/08/2014 94


Junto con la librería se distribuye el archivo caTpvpcImplantado.jks con los certificados de Verisign necesarios para la comunicación SSL en el entorno de REAL y DESARROLLO. Este fichero debe estar en el directorio de ejecución de la aplicación, para el correcto funcionamiento de la librería. Si fuese necesaria la actualización de estos certificados, se podrá descargar la última versión disponible de la librería, solicitar este archivo a [email protected] o realizarlo de forma manual (keytool necesario para generar el formato JKS). Para la descarga manual, se pueden descargar desde un navegador de la URL https://tpvpc.sermepa.es/TPV_PC/entrada Si la librería requiere la generación de un fichero de Log, éste se activará de manera remota en caso de incidencia. Se generará en el directorio de ejecución de la aplicación con el nombre logDllImplantado.txt



28/08/2014 95

IntegracionTpvpcImplantado

Recommend Documents