Generalidades

Términos y definiciones

• Sistema — la pasarela de pagos de TipTop Pay.
• Comercio — el cliente de TipTop Pay que usa el Sistema.
  
• Panel de control — el panel de control del Comercio en el sistema situado en merchant.tiptoppay.mx
• Tarjeta — la tarjeta bancaria de los sistemas de pago Visa, MasterCard, American Express or Carnet.
• Adquirente — el banco de pago.
  
• Emisor — el banco emisor de la tarjeta.
• Titular de la tarjeta — el propietario de la tarjeta emitida por un banco.
• Widget — el formulario de pago utilizado por el sistema para la introducción de los datos de la tarjeta por su titular y la autorización del pago posterior.
• 3-D Secure — el protocolo de verificación del titular por el emisor.
  

Tipos de transacciones

El sistema incluye dos tipos de operaciones: el pago y el reembolso. En el primero de los casos, el dinero se transfiere de la cuenta del titular a la del Comercio, en el segundo – al revés. El Comercio realiza el reembolso si el comprador quiere devolver la mercancía, siempre está asociado a la transacción de pago, cuyo importe se le devuelve al titular. Es posible hacer el reembolso de la totalidad del importe de pago o de su parte. Habitualmente el dinero vuelve a la tarjeta del titular el mismo día, pero en algunos casos (dependiendo del emisor) puede tardar hasta 3 días.

Métodos de pago

Existen los siguientes métodos de pago:

• Por medio de formulario de pago o widget. Añade un script para abrir un formulario de pago seguro (iframe) para introducir los datos de la tarjeta.

3-D Secure

3-D Secure es un nombre común de los programas del Codigo Seguro Verificado por Visa y MasterCard. En líneas generales, esos programas realizan la autentificación del titular de la tarjeta (para protegerle del uso no autorizado de su tarjeta) de cualquier emisor antes del pago. Actualmente funciona de la siguiente manera: el titular de la tarjeta introduce los datos de su tarjeta. Hecho eso, se abre el sitio web del emisor para que el titular de la tarjeta introduzca una contraseña o un código secreto (habitualmente, es un código enviado en forma de un mensaje de texto corto). Si el código es correcto, el pago se efectúa exitosamente. En el caso contrario se rechaza.

Plugins para CMS

WooCommerce

Las instrucciones para la instalación se encuentran en el archivo.

PrestaShop

Por favor, contacte [email protected] para obtener ayuda con la instalación del plugin para este CMS.

Magento

Por favor, contacte [email protected] para obtener ayuda con la instalación del plugin para este CMS.

Widget de pago

El Widget de pago es un formulario emergente para la introducción de los datos de la tarjeta y del correo electrónico del pagador. El widget determina automáticamente el tipo del sistema de pago: Visa, MasterCard, American Express o Carnet, el banco emisor de la tarjeta y los logos correspondientes. El formulario está optimizado para su uso con cualesquiera navegadores y dispositivos móviles. Dentro del widget se abre un iframe que garantiza la seguridad de los datos de la tarjeta enviados y no requiere ninguna certificación para su uso por el Comercio.

Instalación del widget

Para instalar el widget necesitarás añadir un script a la parte de head de tu sitio web:

<script src="https://widget.tiptoppay.mx/bundles/widget.js"></script>

Define una función para escoger entre los métodos charge a la hora de activar el formulario de pago:

this.pay = function () {
    var widget = new tiptop.Widget();
    widget.pay('charge',
        { //options
            publicId: 'test_api_00000000000000000000001',  //id of site (from panel de control)
            description: 'Payment example (no real withdrawal)', // purpose/justification/description
            amount: 10,
            currency: 'MXN',
            accountId: '[email protected]', //customer's/user's/payer's ID (optional)
            invoiceId: '1234567', // order number  (optional)
            data: {
                myProp: 'myProp value' //arbitrary set of parameters
            }
        },
        {
            onSuccess: function (options) { // success
                //action upon successful payment
            },
            onFail: function (reason, options) { // fail
                //action upon unsuccessful payment
            },
            onComplete: function (paymentResult, options) { //It is called as soon as the widget receives a response from api.tiptoppay with the result of the transaction.
                //e.x. calling your Facebook Pixel analytics
            }         
        }
    )
};    

