Manual de Integración WebServices

Transcripción

1 Manual de Integración WebServices Guía de integración WebServices de Pagosonline, para clientes con plan Gateway (Empresarial) Revisión R 1 1

2 Control de Cambios Fecha Responsable Versión Descripción 08/Marzo/2011 Jorge Lopez Arrieta R1 Nueva versión 2

3 Contenido CAPITULO 1. Descripción de la aplicación... 6 CAPITULO 2. Como obtener los datos de acceso al WebServices... 8 CAPITULO 3. Descripción y Uso de Métodos Descripción de los métodos y objetos disponibles para los diferentes medios de pago METODO: getversion() Métodos WebServices Y Objetos METODO: leermediospagoactivos( usuarioid ) OBJETO: MedioPagoWS Métodos para consulta de transacciones METODO: consultarestadotransaccion( cuentaid, transaccionid ) OBJETO: EstadoTransaccionWS Métodos de consulta por referencia: METODO: consultarsolicitudesporreferencia( cuentaid, referencia ) METODO: obtenerestadotransacciones( usuarioid,xml ) OBJETO: XML Cuando usar los métodos de consulta Paginas de Respuesta y Confirmación: Página de Respuesta: Página de confirmación: Proceso de Pagos con Tarjeta de Crédito Figura 2: Diagrama de Flujo pagos con Tarjeta de Crédito Descripción de métodos para el pago con tarjeta de crédito METODO: solicitarautorizacion( solicitudautorizacionws ) OBJETO: SolicitudAutorizacionWS OBJETO: AutorizacionWS Proceso de Transacciones con PSE Figura 3: Diagrama de Flujo pagos con PSE Descripción de métodos para el pago con PSE METODO: leerbancospse( usuarioid ) OBJETO: BancoPseWS

4 METODO: iniciartransaccionpseconinformacionadicional (TransaccionPseConInformacionAdicionalWS) OBJETO: TransaccionPseConInformacionAdicionalWS Proceso de pago con Pago Referenciado Figura 4: Diagrama de Flujo pagos con Pago Referenciado Descripción de métodos para el pago Referenciado METODO: solicitarautorizacionpagoreferenciado(solicitudautorizacionpagoreferenciado). 30 OBJETO: SolicitudAutorizacionPagoReferenciadoWS Proceso de Pagos Recurrentes Figura 5. Diagrama de flujo Pagos Recurrentes Descripción de métodos para el pago Recurrente METODO: solicitarautorizacionrecurrente( SolicitudAutorizacionRecurrenteWS ) OBJETO: SolicitudAutorizacionRecurrenteWS OBJETO: AutorizacionRecurrenteWS METODO: consultarestadosolicitudrecurrente( cuentaid, solicitudrecurrenteid) OBJETO: EstadoSolicitudRecurrenteWS METODO: reintentarsolicitudpagorecurrente( cuentaid, solicitudpagorecurrenteid ) METODO: actualizarsolicitudpagorecurrente( cuentaid, solicitudpagorecurrenteid, cuotas, tarjeta ) METODO: cancelarsolicitudpagorecurrente( cuentaid, solicitudpagorecurrenteid ) Proceso de Pago de las Agencias de Viajes Figura 6. Diagrama de Flujo Transacciones Agencia de Viajes METODO: leeraerolineas() OBJETO: AerolineaWS METODO: solicitarautorizacionta( SolicitudAutorizacionTAWS ) OBJETO: SolicitudAutorizacionTAWS OBJETO: AutorizacionTAWS Otros Objetos Disponibles OBJETO: TarjetaCreditoWS OBJETO: PagosonlineWSFault CAPITULO 4 Pruebas Pruebas con Tarjetas de Crédito:

5 4.2 Pruebas con PSE: CAPITULO 6. Como revisar las transacciones en nuestro sistema CAPITULO 7. Como pasar a producción ANEXOS A1. Códigos de las franquicias para enviar a Pagosonline A2. Estados de las transacciones en Pagosonline A3. Códigos de respuesta de Pagosonline (codigorespuesta) A4. Estados de las solicitudes de pago recurrente A5. Medios de Pago A6. Tipo Medio de Pago A7. Códigos VISA de las aerolíneas A7 Divisas admitidas A8 Tipo de documento para PSE GLOSARIO

6 CAPITULO 1. Descripción de la aplicación Pagosonline ofrece un WebService que permite procesar pagos con: Tarjetas de Crédito - Pagos recurrentes: PSE (cuentas de ahorro y corrientes): Pago Referenciado o formato de pago con Código de barras: El comercio puede desarrollar una aplicación en cualquier lenguaje de programación que soporte WebServices (Java, PHP, MS.NET), de igual forma el hosting del comercio, debe soportar esta tecnología. 6

