TABLA DE CONTENIDO 1. INTRODUCCIÓN 2 2. DESCRIPCIÓN 3 3. PROCESO DE INTEGRACIÓN 5 4. PÁGINA DE RESPUESTA PÁGINA DE CONFIRMACIÓN 19

Transcripción

1 VERSIÓN 3.1

2 TABLA DE CONTENIDO Pág. 1. INTRODUCCIÓN 2 2. DESCRIPCIÓN 3 3. PROCESO DE INTEGRACIÓN Página de Envío de la Información Cálculo de la base de Devolución Generación de las firmas digitales Ejemplo de generación de las firmas digitales en PHP Ejemplo de generación de las firmas digitales en JAVA Ejemplo de generación de las firmas digitales en ASP.NET PÁGINA DE RESPUESTA Ejemplo en PHP para capturar variables de URL de respuesta Ejemplo en JAVA para capturar variables de URL de respuesta Ejemplo en ASP.NET para capturar variables de URL de respuesta PÁGINA DE CONFIRMACIÓN Ejemplo en PHP para capturar variables de URL de respuesta Ejemplo en JAVA para capturar variables de URL de respuesta Ejemplo en ASP.NET para capturar variables de URL de respuesta ERRORES MÁS FRECUENTES MÓDULO DE AGENCIAS DE VIAJES PRUEBAS PRUEBAS CON TARJETA DE CRÉDITO PRUEBAS A TRAVÉS DE PSE CERTIFICACIÓN PSE (SOLO PLAN EMPRESARIAL) 27 ANEXOS 32 I) Divisas admitidas 32 II) Idiomas admitidos 32 III) Parámetros adicionales para página de pago 33 IV) Estados posibles de transacciones (estado_pol) 34 V) Códigos de Respuesta (codigo_respuesta_pol) 35 VI) Tipos de Medio de Pago (tiposmediosdepago, tipo_medio_pago) 36 VII) Medio de Pago (medio_pago) 36 VIII) Parámetros adicionales para página de confirmación 37 IX) Preguntas frecuentes 37 X) GLOSARIO 40

3 1. INTRODUCCIÓN Para poder aceptar pagos con tarjetas débito y crédito a través de Pagosonline.net usted debe conectar su página de Internet con nuestro sistema transaccional. A este proceso lo denominamos "integración". Una vez finalizado, usted podrá recibir pagos desde cualquier parte del mundo, en diferentes monedas e idiomas, utilizando nuestro módulo Antifraude y la última tecnología para garantizar la seguridad y confiabilidad de las transacciones. La Guía de integración estándar para Pagos desde su sitio Web proporciona información sobre la mayoría de las funciones de Pagosonline.net, así como explicaciones de cómo utilizarlas para cubrir sus necesidades de pago en Internet. Utilice la Guía de integración estándar para: Configurar de manera rápida y sencilla la funcionalidad del comercio electrónico con Pagosonline.net. Por ejemplo, aprenda a integrar Pagosonline.net en su sitio Web en cuestión de minutos con los botones de pago utilizando formularios HTML. Conocer técnicas y herramientas más avanzadas para sacar el máximo partido a los servicios provistos por Pagosonline.net. Conocer que información debe enviar a, y recibir de Pagosonline.net. Entender qué ven los compradores al momento de pagar dentro de Pagosonline.net. Por ejemplo, revise qué significa para un nuevo comprador pasarela de pagos. Conocer el funcionamiento de Pagosonline.net para visualizar mejor el flujo de los Pagos. Revisar las soluciones y buenas prácticas recomendadas. La Guía de integración estándar incluye información e instrucciones del uso de las siguientes funciones: Páginas de pago, respuesta y confirmación Envío y manipulación de información Divisas o tipos de moneda admitidas Tipos de Medio de Pago Idiomas permitidos Nota: Para conocer otras formas de integración y funcionalidades como por ejemplo, pagos recurrentes, por favor comuníquese con el área de soporte técnico en Pagosonline.net o acceda a nuestro foro: 2

4 2. DESCRIPCIÓN Figura 2.1. Flujo de una transacción típica. Para comprender la validación manual consulte el Anexo IX El comprador entra a la página del comercio y selecciona los productos y/o servicios que desea adquirir. (1) El comercio totaliza el valor de la compra y genera una trama que es enviada al sistema transaccional de Pagosonline.net por medio de una petición POST. (2) El sistema transaccional valida la trama, captura la información en caso de tratarse de una tarjeta de crédito y envía los datos a la entidad bancaria. (3) La entidad bancaria procesa la transacción y retorna una respuesta al sistema transaccional de Pagosonline.net (4) El sistema envía al comprador de nuevo a la página del comercio, utilizando la Página de Respuesta, esta incluye la información actual de la transacción. En el momento que se procese dicha transacción se envía la respuesta final a la Página de Confirmación. 3

5 Nota: Estas páginas, Respuesta y Confirmación se describen en detalle en capítulos posteriores. Pagosonline.net cuenta con un módulo Antifraude que utiliza las últimas técnicas de inteligencia artificial para evaluar las transacciones, dependiendo de las opciones de configuración del comercio y del factor de riesgo asociado a una transacción, puede enviar la transacción a un proceso de validación manual, retardando el envío de la información a la entidad bancaria mientras se corrobora la autenticidad de la transacción. Cuando esto sucede el sistema envía al comprador a la Página de Respuesta, indicando que la transacción se encuentra en proceso de validación. Importante El proceso de integración estándar está enfocado a los pymes y personales, si usted posee una cuenta empresarial o corporativa y/o está utilizando convenios propios es necesario realizar ajustes adicionales para la certificación ante ACH y así poder recaudar con tarjetas débito, cuentas corrientes o cuentas de ahorro. Por favor consulte con su asesor comercial o directamente con el área de soporte técnico en Pagosonline.net. 4