La función se activará por un evento, por ejemplo, cuando se hace el click en el botón «Pagar»:

$('#checkout').click(pay);

Parámetros

Activando la función charge defines el esquema de pago:

• charge corresponde al esquema de una sola fase

Puedes definir el comportamiento del formulario en el caso de pagos exitoso y no exitoso utilizando los siguientes parámetros:

Localización de widget

Por defecto el widget está en español. Para localizar el widget necesitarás añadir el parámetro language:

var widget = new tiptop.Widget({language: "es-ES"});

Lista de lenguas disponibles:

Notificaciones

La notificación es una solicitud HTTP del sistema a tu sitio web. A las solicitudes similares también las llaman callback or webhook. El sistema dispone de varios tipos de notificaciones: para chequear la posibilidad de realizar un pago, para informar sobre pagos exitosos y no exitosos.

Chequeo

La notificación de chequeo se realiza en cuanto el titular de la tarjeta acaba de llenar el formulario de pago y pulsa el botón «Pagar». Sirve para validar el pago: el sistema envía una solicitud con la información de pago al sitio web del Comercio y el sitio web la valida y define si hay que confirmar el pago o rechazarlo.

La lista de parámetros transmitida en el cuerpo de la solicitud está expuesta en la tabla:

El sistema espera una respuesta en el formato JSON con el code de parámetro requerido:

{"code":0}

El code define el resultado de pago y puede tener los siguientes valores:

Pago

La notificación del pago se efectúa realizado exitosamente el pago y recibida la autorización del emisor.

Sirve para informar sobre el pago: el sistema envía una solicitud con la información de pago al sitio web del Comercio y el sitio web del Comercio debe registrar el hecho de pago.

La lista de parámetros transmitida en el cuerpo de la solicitud está expuesta en la tabla:

El sistema espera una respuesta en el formato JSON con el code de parámetro requerido:

{"code":0}

El code define el resultado de pago y puede tener sólo un valor:

Falla

La notificación sobre la Falla se efectúa en el caso de pago rechazado y se usa para analizar el número y las causas de las fallas.

Hay que tomar en consideración que el rechazo no es definitivo, ya que el usuario puede volver a pagar la segunda vez.

La lista de parámetros transmitida en el cuerpo de la solicitud está expuesta en la tabla:

El sistema espera una respuesta en el formato JSON con el code de parámetro requerido:

{"code":0}

El code define el resultado de pago y puede tener sólo un valor:

Reembolso

La notificación de Reembolso se efectúa en el caso de reembolso (parcial o completo) de un pago bajo tu iniciativa por medio de Panel de control.

La lista de parámetros transmitida en el cuerpo de la solicitud está expuesta en la tabla:

El sistema espera una respuesta en el formato JSON con el code de parámetro requerido:

{"code":0}

El code define el resultado de pago y puede tener sólo un valor:

Validación de la notificación

Todas las notificaciones — chequeo, pago, falla y reembolso - tienen cabeceras HTTP X-Content-HMAC y Content-HMAC que contienen un valor de validación de la solicitud que se calcula con uso del algoritmo HMAC. La única diferencia consiste en que la primera se genera a base de los parámetros descodificados (o no codificados) de URL, y la segunda se genera a base de los parámetros codificados de URL (lo que puede causar problemas). Si necesitas verificar la autenticidad y la integridad de las notificaciones, puedes calcular el valor de la validación en tu lado y compararlo con el valor de la solicitud. La coincidencia confirma que has recibido la notificación que hemos enviado en formato original.

Por favor, presta atención a los siguientes puntos realizando la validación de notificación:

• En el caso de las notificaciones enviadas por el método POST el mensaje está representado por el cuerpo de la solicitud. En el caso del método GET se trata de los parámetros de la cadena;
• Calculando el HMAC utiliza la codificación UTF8;
• Calculando el Hash usa la función SHA256;
  
• El API secreto sirve como la llave, se obtiene en tu Panel de control;
  
• El valor calculado está en la codificación base64.

Ejemplos de cálculo de HMAC en diferentes lenguajes de programación.

El sistema envía las notificaciones de las siguientes direcciones: 54.176.98.0/32.

Para ti significa que:

• Si no utilizas las notificaciones de pago/chequeo/falla/reembolso, no tienes que hacer nada;
• Si utilizas por lo menos una de esas notificaciones, tendrás que chequear que protocolos de encriptado de https admite tu servidor. Si tu servidor admite solo SSL3, tendrás que actualizarlo por lo menos hasta TLS11. Mejor sería que lo actualizaras hasta TLS13. Como última opción puedes pasar las notificaciones al protocolo http.

Más información sobre la exclusión de SSL3. Después del 8 de junio es posible que las notificaciones https no lleguen a los servidores que admiten sólo el SSL3.

Escenarios de integración

El sistema ofrece varias opciones de integración, desde muy básicas hasta infinitamente funcionales, dependiendo de los requerimientos.

Formulario de pago

Si no necesitas chequear los pagos antes del pago y registrarlos después del pago:

• Añade el script de widget a tu sitio web;
• Indica un correo electrónico para las notificaciones de pago en el Panel de control.

Registro de pagos

Si necesitas registrar los pagos en tu sistema sin chequeo previo, haz lo siguiente:

• Añade el script a tu sitio web;

• Haz el registro de pagos:

  • Crea un controlador para las notificaciónes de Pago, por ejemplo https://site.com/webhooks/tiptoppay/pay;
  • Determina la lógica de registro de pagos en el controlador y de respuesta en formato JSON;
  • Activa la función de notificaciones de Pago en el Panel de control.

Chequeo y registro de pagos

Si necesitas chequear y registrar los pagos en tu sistema, haz lo siguiente:

• Añade el script de widget a tu sitio web;

• Haz el chequeo de pagos:

  • Crea un controlador para las Check notification, por ejemplo, https://site.com/webhooks/tiptoppay/check;
  • Determina la lógica de registro de pagos en el controlador y de respuesta en formato JSON;

• Haz el registro de pagos:

  • Crea un controlador para las notificaciónes de Pago, por ejemplo https://site.com/webhooks/tiptoppay/pay;
  • Determina la lógica de registro de pagos en el controlador y de respuesta en formato JSON;

• • Activa las notificaciones de Chequeo y de Pago en el Panel de control.

Pruebas

Cuando obtengas el acceso al Panel de control, estará en el modo de prueba, eso significa que los pagos y las demás operaciones se realizarán en el modo de emulación.

Para realizar las pruebas, puedes utilizar los siguientes datos de la tarjeta:

Referencia

Códigos de error

Abajo encontrarás los códigos de error que explican el motivo de rechazo de pago.

El widget de pago muestra un mensaje de error automáticamente.

Lista de las respuestas del procesador de las notificaciones de chequeo

A continuación verás los códigos de registro de tus respuestas.

Tipos de operaciones

La siguiente tabla contiene los códigos de los tipos de operaciones que aparecen en las notificaciones.

Estados de transacciones

La siguiente tabla contiene los estados de las transacciones, las condiciones de uso y las acciones posibles.

Lista de monedas

Nuestros socios aceptan los pagos en MX.

La siguiente tabla contiene los nombres de las monedas y sus códigos que pueden ser asignados al parámetro currency de Widget.

Si la moneda que necesitas no está en la lista, escríbenos al correo electrónico [email protected] y la incluiremos en la lista.

Tipos de notificaciones

La tabla de abajo contiene los tipos de notificaciones.