7 Se utilizan diferentes recursos para garantizar la seguridad de la comunicación entre los usuarios y Pagosonline: Confidencialidad de la información: Utilizamos SSL; de esta forma la información viaja cifrada por el protocolo HTTPS. Integridad de la información: Utilizamos WS-Security; todos los mensajes contienen una firma digital, de tal forma que se puede detectar si el mensaje fue modificado luego de ser enviado por el cliente. En tal caso, se rechaza la petición. Autenticidad de la información: Utilizamos dos mecanismos; 1) WS-Security: se verifica que la firma digital sea de confianza. 2) Pagosonline puede saber cuáles son las cuentas que están autorizadas para cada firma digital. De esta forma, aunque un cliente tenga una firma digital autorizada, no podrá solicitar peticiones relacionadas a cuentas que no le pertenecen. Todos los aspectos de seguridad aplican tanto para los mensajes que van del cliente a Pagosonline como para los mensajes de respuesta de Pagosonline al cliente. En la integración con WebService, la captura de datos para realizar la transacción se realiza en el sitio web del comercio, por lo tanto debe brindar la seguridad necesaria para la captura y envío de los datos hacia Pagosonline; Por lo cual deberá tener un tipo de autentificación e implementar el certificado SSL para el formulario de tarjetas de crédito, provisto por una autoridad certificadora. Para la utilización del WebServices de Pagosonline pueden implementarse dos tipos de autenticación y dependiendo de la tecnología de desarrollo utilizada así: Tipo de autenticación Tecnología Filtrado JAVA MS.NET PHP Username Token X X SI Username Token con TimeStamp X SI Según la tecnología que se desee usar se deben tener las siguientes herramientas: JAVA MS.NET PHP AXIS 1.2 WSS4J.JAR WSDL4J.JAR Visual Studio 2005 / 2008 WSE 3.0 NUSOAP 7

8 CAPITULO 2. Como obtener los datos de acceso al WebServices Para cualquier tipo de integración lo primero que debe hacer el Comercio, es obtener una cuenta con Pagosonline, de esta forma obtendrá una identificación única para el Comercio ante Pagosonline (usuarioid), esta permitirá la autenticación con el WebServices, al usar UsernameToken, también para el consumo de algunos métodos obtendrá una cuentaid, la cual se utiliza como parámetro adicional. Tan pronto se crea una cuenta en Pagosonline se envía un correo electrónico con el número del usuario y datos para ingresar al modulo administrativo, sin embargo esta cuenta no tendrá acceso al sistema de pruebas inmediatamente, debido a procedimientos internos que se deben ejecutar antes de realizar pruebas. Para ingresar al modulo administrativo en producción debe entrar a la siguiente URL: Una vez ingrese a este módulo debe entrar a la pestaña Opciones, donde visualizará la Llave para realizar encripciones, la cual usará en las páginas de Confirmación y Respuesta, las cuales se explican más adelante. 8

9 Si ha perdido la contraseña, podrá volver a adquirirla oprimiendo en Olvidó su clave? allí digitará el usuario de acceso (generalmente este usuario es el correo que se registro en el sistema de Pagosonline al adquirir su cuenta). Y pulsamos en el botón Enviar Tan pronto haga este paso recibirá un correo, a veces puede ir al correo no deseado por lo tanto debe revisarse esta carpeta también. En este correo encontrará un enlace para activar la clave que fue enviada en este correo, como se ve a continuación: 9

10 Nota Importante: Una vez se inicie el contacto técnico, podrán solicitar a su ingeniero asignado la configuración del usernametoken para iniciar las pruebas. Al realizar la activación, podremos usar la nueva contraseña que fue enviada al correo. El sistema nos pedirá actualizar la contraseña. Para que esta nueva contraseña sea permitida debe cumplir unos requisitos mínimos, sabremos que los cumplimos cuando en la parte inferior del campo de texto haya una barra verde con la descripción Fuerte. Por facilidad podemos agregarle a la contraseña que recibimos algunos caracteres. Ejemplos de claves validas teniendo en cuenta que la recibida en el correo fue: X0GMILP@rnP$uo1 X0GMILP@rnP$uoabc X0GMIL@rnP$uopruebas ABC! #abc123 Para ingresar al modulo administrativo en el ambiente pruebas debe solicitar de nuevo una contraseña, la cual es diferente a la anterior. Esto le permitirá revisar las transacciones realizadas en modo de prueba. 10