6 3. PROCESO DE INTEGRACIÓN La utilización de Pagosonline.net requiere el desarrollo de una página dinámica y dos páginas dinámicas opcionales: La página de Envío de datos, y la página de Respuesta y la página de Confirmación respectivamente. A continuación se describe la funcionalidad de cada una de estas páginas y los parámetros asociados. Adicionalmente se describe cómo generar las firmas digitales de las transacciones y se presenta un ejemplo en PHP, Java y Asp.NET. Nota: Ver imagen del flujo de una transacción, Figura 2.1. Importante Si no desea utilizar las páginas de Respuesta y Confirmación, es necesario que redireccione el flujo del pago al index de su sitio web configurando en el módulo administrativo en Pagosonline.net la página de respuesta. 3.1 PÁGINA DE ENVÍO DE LA INFORMACIÓN Esta es la página que envía la información al sistema transaccional de Pagosonline.net utilizando un formulario HTML. Como mínimo se debe enviar el código de referencia de la transacción refventa, que no se debe repetir, el valor, el valor del IVA, la descripción de la venta y el número de usuario del comercio en Pagosonline.net. Con el código de referencia debe ser posible identificar exactamente qué producto o servicio se está pagando, así como los datos básicos del comprador. Recomendamos utilizar un valor generado automáticamente por la base de datos. Además de ello recomendamos enviar también el correo electrónico del comprador para notificarle el resultado de la transacción así como para facilitar la evaluación de la transacción con el módulo antifraude. La página a la cual se debe enviar la información de los pagos se encuentra en la siguiente dirección URL: Importante La dirección de enlace se encuentra bajo una capa SSL certificada por VERISIGN. 5

7 Importante Si envía una solicitud de pago con un mismo número de referencia pero con un valor o descripción diferente el sistema generará el error (-2017), consulte el capítulo 6 (Errores más frecuentes). A continuación se presenta un ejemplo de un formulario HTML: <form method="post" action=" <input name="usuarioid" type="text" value="2"> <input name="descripcion" type="text" value="pruebas"> <input name="refventa" type="text" value="0001"> <input name="valor" type="text" value="116000"> <input name="basedevolucioniva " type="text" value="100000"> <input name="iva" type="text" value="16000"> <input name="moneda" type="text" value="cop"> <input name="firma" type="text" value="694f a e450a820b0"> <input name="submit" type="submit" value="enviar"> </form> En el formulario HTML se puede ver que se está generando una transacción para el usuario No 2, con una descripción de la venta "Pruebas", una referencia única de la compra "0001", por un valor total de "$116000" y un IVA de "$16000". El valor se envío en pesos colombianos, utilizando la variable moneda con el valor "COP", y se generó una firma digital con el valor "694f a e450a820b0" que garantiza la autenticidad y la integridad de la transacción. A continuación se presenta la tabla con los parámetros básicos que recibe la página de pagos, detallando el campo tipo como N: numérico y A: alfanumérico, la longitud máxima y si se trata de un campo requerido o no, para conocer los demás parámetros consulte en el anexo III. Tabla 3.1. Parámetros básicos de la Pagina de Pagos Campo Tipo. Tam. Req. Descripción usuarioid N 12 Si El número de usuario en el sistema de Pagosonline.net. Este número lo encontrará en el correo de confirmación de la creación de su cuenta. refventa A 50 Si La referencia de la venta o pedido. Deber ser único por cada transacción que se envía al sistema. descripcion A 255 Si Descripción de la venta. valor N 14,2 Si El valor de la transacción especificado en la moneda enviada o en pesos si ésta no se especifica. Contiene dos dígitos decimales. Ej , son diez mil pesos con cero centavos. iva N 14,2 Si El valor del IVA en la moneda especificada o en pesos si ésta no se especifica, si no se envía el IVA se aplicará el 16% automáticamente. Contiene dos dígitos decimales. Ej: En caso de que no tenga IVA o el IVA corresponda a otra tarifa se debe enviar en 0. 6

8 basedevolucioniva N 14,2 Si El valor de la base de devolución del IVA para productos gravados con el 10% o el 16% de la tarifa del IVA. En caso de que no tenga IVA o el IVA corresponda a otra tarifa se debe enviar en 0. firma A 32 Si La firma digital del mensaje utilizando el algoritmo Md5. Ver sección: Generación de las firmas digitales. comprador A 255 No Campo que contiene el correo electrónico del comprador para notificarle el resultado de la transacción por correo electrónico. prueba N 1 No Si el valor de la variable es "1" la transacción se considera una transacción de prueba. lng A 3 No Código ISO-639 del idioma en el que se desea mostrar la pasarela de pagos. Ver los lenguajes admitidos en el anexo II. moneda A 3 No Código ISO-4217 de la moneda respectiva en la que se debe mostrar la información del pago. El proceso de conciliación se hace en pesos a la tasa representativa del día. Ver las divisas admitidas en el Anexo I. valoradicional N 14,2 No El valor adicional no sujeto a comisión por parte de la entidad financiera Ej. una propina en un restaurante. nombrecomprador A 50 No El nombre del comprador. Este valor se tomará para llenar el formulario de tarjetas crédito. documentoidentificacion A 25 No El nombre de identificación del comprador. Este valor se tomará para llenar el formulario de tarjetas crédito. El nombre de identificación del comprador. Este valor se tomará para llenar el formulario de tarjetas crédito. tipodocumentoidentificacion N 2 No El tipo de identificación del cliente. 1 Cédula de Ciudadanía 2 - NIT (sin dígito de chequeo) 3 - Cédula de Extranjería 4 - Tarjeta de Identidad 5 - Pasaporte 6 - Tarjeta Social Security 7 - Sociedad extranjera sin Nit. 8 - Fideicomiso 9 - Registro Civil 10 Carné Diplomático 99 Otro telefonomovil A 50 No El número celular del comprador en caso de enviarlo se utilizará como teléfono del trabajo y de residencia Este valor se tomará para llenar el formulario de tarjetas crédito y será el teléfono de contacto. extra1 A 255 No Campo adicional para enviar información sobre la compra. Ej. extra1 = teléfonos: extra2 A 255 No Campo adicional para enviar información sobre la compra. url_respuesta A 255 No La url de respuesta. Donde se envía al tarjetahabiente una vez ha finalizado su proceso en Pagosonline.net 1 url_confirmacion A 255 No La url de confirmación. Es una página dedicada a la recepción de datos de Pagosonline.net. Es transparente para cualquier usuario. Las filas resaltadas son obligatorias para el sistema de Pagosonline.net. 1Este parámetro se debe enviar únicamente cuando la URL de respuesta y/o confirmación es diferente a la especificada en la configuración del cliente en su módulo administrativo. Si envía dicho parámetro, el sistema de Pagosonline.net ignorará la configurada en su panel administrativo y utilizará las variables que envíe. 7

9 Nota: Si desea conocer los demás parámetros que se pueden utilizar por favor remítase al anexo III Cálculo de la base de Devolución La base de devolución corresponde al valor de los productos y/o servicios grabados con el IVA del 16% o del 10%. Para mayor claridad se presenta un ejemplo: Tabla 3.2. Ejemplo del cálculo de la base de devolución del IVA Producto Base IVA Valor Total A 100,000 16, ,000 B 200,000 20, ,000 C 150, ,000 Base Devolución IVA 300,000 IVA 36,000 Valor Total 486,000 Los campos que se deberían enviar a Pagosonline.net serían los siguientes: Tabla 3.3. Ejemplo de los campos que se envían a Pagosonline.net Campo Valor valor 486, iva 36, basedevolucioniva 450, Importante Si usted envía los campos iva y basedevolucioniva vacíos (p.e. IVA=' ') el sistema automáticamente tomará un IVA del 16% y la base de devolución respectiva Generación de las firmas digitales Para garantizar la autenticidad y la integridad de las tramas que son recibidas y generadas por Pagosonline.net se desarrolló un sistema de firmas digitales basado en criptografía de una sola vía (funciones de Hashing). 8

10 Para la generación de las firmas se utiliza una llave de encripción que únicamente es conocida por Pagosonline.net y por el comercio (esta llave se puede consultar a través del módulo administrativo del sistema dado por Pagosonline.net). El algoritmo para la generación de las firmas digitales se describe a continuación: Cadena de envío (COMERCIO PAGOSONLINE): El comercio almacena la información de la transacción en la base de datos y genera un código único de referencia. Con esta información construye una cadena de texto de la siguiente manera: "llaveencripcion~usuarioid~refventa~valor~moneda" en donde las variables son reemplazadas por sus valores correspondientes. El valor debe ir en el formato ###.00, por ejemplo " ". A continuación se presenta un ejemplo para la generación de la firma digital por parte del comercio. Se supone que se cuenta con las siguientes variables: Campo Valor llaveencripcion usuarioid 2 refventa Pruebas01 valor moneda COP La cadena que se debe construir es la siguiente: " ~2~Pruebas01~ ~COP" Nota: Recuerde que estos datos son ejemplos, usted debe cambiarlos por los que le asignaron al convertirse en cliente de PAGOSONLINE.NET A esta cadena se le debe aplicar la función de Hashing MD5, generando de esta manera la firma digital de la transacción. No olvide presentar la firma digital como una cadena en formato Hexadecimal. La firma digital correspondiente sería: "ed3f e4dff83ad6bc00ccae1" 9

11 Cadena de recepción (PAGOSONLINE COMERCIO): Las tramas generadas por Pagosonline.net también incluyen una firma digital para garantizar la autenticidad e integridad de la respuesta. La firma se construye al aplicar el algoritmo MD5 a la cadena: "llaveencripcion~usuarioid~refventa~valor~moneda~estado_pol" A continuación se presenta un ejemplo de una cadena generada con base a los siguientes campos: Campo Valor llaveencripcion usuarioid 2 refventa PRUEBAS01 valor moneda COP La cadena generada sería: " ~2~PRUEBAS01~ ~COP~4". Para poder usted comparar la firma digital enviada por Pagosonline.net y establecer la autenticidad de la cadena recibida, recuerde que debe tomar las variables que vienen en la transacción (GET para la de respuesta y POST para la de confirmación) y vienen en mayúscula sostenida. No realice la comparación tomando las variables, por ejemplo, desde su base datos (exceptuando su llave de encripción personal) Importante Recuerde que el sistema asume la moneda "COP" siempre que se envía una transacción en donde no se especifica el campo "moneda". Para evitar posibles confusiones o errores le recomendamos enviar siempre la moneda asociada a una transacción. 10

12 3.1.3 Ejemplo de generación de las firmas digitales en PHP A continuación se presenta un ejemplo de generación de firmas digitales con PHP. Por favor recuerde que la información se presenta a manera de ejemplo y es responsabilidad del comercio enviar los parámetros correctos como se explicó anteriormente. <?php?> $llave_encripcion = " "; $usuarioid=2; $refventa=0001; $valor=116000; $basedevolucioniva=100000; $iva=16000; $moneda=cop; $descripcion = "Pruebas de Generacion de Firmas"; $firma= "$llave_encripcion~$usuarioid~$refventa~$valor~$moneda"; $firma_codificada = md5($firma); La llave de encripción que tiene asignado el usuario 2 es Con el identificador del usuario, la referencia de la venta, el valor y la moneda se genera la firma digital. Estos datos deben ser enviados a la página de pagos de Pagosonline.net, ubicada en A continuación se presenta el formulario HTML que es enviado a Pagosonline.net <form name="form1" method="post" action=" <table width="500" border="0" cellpadding="0" cellspacing="2"> <tr bgcolor="#ff8000 "> <th> Campo</th> <th >Valor</th> <tr bgcolor="#cccccc"> <td>usuario:</td> <td><input name="usuarioid" type="text" value="<?php echo($usuarioid)?>"></td> <tr bgcolor="#dedede"> <td>descripción:</td> <td><input name="descripcion" type="text" value="<?php echo $descripcion?>" > </td> <tr bgcolor="#cccccc"> <td>ref. Venta:</td> <td><input name="refventa" type="text" value="<?php echo $refventa?>"></td> 1 Para consultar la llave de encripción debe ingresar al módulo administrativo en y seleccionar la pestaña Opciones 11