11 CAPITULO 3. Descripción y Uso de Métodos A continuación, se describen los métodos básicos para desarrollar un cliente WebServices. Muchos desarrolladores experimentados en WebServices pueden realizar la aplicación de cualquier forma, siempre y cuando cumpla algunos requisitos básicos. En el capítulo 4, explicaremos cómo realizar pruebas con todos los medios de pago disponibles en nuestra plataforma. En el capítulo 5, como revisar las transacciones desde el panel administrativo, y verificar que las transacciones de prueba se estén realizando bien. En el capítulo 6, se explica cómo pasar a producción. Para iniciar con el proceso de integración puede realizar los siguientes pasos principales: 1. Obtener la estructura WSDL que describe los métodos y objetos publicados por el WebService. El archivo se encuentra alojado en las siguientes direcciones dependiendo de la tecnología que se utilice: Tecnología MS.NET con UsernameToken JAVA o PHP con UsernameToken Url Generar el esqueleto de la aplicación a partir del archivo WSDL (Dependiendo del lenguaje usado se implementa de formas diferentes). 3. Modificar el esqueleto generado para implementar la seguridad con WS-Security, para UsernameToken (Este paso generalmente aplica solo en JAVA) 4. Utilizar el servicio. Crear los objetos con los datos de la petición y recibir los objetos de respuesta (Para MS.NET y JAVA se genera de forma automática esta estructura). 11

12 3.1 Descripción de los métodos y objetos disponibles para los diferentes medios de pago A partir de aquí, explicaremos cada uno de los métodos disponibles, y los diferentes medios de pago donde se deben utilizar. Inicialmente, se utiliza un sencillo método para verificar la comunicación entre el cliente que se está desarrollando y el WebService de Pagosonline. METODO: getversion() Es un método sencillo, que retorna una cadena con la versión actual del WebServices Pagosonline. Sirve para probar que la conexión está funcionando de manera adecuada. Retorna: Una cadena con la versión actual del sistema. En caso de ocurrir un error retorna un mensaje informando sobre el error. Luego de verificar que la comunicación funciona correctamente, se debe proceder a leer los medios de pago disponibles para el comercio. Los medios de pago disponibles para cada comercio varían de acuerdo a los convenios que dicho comercio haya hecho con las entidades correspondientes para cada uno de los medios de pago mencionados Métodos WebServices Y Objetos METODO: leermediospagoactivos( usuarioid ) Este método permite consultar los medios de pago activos que tiene un cliente. De esta forma se puede saber que opciones de pago mostrarle al comprador. Retorna: Un arreglo de objetos de la clase MedioPagoWS con los datos de cado uno de los medios de pago disponibles para el usuario. 12

13 Lanza: Una excepción PagosonlineWSFault en caso de que no sea posible consultar los medios de pago activos asociados al identificador del usuario. OBJETO: MedioPagoWS Este objeto representa un medio de pago en el sistema. Se utiliza principalmente para determinar qué medios de pago activos tiene su comercio. Este objeto tiene el campo tipomediopagoid que indica a qué tipo de medio de pago pertenece (Tarjetas de crédito, PSE, Referenciado), el campo mediopagoid que indica a cual es el medio de pago (Visa, Mastercard, PSE, etc..) y por último la descripción. Los valores que pueden tomar los campos mediopagoid y tipomediopagoid se describen en los Anexos A5 y A6 respectivamente. Estructura: Campo Tipo Descripción mediopagoid N El identificador del medio de pago. Anexo A5 tipomediopagoid N El identificador del tipo de medio de pago. Anexo A6 descripcion A La descripción del medio de pago. A través de la integración WebServices se pueden implementar diferentes medios de pago, tarjetas de crédito, PSE y Pago Referenciado Código de barras Métodos para consulta de transacciones A continuación se describen los diferentes métodos para verificar el estado de las transacciones. Generalmente estos métodos son utilizados para consultar constantemente transacciones que queden en estado de validación o pendiente, también en caso de que no se utilice una página de confirmación en el sitio web del Comercio. 13

14 METODO: consultarestadotransaccion( cuentaid, transaccionid ) Este método nos permite consultar los diferentes estados de una transacción (ver Anexo A2), siempre y cuando se conozca la transaccionid, que es generada por Pagosonline en el objeto de retorno EstadoTransaccionWS. Y solo permite solicitar una transacción por llamado al WebService Pagosonline. Parámetros de entrada: Campo Tipo Descipción cuentaid N Cuenta secundaria para acceso a WebServices transaccionid N Identificador de cada Transacción que entra a Pagosonline, la cual es generada Internamente por nuestro sistema. Retorna : Objeto de tipo EstadoTransaccionWS, contiene todos los datos de la transacción solicitada (referencia, valor, iva, etc..) OBJETO: EstadoTransaccionWS En este objeto se contiene toda la información de la transacción solicitada (referencia, valor, IVA, etc ). Estructura Campo Tip Descripción transaccionid N El número (id) de la transacción en Pagosonline. cuentaid N El número (id) de la cuenta del usuario en Pagosonline. estadoid N El estado en el que se encuentra la transacción (Anexo A4). Referencia A La referencia de la solicitud de pago correspondiente. codigorespuesta N El código de respuesta de Pagosonline (Anexo A3). codigoautorizacion N El código de autorización generado por el banco. riesgo* N El índice de riesgo de la solicitud (0 bajo - 1 alto). Valor N El valor de la transacción. Iva N El valor del IVA de la transacción. basedevolucioniva N El valor de la base de devolución del IVA de la transacción valoradicional N El valor adicional de la transacción. codigoaerolinea N El código de la aerolínea según el Anexo A6. extra1 A El primer campo libre. Extra2 A El segundo campo libre. fechaprocesamiento F La fecha de procesamiento de la transacción. codigoerror* N El código que identifica el error ocurrido (dado el caso). mensajeerror** A El mensaje del error ocurrido (dado el caso). *Aplican cuando ocurre algún error procesando la solicitud de pago. ** Tiene sentido si se validó por el módulo anti fraude, de otro modo siempre es 0. 14

15 3.1.3 Métodos de consulta por referencia: Cuando se emplean métodos de consulta de transacciones por referencia, es importante tener en cuenta que cada referencia puede estar relacionada a una o más transacciones con estados diferentes; este caso puede suceder cuando el comercio permite reintentos de pago, con la misma referencia, por ejemplo: referencia Transacciones Descripción Ref_001 transaccionid estado Desc Abierta Cancelada Validación En este caso, cuando obtenemos el estado de la transacción en validación, también obtenemos la transaccionid, por lo tanto es necesario consultar recurrentemente esta transacción usando este método, hasta obtener un estado final. Ref_002 Ref_003 transaccionid estado Desc Abierta Cancelada Rechazada Rechazada Pagada y Abonada transaccionid estado Desc Abierta Pagada y Abonada Pagada y Abonada En esta observamos que de las transacciones hay una en estado 4, por lo tanto, esta referencia no tendrá más transacciones asociadas, y podremos actualizar la base de datos de nuestro comercio. Este caso nunca se va a presentar, debido a que solo puede existir una transacción aprobada relacionada a una misma referencia. Por lo tanto, siempre que usemos estos métodos, se debe verificar todas las transacciones relacionadas. (Ver Anexo A2). METODO: consultarsolicitudesporreferencia( cuentaid, referencia ) Con este método podemos consultar una transacción por la referencia, la cual es generada del lado del comercio. Es muy útil en casos que se pierda comunicación con el WebServices Pagosonline, por cualquier motivo, por lo tanto no se tiene la transaccionid. Hay que tener en cuenta que solo permite consultar una solicitud por llamado al WebService Pagosonline. Parámetros de entrada: Campo Tipo Descripción cuentaid N Cuenta secundaria para acceso a WebServices Referencia A Referencia de venta, la cual es generada por el Comercio, y debe ser única para cada transacción enviada a Pagosonline. 15

16 Retorna: Arreglo de objetos de la clase EstadoTransaccionWS[]. En este arreglo se retornan varios objetos, que corresponden a todas las transferencias asociadas a la referencia enviada, con toda la información de cada transacción ( valor, iva, etc..). METODO: obtenerestadotransacciones( usuarioid,xml ) Con este método se puede consultar el estado de máximo 10 transacciones usando la referencia de cada una y en un solo llamado al WebServices. A diferencia de los métodos anteriores, este nos trae como resultado una estructura XML, con datos básico para identificar el estado actual de cada transacción. Estructura: Campo Tipo Descripción usuarioid N Cuenta principal para acceso a webservices xml N Variable de tipo String con una estructura XML Retorna: Un objeto de tipo String con una estructura XML, la cual puede ser leída del lado del comercio para identificar el estado de todas las transacciones solicitadas. Estructura XML a enviar en el método: <consultar-estado-por-referencias> <referencia>referencia_1</referencia> <referencia>referencia_2</referencia>... <referencia>referencia_n</referencia> </consultar-estado-por-referencias> OBJETO: XML Un objeto de tipo String con una estructura XML, la cual está descrita debajo y con la que se puede identificar el estado de todas las transacciones solicitadas. Solo si la referencia solicitada existe, la obtendremos en la estructura <solicitud> 16