13 <tr bgcolor="#dedede"> <td>valor:</td> <td><input name="valor" type="text" value="<?php echo $valor?>"> </td> <tr bgcolor="#cccccc"> <td bgcolor="#cccccc">iva:</td> <td><input name="iva" type="text" value="<?php echo $iva?>"></td> <tr bgcolor="#dedede"> <td bgcolor="#dedede">base Devolución Iva:</td> <td> <input name="basedevolucioniva" type="text" value="<?php echo $basedevolucioniva?>" > </td> <tr bgcolor="#cccccc"> <td bgcolor="#cccccc">moneda:</td> <td><input name="moneda" type="text" value="<?php echo $moneda?>"></td> <tr bgcolor="#dedede"> <td>firma:</td> <td><input name="firma" type="text" value="<?php echo $firma_codificada?>"></td> <tr bgcolor="#cccccc"> <td> </td> <td><input name="submit" type="submit" value="enviar"></td> </table> </form> Ejemplo de generación de las firmas digitales en JAVA A continuación se presenta un ejemplo de generación de firmas digitales en JAVA. Por favor recuerde que la información se presenta a manera de ejemplo y es responsabilidad del comercio enviar los parámetros correctos como se explicó anteriormente. <%@page import="org.apache.commons.codec.digest.digestutils"%> <% String clavesecreta = " "; int usuarioid = new Integer(request.getParameter("usuarioId")).intValue(); String refventa = request.getparameter("refventa"); double valor = new Double(request.getParameter("valor")).doubleValue(); double basedevolucion = new Double(request.getParameter("baseDevolucion")).doubleValue(); double iva = new Double(request.getParameter("iva")).doubleValue(); String moneda = request.getparameter("moneda"); String descripcion = request.getparameter("descripcion"); String cadena = clavesecreta + "~" + usuarioid + "~" + refventa + "~" + valor + "~" + moneda; String firma = DigestUtils.md5Hex(cadena); %> 12