17 Estructura: <respuesta> <fecha></fecha> <codigo-respuesta></codigo-respuesta> <codigo-error></codigo-error> <mensaje-error></mensaje-error> <!--solo si la referencia existe en el sistema de pagosonline --> <solicitudes> <solicitud> <id></id> <referencia></referencia> <codigo-respuesta-solicitud></codigo-respuesta-solicitud> <estado></estado> </solicitud> </solicitudes> </respuesta> Descripción de etiquetas Etiqueta fecha codigo-respuesta codigo-error mensaje-error id referencia codigo-respuesta-solicitud estado Descripción Una fecha en formato: yyyy-mm-dd o HH:mm:ss código exitoso:1 / código fallido:2 código indeterminado: 5000, contacte a Pagosonline El mensaje de error asociado. El Id de la transacción en Pagosonline. Esta es la misma variable ref_pol enviada en las páginas de confirmación y respuesta (en integración tradicional). Esta es la misma variable refventa enviada a Pagosonline o la misma ref_venta enviada a la página de confirmación y respuesta (en integración tradicional). Esta variable está codificada de la misma forma que la variable codigo_respuesta_pol. Referirse a la tabl, ver Anexo A3. El id para el estado de la transacción en Pagosonline. Esta variable está codificada de igual forma que la variable estado_pol, ver Anexo A2. 17

18 3.1.4 Cuando usar los métodos de consulta Estos son los casos más relevantes en los cuales se deben usar el llamado de los métodos de consulta: Caso Método Propósito Una transacción queda en validación. consultarestadotransaccion En este caso si sabemos que la transacción queda en validación, es porque también estamos obteniendo la transaccionid, por lo tanto es necesario consultar recurrentemente esta transacción usando este método, hasta obtener un estado final. En caso de ocurrir esta situación por cualquier circunstancia, existe la posibilidad que el WebServices sí haya procesado nuestra solicitud de pago, por lo tanto, el único dato que tenemos para verificar esto es la referencia, por lo que podemos usarla con este método, y conocer el estado que tenga en el momento de Se pierde comunicación con el WebServices Pagosonline, mientras se envía una transacción. consultarsolicitudesporreferencia consultarla, o en caso contrario, verificar que la transacción no llegó al WebServices. Teniendo en cuenta, que en el Objeto de respuesta podemos conocer la transaccionid y usar el método consultarestadotransaccion, para hacerle un seguimiento a la transacción rápidamente Paginas de Respuesta y Confirmación: En esta sección explicaremos que son las páginas de Respuesta Y Confirmación, las cuales son de uso Opcional y dependiendo del tipo de pago que se va a realizar pueden ser Obligatorias. Para un mayor entendimiento de estas dos páginas recomendamos revisar el manual de Integración Tradicional en nuestro Portal de ayuda donde encontrará como usar la llave de encripcion, para mejorar la seguridad de estas páginas. Página de Respuesta: Esta es una página de carácter informativo, la cual se muestra al usuario al terminar un pago. Es obligatoria en pagos PSE, la cual debe cumplir con los requisitos para la certificación de ACH. Debido que estos pagos se hacen dentro de los portales de las entidades bancarias, y nuestro WebServices no controla el proceso que realiza el usuario en estos sitios, tan solo al terminar o cancelar un pago, la entidad bancaria retorna al usuario a la URL que el comercio configure como página de respuesta, recibiendo una trama de datos por método GET que envía el banco. 18

19 PÁGINA DE RESPUESTA DE EJEMPLO Página de confirmación: Esta es una página totalmente funcional, que se debe usar para confirmar el resultado de las transacciones, por lo tanto es útil para actualizar la Base de datos, y obviamente no es visible para los usuarios, es decir es de uso exclusivo entre Pagosonline y el Comercio, como por ejemplo, cuando una transacción queda en validación o en espera por la entidad bancaria, al momento que Pagosonline obtiene una respuesta definitiva (Rechazada / Pagada y Abonada), la página de confirmación es consumida y se envía una trama de datos por método POST. Debe tener en cuenta que esta página debe estar en acceso público. 19

20 3.1.6 Proceso de Pagos con Tarjeta de Crédito Figura 2: Diagrama de Flujo pagos con Tarjeta de Crédito COMERCIO leermediospagoactivos( )* 1 Captura datos de tarjeta 2 MedioPagoWS [ ] WebServices PagosOnLine solicitarautorizacion( ) 3 4 AutorizacionWS [ ] Pág. Respuesta CONNECT TO INSERT INTO UPDATE FROM 5 HTTP POST Página de confirmación 6 7 Correo confirmación Comercio Correo confirmación Comprador CRON JOB 9 (Método de consulta estado Transacción)* (Estado de la transacción)** [ ] 8 *Dependiendo del caso, se usa un método de consulta diferente. ** Dependiendo del método usado para consultar la transacción, traerá un objeto diferente. 20

21 Para implementar el pago con tarjeta de crédito, inicialmente (1) se deben leer los medios de pago disponibles, (2) de esta petición recibirá todos los medios de pago activos para el comercio. Luego se deben enviar los datos de la transacción (referencia, valor, IVA, etc ) de la transacción al WebServices de Pagosonline (3). La transacción es procesada y se devuelve una respuesta inmediata (4), permitiendo al comercio realizar las actualizaciones de bases de datos que necesite, y mostrándole al comprador una página de respuesta que puede ser personalizada de acuerdo a las necesidades del comercio; pero no en todos los casos, esta respuesta es definitiva, en algunas ocasiones la transacción queda en proceso de validación y requiere de un tiempo mayor para procesarse y tener una respuesta definitiva. Luego que se resuelve la transacción, existen dos métodos para informar al comercio sobre el estado final: 1. PagosOnLine envía al comercio el estado final de la transacción por medio de una página de confirmación (5), lo cual es opcional. En este caso, el comercio debe tener una página de confirmación con una URL pública, la cual recibe la trama de datos, de la transacción procesada, que envía Pagosonline por método POST, y en esta, se debe hacer todo el proceso de actualización de bases de datos que requiera el comercio (Para mayor información del uso de la página de confirmación, remítase al manual de Integración Tradicional). 2. El comercio puede consultar las veces necesarias en nuestro sistema el estado de la transacción (8), e inmediatamente recibe el estado en el momento de la consulta (9), el cual puede mantenerse en validación por un periodo prolongado, hasta llegar al estado definitivo, de aprobada o rechazada. Luego del proceso de pago, se envía un correo automáticamente, al comercio para todas las transacciones (6) y al cliente, siempre y cuando se envía el del comprador (7), con la información del estado final de la transacción. Esta funcionalidad es opcional, según las necesidades del comercio. 21

22 Descripción de métodos para el pago con tarjeta de crédito. METODO: solicitarautorizacion( solicitudautorizacionws ) Es el método principal para tarjetas de crédito, que permite enviar la solicitud de pago y recibir la respuesta de Pagosonline. Recibe como parámetro un objeto SolicitudAutorizacionWS y retorna un objeto AutorizacionWS. Este objeto de retorno, contiene el atributo codigorespuesta, el cual identifica el estado de la transacción, (ver Anexo A3). En algunos casos, al realizar una solicitud de pago, es posible que el proceso se demore mientras se realiza la validación de los datos de la tarjeta de crédito, ya sea en la misma franquicia o en el módulo anti fraude de Pagosonline. Para tales casos, se retorna una autorización con el código de respuesta '15', como transacción en proceso de validación. Posteriormente, se puede examinar el estado de la transacción (con el método consultarestadotransaccion()) para verificar si ya se terminó de validar la solicitud de pago. (Ver Anexo A1) Parámetros de entrada Parámetro solicitudautorizacion Descripción El objeto que contiene los datos necesarios para solicitar la autorización de la transacción. Retorna: objeto AutorizacionWS que contiene los datos de la autorización. OBJETO: SolicitudAutorizacionWS Este objeto contiene todos los datos de la solicitud de pago, entre los cuales están el número (usuarioid) de la cuenta del usuario en Pagosonline, los datos de descripción del pago (referencia, valor, IVA, etc ), los datos del cliente (nombre, documento, teléfono, etc ), los datos de la tarjeta de crédito (franquicia, número, etc ) y algunas opcionales (validar anti fraude, reportar confirmación). A continuación se muestra una tabla que describe todos los campos, en la tabla se indica cuáles campos son requeridos y cuáles no, sin embargo, se debe enviar la mayor cantidad de datos que sea posible. 22

23 Estructura: Campo Tam. Req. Descripción cuentaid 12 SI El número (ID) de la cuenta del usuario en Pagosonline. referencia 50 SI La referencia de la venta, debe ser única por cada solicitud de pago. descripcion 255 SI La descripción de la venta. valor 14,2 SI El valor total de la venta. iva 14,2 SI El valor del IVA de la venta. basedevolucioniva 14,2 SI El valor de la base de devolución del IVA de la venta. valoradicional 14,2 NO El valor adicional de la venta. isomoneda SI El código ISO de la moneda. numerocuotas 2 SI El número de cuotas. nombrecomprador 50 NO El nombre del comprador. documentoidentificacion 25 NO El documento de identificación del comprador. comprador 255 SI El correo electrónico del comprador. telefono 50 NO El teléfono nocturno del comprador. telefonooficina 50 NO El teléfono diurno del comprador. paiscorrespondencia 2 NO El código ISO del país de la dirección de correspondencia. ciudadcorrespondencia 25 NO La ciudad de la dirección de correspondencia. direccioncorrespondencia 255 NO La dirección de correspondencia de la tarjeta de crédito. paisenvio 2 NO El código ISO del país de la dirección de envío. ciudadenvio 25 NO La ciudad de la dirección de envío. direccionenvio 255 NO La dirección de envío de la mercancía. ipcomprador SI La dirección IP del comprador. cookie NO La cookie del navegador del comprador. useragent NO El agente del navegador del comprador. franquicia SI El nombre de la franquicia ver Anexo A5, descripción Ejemplo : VISA codigoaerolinea** 2 NO El código de la aerolínea según el Anexo A6. extra1 255 NO El primer campo libre. extra2 255 NO El segundo campo libre. numero SI El número de la tarjeta de crédito. codigoseguridad SI El código de seguridad para tarjetas de crédito Mastercard. Para el resto de tarjetas, se debe enviar el valor en NULL nombretarjetahabiente 50 SI El nombre del dueño de la tarjeta de crédito, tal y como aparece en la misma. fechaexpiracion 20 SI La fecha de expiración de la tarjeta de crédito (AAAA/MM ejemplo 2010/01). validarmoduloantifraude NO Si se quiere utilizar el módulo antifraude para validar la solicitud de pago. reportarpaginaconfirmacion 255 NO Si se quiere reportar el resultado de la transacción a la página de confirmación del usuario. ** Este campo es obligatorio para Agencia de Viajes y Aerolíneas, si no se envía la franquicia no hará el cargo al tarjetahabiente por el valor adicional. 23