14 Importante Para poder ejecutar el ejemplo anterior debe incluir la librería commons-codec de Apache [ La llave de encripción que tiene asignado el usuario 2 es Con el identificador del usuario, la referencia de la venta, el valor y la moneda se genera la firma digital. Estos datos deben ser enviados a la página de pagos de Pagosonline.net, ubicada en A continuación se presenta el formulario HTML que es enviado a Pagosonline.net <form name="form1" method="post" action=" <table width="500" border="0" cellpadding="0" cellspacing="2"> <tr bgcolor="#ff8000"> <th> Campo</th> <th >Valor</th> <tr bgcolor="#cccccc"> <td>usuario:</td> <td><input name="usuarioid" type="text" value="<%= usuarioid %>"></td> <tr bgcolor="#dedede"> <td>descripción:</td> <td><input name="descripcion" type="text" value="<%= descripcion %>"></td> <tr bgcolor="#cccccc"> <td>ref. Venta:</td> <td><input name="refventa" type="text" value="<%= refventa %>"></td> <tr bgcolor="#dedede"> <td>valor:</td> <td><input name="valor" type="text" value="<%= valor %>"></td> <tr bgcolor="#dedede"> <td>base Devolución Iva:</td> <td><input name="basedevolucioniva" type="text" value="<%= basedevolucion%>"></td> <tr bgcolor="#cccccc"> <td bgcolor="#cccccc">iva:</td> <td><input name="iva" type="text" value="<%= iva %>"></td> <tr bgcolor="#dedede"> <td bgcolor="#dedede">moneda:</td> <td><input name="moneda" type="text" value="<%= moneda %>"></td> <tr bgcolor="#cccccc"> 2 Para consultar la llave de encripción debe ingresar al módulo administrativo en y seleccionar la opción Opciones 13

15 <td>firma:</td> <td><input name="firma" type="text" value="<%= firma %>"></td> <tr bgcolor="#cccccc"> <td> </td> <td><input name="submit" type="submit" value="enviar"></td> </table> </form> Ejemplo de generación de las firmas digitales en Visual Basic.NET A continuación se presenta un ejemplo de generación de firmas digitales con Visual Basic (Asp.net). Por favor recuerde que la información se presenta a manera de ejemplo y es responsabilidad del comercio enviar los parámetros correctos como se explicó anteriormente. <%@ Page Language="VB" %> <%@ Import Namespace="System" %> <%@ Import Namespace="System.Security.Cryptography" %> <%@ Import Namespace="System.Text" %>... <% ' Encripta una cadena ingresada y retorna el Hash ' como una cadena hexadecimal de 32 caracteres Function getmd5hash(byval input As String) As String ' Crea una nueva instancia del objeto MD5. Dim md5hasher As MD5 = MD5.Create() ' Convierte la cadena ingresada a un array de bytes y genera el hash. Dim data As Byte() = md5hasher.computehash(encoding.default.getbytes(input)) ' Create a new Stringbuilder to collect the bytes and create a string. Dim sbuilder As New StringBuilder() ' Loop through each byte of the hashed data and format each one as a hexadecimal string. ' Dim i As Integer For i = 0 To data.length - 1 sbuilder.append(data(i).tostring("x2")) Next i ' Return the hexadecimal string. Return sbuilder.tostring() End Function 'Se capturan las variables por ejemplo desde un formulario Dim clavesecreta As String = " "; Dim usuarioid As Integer = request.form("usuario_id") Dim refventa As String = request.form("ref_venta") Dim valor As Double = request.form("valor") Dim moneda As String = request.form("moneda") Dim firma As String = "clavesecreta & "~" & usuarioid & "~" & refventa & "~" & valor & "~" & moneda" Dim firma_codificada As String = getmd5hash(firma) %> 14

16 La llave de encripción que tiene asignado el usuario 2 es Con el identificador del usuario, la referencia de la venta, el valor y la moneda se genera la firma digital. Estos datos deben ser enviados a la página de pagos de Pagosonline.net, ubicada en A continuación se presenta el formulario HTML que es enviado a Pagosonline.net <form name="form1" method="post" action=" <table width="500" border="0" cellpadding="0" cellspacing="2"> <tr bgcolor="#000099"> <th width="119">campo</th> <th width="375">valor</th> <tr bgcolor="#cccccc"> <td>usuario:</td> <td><input name="usuarioid" type="text" value="<%= request.form("usuarioid") %>"></td> <tr bgcolor="#dedede"> <td>descripción:</td> <td><input name="descripcion" type="text" value="<%= request.form("descripcion")%>"></td> <tr bgcolor="#cccccc"> <td>ref. Venta:</td> <td><input name="refventa" type="text" value="<%= request.form("refventa") %>"></td> <tr bgcolor="#dedede"> <td>valor:</td> <td><input name="valor" type="text" value="<%= request.form("valor") %>"></td> <tr bgcolor="#cccccc"> <td>valor:</td> <td><input name="basedevolucioniva" type="text" value="<%=request.form("basedevolucioniva") %>"></td> <tr bgcolor="#dedede"> <td bgcolor="#dedede">iva:</td> <td><input name="iva" type="text" value="<%= request.form("iva") %>"></td> <tr bgcolor="#cccccc"> <td bgcolor="#cccccc">moneda:</td> <td><input name="moneda" type="text" value="<%= request.form("moneda") %>"></td> <tr bgcolor="#dedede "> <td>firma:</td> <td><input name="firma" type="text" value="<%= request.form("firma") %>"></td> <tr bgcolor="#cccccc"> <td> </td> <td><input name="submit" type="submit" value="enviar"></td> </table> </form> 3 Para consultar la llave de encripción debe ingresar al módulo administrativo en y seleccionar la opción Opciones 15

17 4. PÁGINA DE RESPUESTA La página de respuesta es una página informativa que se le muestra al comprador una vez ha terminado de realizar su transacción financiera en Pagosonline.net. Esta página tiene un propósito puramente informativo. Dada la naturaleza de Internet, es imposible garantizar que la página de respuesta sea llamada en todos los casos, el comprador puede cerrar el navegador de Internet antes de tiempo, o puede tener un problema de comunicación temporal. Le recomendamos no realizar ningún tipo de operación transaccional en esta página, este tipo de operaciones se deben realizar utilizando la página de confirmación. Nota: Ver imagen del flujo de una transacción, Figura 2.1. A continuación se presenta los parámetros que son enviados a la página de respuesta, detallando el tipo campo N: numérico y A: alfanumérico, la longitud máxima y si se trata de un campo requerido o no. Tabla 4.1. Parámetros enviados a la Pagina de Respuesta Campo Tipo. Tam. Descripción usuario_id N 12 El número de usuario en el sistema de Pagosonline.net. Este número lo encontrará en el correo de confirmación de la creación de su cuenta. estado_pol N 2 Indica el estado de la transacción en el sistema, ver tabla en el anexo IV con los estados. riesgo N 12 El riesgo asociado a la transacción. Toma un valor entre 0 y 1. A mayor riesgo mayor valor. Viene en formato ###.00 codigo_respuesta_pol N 2 El código de respuesta de Pagosonline.net. Ver la tabla con los códigos de respuesta en el anexo V. ref_venta A 50 La referencia de la venta o pedido. Deber ser único por cada transacción que se envía al sistema. ref_pol N 12 La referencia o número de la transacción en Pagosonline.net. firma A 32 La firma digital del mensaje utilizando el algoritmo Md5, esta firma se enviará en mayúscula sostenida por motivos de compatibilidad. Ver sección: Generación de las firmas digitales. extra1 A 255 Campo adicional para enviar información sobre la compra. Ejemplo: extra1=teléfonos: Si el campo no especificado, envía una cadena en blanco. extra2 A 255 Campo adicional para enviar información sobre la compra. Si el campo no fue especificado, envía una cadena en blanco. mensaje A 255 Descripción del estado de la transacción. medio_pago N 2 El identificador interno del medio de pago utilizado. Ver tabla en el anexo VII para consultar información sobre los medios de pago disponibles 16

18 tipo_medio_pago N 2 El tipo de medio de pago utilizado para el pago. Ver tabla en el anexo VI para los tipos de medios de pago disponibles. cuotas N 2 Número de cuotas en las cuales se difirió el pago con tarjeta crédito. valor N 14,2 El valor de la transacción en formato ###.00 en la moneda que fue hecho el pago. valorpesos N 14,2 El valor de la transacción en formato ###.00 en pesos Colombianos (COP). iva N 14,2 El valor del IVA de la transacción en formato ###.00 valoradicional N 14,2 El valor adicional enviado no sujeto a comisión por parte de la entidad financiera. moneda A 3 Código ISO-4217 de la moneda utilizada para realizar el pago. Ver las divisas admitidas en el anexo I. cus N 15 El cus, código único de seguimiento, es la referencia del pago dentro del Banco, aplica solo para pagos con PSE. En el caso de un pago con tarjeta de crédito se envía la fecha de la transacción YYYYMMDD. Requerido para la certificación de PSE con ACH Colombia. banco_pse A 25 El nombre del banco, aplica solo para pagos con PSE. Requerido para la certificación de PSE con ACH Colombia. idioma A 2 Código ISO-639 del idioma en el cual se mostró la pasarela de pagos. Ver los lenguajes admitidos en el anexo II. comprador A 255 Campo que contiene el correo electrónico del comprador para notificarle el resultado de la transacción por correo electrónico. fecha_procesamiento A 20 La fecha en que se realiza la transacción. Importante Para propósitos de despachos y/o manejo logístico de su negocio (a excepción de ciertos casos mencionados en el capítulo 9) NO UTILICE la página de respuesta como mecanismo para actualizar su base de datos. A su vez tenga en cuenta el estado en validación (para tarjetas de crédito) y el estado pendiente (para PSE), ya que no son una respuesta afirmativa ni negativa de la transacción. Entonces es necesario que en la página de respuesta usted informe al tarjeta habiente que dicha transacción debe ser autorizada por su sistema de pagos en línea y puede tomar un tiempo prudencial la verificación de datos y procesamiento de la misma. Para más información sobre este estado, remítase al Anexo IX numeral h. 4.1 EJEMPLO EN PHP PARA CAPTURAR VARIABLES DE URL DE RESPUESTA Por favor recuerde que la información se presenta a manera de ejemplo y es responsabilidad del comercio mostrar los parámetros correctos como se explicó anteriormente. 17

19 En este caso tomaremos como ejemplo de variable la Referencia del pago (ref_pol): <! Código de respuesta del comercio --> <tr> <td>referencia del pago:</td> <td><?php echo $_GET['ref_pol'];?></td> 4.2 EJEMPLO EN JAVA PARA CAPTURAR VARIABLES DE URL DE RESPUESTA <! Código de respuesta del comercio --> <tr> <td>referencia del pago:</td> <td><% out.println(request.getparameter("ref_pol")); %></td> 4.3 EJEMPLO EN ASP.NET PARA CAPTURAR VARIABLES DE URL DE RESPUESTA <! Código de respuesta del comercio --> <tr> <td>referencia del pago:</td> <td>><% =Request.querystring("ref_pol") %></td> Una vez el tarjetahabiente haya procesado el pago, podrá visualizar claramente página de respuesta que dará a conocer las variables anteriormente suscritas. Importante Si usted lo desea, puede requerir que la página de respuesta sea una estándar de PAGOSONLINE.NET. Si hace esto, configure la URL de respuesta como el index de su página web (p.e. sobre su panel administrativo y consulte al área de soporte de Pagosonline.net. Importante Para descargar ejemplos y tutoriales no olvide visitar nuestra web de ayudas: 18

20 5. PÁGINA DE CONFIRMACIÓN Una vez recibida la confirmación de la transacción por parte de la entidad financiera, Pagosonline.net invocará la página de confirmación. Esta página establece una comunicación directa entre el sistema transaccional de Pagosonline.net y el sitio web del comercio y por ende no se mostrará ninguna información al comprador. Esta página es independiente y diferente a la Página de Respuesta, no tiene tags html ni funciones de navegador como javascript; es transparente para cualquier usuario y solamente cumple la función de recibir la información a través de un socket entre el servidor del comercio y el de pagosonline.net El propósito de la página de confirmación es notificar al comercio de la realización de una transacción en Pagosonline.net, para que éste pueda dar inicio al proceso logístico correspondiente 4. La página de confirmación del comercio es llamada por medio de una petición HTTP POST. A continuación se presentan los parámetros que son enviados a la página de confirmación, detallando el tipo campo N: numérico y A: alfanumérico, la longitud máxima y si se trata de un campo requerido o no. Tabla 5.1. Parámetros enviados a la Pagina de Confirmación Campo Tipo. Tam. Descripción usuario_id N 12 El número de usuario en el sistema de Pagosonline.net. Este número lo encontrará en el correo de confirmación de la creación de su cuenta. estado_pol N 2 Indica el estado de la transacción en el sistema, ver tabla en el anexo IV con los estados. riesgo N 12 El riesgo asociado a la transacción. Toma un valor entre 0 y 1. A mayor riesgo mayor valor. Viene en formato ###.00 codigo_respuesta_pol N 2 El código de respuesta de Pagosonline.net. Ver la tabla anexa con los códigos de respuesta. ref_venta A 50 La referencia de la venta o pedido. Deber ser único por cada transacción que se envía al sistema. ref_pol N 12 La referencia o número de la transacción en Pagosonline.net. firma A 32 La firma digital del mensaje utilizando el algoritmo Md5, esta firma se enviará en mayúscula sostenida por motivos de compatibilidad. Ver sección: Generación de las firmas digitales. 4 Le recomendamos establecer un proceso tanto para las transacciones aprobadas como para las transacciones rechazadas. Los clientes de Pagosonline.net que mayor volumen de ventas tienen, generalmente cuentan con un sistema de seguimiento automático capaz de generar control de inventarios, despachos y otras funciones relacionadas para contactar a sus clientes. 19

21 extra1 A 255 Campo adicional para enviar información sobre la compra. Ejemplo: extra1=teléfonos: Si el campo no especificado, envía una cadena en blanco. extra2 A 255 Campo adicional para enviar información sobre la compra. Si el campo no fue especificado, envía una cadena en blanco. medio_pago N 2 El identificador interno del medio de pago utilizado. Ver tabla en el anexo VII para consultar información sobre los medios de pago disponibles tipo_medio_pago N 2 El tipo de medio de pago utilizado para el pago. Ver tabla en el anexo VI para los tipos de medios de pago disponibles. cuotas N 2 Número de cuotas en las cuales se difirió el pago con tarjeta crédito. valor N 14,2 El valor de la transacción en formato ###.00 en la moneda que fue hecho el pago. iva N 14,2 El valor del IVA de la transacción en formato ###.00 valoradicional N 14,2 El valor adicional enviado no sujeto a comisión por parte de la entidad financiera. moneda A 3 Código ISO-4217 de la moneda respectiva en la que se debe mostrar la información del pago. El proceso de conciliación se hace en pesos a la tasa representativa del día. Ver las divisas admitidas en el anexo I. fecha_transaccion A 20 La fecha de procesamiento de la transacción en formato: yyyy- MM-dd HH:mm:ss. Por ejemplo :15:43 codigo_autorizacion A 7 Se envía únicamente si la transacción resultó aprobada. En el caso de tarjetas de crédito, se envía un código numérico de trazabilidad interno de pagosonline. En el caso de tarjeta débito se enviá en formato texto indicando el estado. cus N 15 El cus, código único de seguimiento, es la referencia del pago dentro del Banco, aplica solo para pagos con PSE. En el caso de un pago con tarjeta de crédito se envía la fecha de la transacción YYYYMMDD. Requerido para la certificación de PSE con ACH Colombia. banco_pse A 25 El nombre del banco, aplica solo para pagos con PSE. Requerido para la certificación de PSE con ACH Colombia. _comprador A 255 Campo que contiene el correo electrónico del comprador para notificarle el resultado de la transacción por correo electrónico. Nota: Para validar la autenticidad y la integridad de los datos le recomendamos validar la firma digital de la transacción, como se detalla en el Importante Por políticas de seguridad de Pagosonline.net, usted solo podrá utilizar el puerto 80 para la recepción de la información enviada a la página de confirmación por Pagosonline. Además si instala la página de confirmación en un servidor seguro https, debe tener un certificado de seguridad válido y enviarlo al área de soporte de Pagosonline.net. De lo contrario el sistema no podrá llamar a la página de confirmación 20

22 Por favor recuerde que la información se presenta a manera de ejemplo y es responsabilidad del comercio enviar los parámetros correctos como se explicó anteriormente. 5.1 Ejemplo en PHP para capturar variables de URL de confirmación <?php?> $referenciapol = $_POST['ref_pol']; 5.2 Ejemplo en JAVA para capturar variables de URL de confirmación <% %> longint referenciapol; referenciapol= request.getparameter("ref_pol")); 5.3 Ejemplo en ASP.NET para capturar variables de URL de confirmación <% %> Dim referenciapol as Long referenciapol = Request.Form("ref_pol") Nota: Consulte el anexo III para ver los parámetros adicionales enviados a la página de confirmación. También le recomendamos revisar el anexo IX donde se resuelven dudas acerca de los errores generados para esta página. Importante Si usted tiene un volumen transaccional alto o es crítico para las reglas de su negocio recibir la respuesta de la transacción rápidamente (por ejemplo ventas de tiquetes, reservas o boletería), le recomendamos enfáticamente consumir el método de consultarestadotransaccion() del web service de pagosonline.net en vez de utilizar la página de confirmación aquí descrita. Por favor consulte el manual de integración web service ( o comuníquese con el área de soporte. 21

23 6. ERRORES MÁS FRECUENTES No. Error Tabla 6.1. Códigos de error que se pueden presentar durante el proceso de pago. Descripción Posible solución -7 La solicitud de pago ya se encuentra como pagada en el sistema El monto de la transacción excede los límites establecidos, por favor comuníquese con la empresa -113 Error validando firma digital. Por favor verifique que la cadena que está generando la firma digital esté correcta El valor es inferior al mínimo permitido, por favor verifique El valor de la base de devolución del IVA es inválido, por favor verifique que el campo no esté vacío o no corresponda el valor indicado El valor del IVA es inválido, excede o es igual al valor de la transacción El valor es superior al máximo permitido, si desea aumentar su monto permitido actual, por favor contacte con el área de transacciones Los datos para crear la solicitud de pago son inválidos o insuficientes Transacción rechazada, por favor contacte el área de transacciones para mayor información. Verifique que la referencia de venta no haya sido utilizada con anterioridad. Recuerde que la referencia de venta es un campo único. El comercio debe solicitar a través de correo electrónico o llamada telefónica el aumento del monto por transacción de ser necesario. Revise el capítulo para verificar la correcta generación de dicha variable. Verifique que la llave de encripción concuerde con la que esta en su módulo administrativo. También verifique que este enviando los campos como se indica en el capítulo 3.1. El monto mínimo de transacción para Pagosonline.net es 3,500 pesos colombianos. Recuerde que la base de devolución depende del IVA, si no hay IVA no hay base de devolución. No se pueden enviar valores negativos. Verifique que la base de devolución más el IVA no superen el valor total de la transacción. El comercio debe solicitar a través de correo electrónico o llamada telefónica el aumento del monto mensual de transacciones de ser necesario. Verifique que todos los campos obligatorios se están enviando correctamente (incluido el usuarioid, refventa y firma) Su IP no esta validada por el módulo antifraude para realizar pruebas. Por favor contacte con el área de soporte para habilitar su IP Modificación ilegal solicitud pago Este error ocurre cuando se envía una transacción con el mismo número de referencia de venta, pero se ha modificado algún valor (valor, iva, base de devolución del IVA). El sistema no permite dos transacciones con la misma referencia de venta. Verifique, si genera este número desde una base de datos (autoincrement), que este campo no este enviando números enviados anteriormente. Nota: Si su error no aparece aquí, visite nuestros foro: 22

24 7. MÓDULO DE AGENCIAS DE VIAJES El sistema cuenta con un módulo especial para las agencias de viajes que permite cobrar la tarifa administrativa y el tiquete aéreo en un único pago, enviando el dinero de la tarifa administrativa a la agencia de viajes y el dinero del tiquete aéreo a la aerolínea. Para utilizar este módulo únicamente se debe enviar el código VISA o el código IATA de la aerolínea, así como el valor de la tarifa administrativa, el iva de la tarifa administrativa y la base de devolución del IVA. El módulo utiliza la página de respuesta y la página de confirmación para reportar el resultado del pago al cliente. En caso tal que los campos correspondientes a la tarifa administrativa no se envíen, el sistema procesará la transacción de manera ordinaria, abonando el dinero directamente a la cuenta de la agencia de viajes Importante Por motivos técnicos es posible que la transacción para el pago del tiquete aéreo se apruebe y la transacción de la tarifa administrativa se rechace. Cuando esto ocurre, el sistema retorna el código de respuesta 24, transacción parcial aprobada. Es responsabilidad del comercio procesar de nuevo el pago para la tarifa administrativa. El módulo de agencias de viajes se encuentra disponible únicamente para pagos con tarjetas de Crédito VISA, AMEX y DINERS. Aún no se encuentra disponible para pagos con tarjetas de crédito MASTERCARD. El valor de la tasa aeroportuaria se debe enviar en el campo valoradicional y no se debe agregar al valor total de la transacción para que la entidad financiera no cobre comisión sobre este valor. Este es un ejemplo de como se envían los campos: Campo Valor valor basedevolucioniva iva valoradicional tarifaadministrativa ivatarifaadministrativa basedevoluciontarifaadministrativa

25 8. PRUEBAS Pagosonline.net cuenta con un módulo y un servidor de pruebas (clon del servidor de producción), que permite realizar pruebas con tarjetas de crédito ficticias y pagos simulados sobre el sistema PSE, en tiempo real. 8.1 PRUEBAS CON TARJETA DE CRÉDITO A continuación se describe el procedimiento para realizar una prueba en el sistema: 1. Para que el sistema utilice el módulo de pruebas debe enviar una solicitud de pago (ver sección 3.1) con la variable prueba con el valor 1 y el campo action del form se debe modificar de la siguiente manera: <form method="post" action=" 2. Debe seleccionar una de las franquicias emisoras de las tarjetas de crédito 3. Debe ingresar todos los datos requeridos por el sistema, digitando en el campo de la tarjeta de crédito un número de longitud 16 dígitos. Para conseguir determinada respuesta ingrese uno de los siguientes números: Número de tarjeta Respuesta respuesta_estado_pol Aprobada Rechazada En proceso de validación Por ejemplo, para aceptar una transacción escriba el siguiente número de tarjeta de crédito: Los dos primeros dígitos (99) indican que se trata de una tarjeta de crédito de pruebas. Los dos últimos dígitos de la tarjeta de crédito (01) corresponden al código de respuesta de una transacción aceptada. Los dígitos intermedios son irrelevantes pueden tomar cualquier número. Por lo tanto si usted desea generar otros estados de respuesta por favor remítase al Anexo V. Si hace la prueba con MasterCard los dígitos de verificación son '123'. 24

26 Importante No realice pruebas con tarjetas débito, cuenta de ahorro o cuenta corriente si el action del form envía los datos a ya que se le debitará de la cuenta el pago como si fuera una transacción real. Para analizar el funcionamiento completo del sistema realice pruebas con tarjetas crédito, el flujo de la información con tarjetas débito es el mismo, tan solo que al momento de pagar se redirige al sitio web del banco para que allí ingrese usuario y contraseña, y al finalizar el pago se redirige a su página de respuesta. 8.2 PRUEBAS A TRAVÉS DE PSE Nota: El sistema de PSE esta disponible solamente en el horario 8:00 a.m. - 8:00 p.m. (en ambiente de pruebas) Pagosonline cuenta con un sistema de pruebas para PSE similar al de tarjetas de crédito; por lo tanto también es posible generar varios códigos de respuesta. Para ello, una vez que ingrese a la pasarela de pagos de pagosonline.net, debe escoger PSE como medio de pago. Una vez allí seleccione el banco: BANCO WEB SERVICE ACH como lo indica la imagen. Figura

27 En la siguiente pantalla, sale un formulario de pruebas de PSE donde se debe colocar los siguientes datos: como lo indica la imagen Account Agency: 1234 Account Number: 1234 Password: Figura 8.2 El resultado de la operación será aprobada. Para obtener el estado Rechazada elegimos de nuevo Banco Web Service ACH como en la Figura 8.1. Cuando lleguemos al formulario de PSE (Figura 8.2) le damos clic en Cancel, y en la siguiente pantalla coloque 00001, como lo muestra la imagen: Figura

28 De igual manera podemos simular otros resultados: Banco a seleccionar Datos plantilla PSE Resultado de la operación Banco Web Service ACH AA: 1234 AN: 1234 P: Banco Web Service ACH Banco Unión Colombiano AA: 1234 AN: 1234 P: Banco Tequendama AA: 1234 AN: P: - Botón Cancel. Luego en el campo Error Code colocar: Aprobada Rechazada Fallida Pendiente AA: Account Agency AN: Account Number P: Password 27

29 9. CERTIFICACIÓN PSE (solo plan empresarial) ACH Colombia es una Cámara de Compensación Autorizada que permite el intercambio de transacciones entre diferentes Entidades Financieras. Para el caso de compras en internet, el sistema a utilizar es PSE (Proveedor de Servicios Electrónicos), y por lo tanto todo el proceso de compra de un artículo o servicio, debe ser certificado por dicha entidad. Para todo este capítulo tenga en cuenta la siguiente tabla de estados: estado_pol cod_respuesta_pol estado a mostrar Tipo de estado 4 1 Transacción aprobada final 6 5 Fallido. final 6 4 Transacción Rechazada final Pendiente, Por favor revisar si el débito fue realizado en el Banco Intermedio 6 15 En proceso de validación Intermedio Estos son los principales requerimientos que su sitio web y el proceso de comprar debe cumplir.: 1. Manejar formato de miles para las cantidades que se muestren en el sitio web del comercio durante todo el proceso de pago (p.e.: 156,000). 2. Si se desea realizar una página de respuesta personalizada, debe tenerse en cuenta que para efectos de la certificación debe mostrar los siguientes datos: Nombre y nit de la empresa (estos datos deben coincidir con la información con la que se creó el código de servicio en ACH para el comercio en cuestión). Fecha en que se realiza la transacción. (fecha_procesamiento) Estado de la transacción. (mensaje) Referencia del pedido (ref_venta) Referencia de la transacción (ref_pol) CUS (cus) Banco (banco_pse) Valor (valor) Moneda (moneda) Valor en pesos colombianos (valorpesos) Descripción (obtenida desde su base de datos) 28

30 En todos los casos debe mostrar el Estado de la transacción en base a la tabla de estados de este capítulo. Además debe incluirse el teléfono del comercio para que el cliente pueda comunicarse para hacer consultas sobre sus transacciones. Nota: Si tiene otros medios de pago, imprima en la página de respuesta la variable mensaje. Figura 9.1 Ejemplo de respuesta 3. En caso del uso obligado de ventanas emergentes, se debe tener en cuenta que no debe ser posible hacer cambios en los datos de la transacción ingresando a la ventana que se abrió inicialmente. 4. La descripción debe ser clara y referente al producto o servicio que se está pagando. No debe superar los 80 caracteres. Ejemplo: Compra en Tutienda.com 5. La pasarela de pagos debe estar personalizada. Para ello deben solicitar al área de soporte de Pagosonline.net el archivo html a personalizar. 29