24 OBJETO: AutorizacionWS Este objeto contiene la respuesta de Pagosonline generada luego de enviar una solicitud de pago. Contiene la referencia de la solicitud de pago, el número (ID) de la transacción en Pagosonline, los códigos de respuesta (de POL y del banco) y otros datos. A continuación se muestra una tabla que describe todos los campos. Campo Tam. Descripción Referencia 50 La referencia de la solicitud de pago correspondiente. transaccionid El número (ID) de la transacción en Pagosonline codigorespuesta 2 El código de respuesta de Pagosonline (Ver Anexo A3). codigoautorizacion 6 El código de autorización generado por el banco. riesgo 12 El índice de riesgo de la solicitud (0 bajo - 1 alto). (Sí se valida por el modulo anti fraude) Valor 12 El valor de la transacción. Iva 12 El valor del IVA de la transacción. basedevolucioniva 14,2 El valor de la base de devolución del IVA de la transacción. valoradicional 14,2 El valor adicional de la transacción. codigoaerolinea 2 El código de la aerolínea según el Anexo A6. extra1 255 El primer campo libre. extra2 255 El segundo campo libre. fechaprocesamiento 20 La fecha de procesamiento de la transacción. codigoerror** mensajeerror** El código que identifica el error ocurrido (dado el caso). El mensaje del error ocurrido (dado el caso). ** Aplican cuando ocurre algún error procesando la solicitud de pago. 24

25 3.1.7 Proceso de Transacciones con PSE Figura 3: Diagrama de Flujo pagos con PSE leermediospagoactivos( )* 1 2 MedioPagoWS [ ] Lista de bancos leerbancospse( ) BancoPseWS [ ] 3 WebServices PagosOnLine 4 iniciartransaccionpseconinformacionadicional ( ) TransaccionPseWS usuarioid psereferencia1.. urlpaginapagosbanco 6 TransaccionPseConInformacionAdicionalWS Redirect HTTP POST urlpaginapagosbanco 7 5 Página de respuesta 8 Redirect HTTP GET Pág. Respuesta (Comprobante de pago) CONNECT TO INSERT INTO UPDATE FROM 9 HTTP POST Página de confirmación Correo confirmación Comercio Correo confirmación Comprador CRON JOB 13 (Método de consulta estado Transacción) (Estado de la transacción) [ ] 12 25

26 * El método leermediospagoactivos() debe ser llamado una vez al día, con el fin de minimizar el uso de los recursos del servidor, en el arreglo de objetos devueltos por este método se especifican todos los métodos de pago activos y estos serán los que se despliegan en la pagina del cliente. Para realizar transacciones con cuentas de ahorro o corrientes, se debe invocar inicialmente el método (1) leermediospagoactivos(), y verificar que efectivamente se tiene activo el medio de pago PSE (Ver Anexo A5). Luego se debe leer la lista de bancos del sistema PSE (3) y se prosigue con el desarrollo normal del proceso como se describió para tarjetas de crédito. Para utilizar este medio de pago es importante tener en cuenta que se debe hacer una certificación del sitio web ante ACH. (Remitirse al manual de certificación PSE) Descripción de métodos para el pago con PSE. METODO: leerbancospse( usuarioid ) Se utiliza para obtener la lista de todos los bancos que permiten pagos con cuentas corrientes y de ahorro a través del sistema PSE. La lista contiene objetos de tipo BancoPseWS. Parámetros de entrada: Parámetro Tipo Descripción usuarioid N El identificador de la cuenta del usuario en el sistema. Retorna: Un arreglo de objetos BancoPseWS[] con los datos de cada uno de los bancos disponibles para realizar el pago. Lanza: Una excepción PagosonlineWSFault en caso de que no sea posible consultar la lista de bancos. OBJETO: BancoPseWS Este objeto contiene los datos básicos de los bancos habilitados, para pagos con PSE. A continuación se muestra una tabla que describe todos los campos del objeto. 26

27 Estructura: Campo Tipo Descripción codigopse N El código del banco en PSE. descripción A El nombre del banco. METODO: iniciartransaccionpseconinformacionadicional (TransaccionPseConInformacionAdicionalWS) Es el método principal para realizar pagos con cuentas corrientes o ahorro y permite iniciar una transacción por medio de PSE. Recibe como parámetro de entrada un objeto de la clase TransaccionPseConInformacionAdicionalWS y retorna un objeto del mismo tipo con los datos actualizados. Si se pudo iniciar la transacción satisfactoriamente, el objeto retornado contiene la URL del banco a la cual se debe direccionar el comprador para que continúe el proceso de pago. Posteriormente, se puede examinar el estado de la transacción (con el método consultarestadotransaccion() ) para ver si ya se terminó de procesar la solicitud de pago. Parámetro TransaccionPseWs Descripción El objeto que contiene los datos necesarios para iniciar una transacción con PSE dentro de los cuales se encuentra el código del banco y el tipo de cliente. Retorna: El objeto TransaccionPseConInformacionAdicionalWS con los datos actualizados para poder realizar la transacción directamente en el banco. Lanza: Una excepción PagosonlineWSFault en caso de que no sea posible iniciar la transacción PSE. OBJETO: TransaccionPseConInformacionAdicionalWS Este objeto contiene todos los datos de la solicitud de pago con cuentas de ahorro o corriente, que se va a enviar a Pagosonline, entre los cuales están el número (ID) de la cuenta del usuario en Pagosonline, los datos de descripción del pago (referencia, valor, IVA, etc ), los datos del comprador (nombre, documento, teléfono, etc ), el código del banco en PSE y otros datos. A continuación se muestra una tabla que describe todos los campos. 27

28 Estructura: Campo Tam. Req. Descripción usuarioid 12 SI El número (id) del usuario en Pagosonline. cuentaid 12 NO El número (id) de la cuenta del usuario en Pagosonline. referencia 50 SI La referencia de la venta, debe ser única por cada solicitud de pago. descripción 255 SI La descripción de la venta. valor 12 SI El valor total de la venta. iva 12 El valor del IVA de la venta. comprador 255 SI El del comprador. direccionipcomprador 255 SI La dirección IP del comprador. nombrecomprador 255 SI El nombre del comprador telefonocomprador 255 SI El teléfono del comprador cookie SI La cookie del comprador. agentenavegador SI El agente del navegador del comprador. urlrespuesta 255 SI La página adonde se debe enviar al comprador después de finalizada la transacción. urlconfirmacion 255 SI La página de confirmación adonde se debe enviar la información del pago. extra1 255 NO El primer campo extra. extra2 255 NO El segundo campo extra. codigobancopse SI El código del banco PSE. tipocliente SI El tipo de cliente. N si es natural y J si es jurídico. id NO* El número (id) de la transacción en Pagosonline. codigopse NO* El código PSE de la transacción. urlpaginapagosbanco 255 NO* La URL a donde debe ser direccionado el usuario psereferencia1 SI IP pública del comprador ejemplo : psereferencia2 SI Tipo de documento ( Cedula, Tarjeta de identidad, ect ver Anexo A8) psereferencia3 SI Documento de identidad ( sin guiones o punto, solo numérico ) * Estos campos son enviados por Pagosonline, en la respuesta al método iniciartransaccionpseconinformacionadicional() Finalmente si se desea, se puede consultar el estado de la transacción, utilizando el método consultarestadotransaccion(), descrito anteriormente. 28

29 3.1.8 Proceso de pago con Pago Referenciado Figura 4: Diagrama de Flujo pagos con Pago Referenciado COMERCIO leermediospagoactivos( ) MedioPagoWS [ ] Código de Barras WebServices PagosOnLine solicitarautorizacionpagoreferenciado( ) AutorizacionPagoReferenciado[ ] El pago referenciado es el pago que se realiza a través de un formato con código de barras. Para implementar este medio de pago, se requiere iniciar leyendo los medios de pago y validar que se tenga activo este medio de pago, luego se debe generar la transacción y Pagosonline devuelve la URL del comprobante de pago que el usuario deberá imprimir y acercarse a pagar en la entidad bancaria correspondiente. Es importante aclarar que para los pagos realizados con Pago Referenciado, el sistema de Pagosonline no realiza ningún tipo de confirmación, ya que las entidades bancarias no nos informan cuando se hacen efectivos los pagos. Para que los datos de las transacciones realizadas por este medio de pago estén actualizados en el modulo administrativo de Pagosonline ( se debe subir el reporte Aso-bancaria que genera su banco. Es posible que luego de subir este reporte, se deba consultar el estado de las transacciones, para actualizar el estado final. 29