NAV
Example

Generalidades

Términos y definiciones

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:

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

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:

Parámetro Tipo Uso Descripción
publicId Cadena Requerido Identificador del sitio web, se encuentra en el Panel de control
description Cadena Requerido Descripción de la razón del pago en cualquier formato
amount Número de coma flotante Requerido Importe de pago
currency Cadena Requerido Moneda: MXN (véase la referencia)
accountId Cadena Requerido ID del pagador (cliente final)
invoiceId Cadena Opcional Número del pedido o de la factura
email Cadena Opcional Correo electrónico del usuario
requireEmail bool Opcional Requiere que el usuario indique su correo electrónico en el widget
retryPayment bool Opcional Mostrar el botón Repetir el pago si el pago no es exitoso. (True por defecto)

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

Parámetro Tipo Uso Descripción
onSuccess Función o Cadena Opcional Se indica una función o una página del sitio web. En el caso de indicar una función, será activada después de la realización exitosa del pago. En el caso de indicar una página, el pagador será dirigido a la página indicada
onFail Función o Cadena Opcional Se indica una función o una página del sitio web. En el caso de indicar una función, será activada después de la realización exitosa del pago. En el caso de indicar una página, el pagador será dirigido a la página indicada
onComplete Función Opcional Se indica una función que se activará en cuanto el widget reciba una respuesta con el resultado de la transacción. Este método no permite hacer redireccionamientos.

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:

languages Timezone Value
Español UTC es-ES

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:

Parámetro Formato Uso Descripción
TransactionId Numérico Requerido Número de la transacción en el sistema
Amount Numérico, punto separador, dos dígitos después del punto Requerido Importe especificado en los parámetros de pago
Currency Cadena Requerido Moneda: MXN especificada en los parámetros de pago (ver referencia)
DateTime yyyy-MM-dd HH:mm:ss Requerido Fecha/hora de creación de pago en la zona horaria UTC
CardFirstSix Cadena(6) Requerido Los primeros 6 dígitos del número de la tarjeta
CardLastFour Cadena(4) Requerido Los últimos cuatro dígitos del número de la tarjeta
CardType Cadena Requerido Sistema de pago de la tarjeta: Visa, MasterCard, American Express, or Carnet
CardExpDate Cadena Requerido Fecha de expiración en el formato MM/AA
TestMode Bit (1 or 0) Requerido Signo del modo de prueba
Status Cadena Requerido En el caso de pagos exitosos: Completed
OperationType Cadena Requerido Tipo de transacción: Pago/reembolso
InvoiceId Cadena Opcional El número de pedido especificado en los parámetros de pago
Name Cadena Opcional Nombre del titular de la tarjeta
Email Cadena Opcional Correo electrónico del pagador
IpAddress Cadena Opcional Dirección IP del pagador
IpCountry Cadena(2) Opcional El código de dos letras del país en el que se encuentra el comprador según ISO3166-1
IpCity Cadena Opcional La ciudad en la que se encuentra el Pagador
IpRegion Cadena Opcional La región en la que se encuentra el Pagador
IpDistrict Cadena Opcional El distrito en el que se encuentra el Pagador
Issuer Cadena Opcional El nombre del banco emisor de la tarjeta
IssuerBankCountry Cadena(2) Opcional El código de dos letras del país del emisor de la tarjeta según ISO3166-1
Description Cadena Opcional Descripción del pago especificada en los parámetros de pago

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:

Código Descripción Resultado
0 El pago puede efectuarse El sistema autorizará el pago
10 Número de pedido inválido El pago será rechazado
11 AccountId inválido El pago será rechazado
12 Importe inválido El pago será rechazado
13 El pago no puede ser aceptado El pago será rechazado
20 El Pago está atrasado El pago será rechazado, el pagador recibirá una notificación

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:

Parámetro Formato Uso Descripción
TransactionId Numérico Requerido Número de la transacción en el sistema
Amount Numérico, punto separador, dos dígitos después del punto Requerido Importe especificado en los parámetros de pago
Currency Cadena Requerido Moneda: MXN especificada en los parámetros de pago (ver referencia)
DateTime yyyy-MM-dd HH:mm:ss Requerido Fecha/hora de creación de pago en la zona horaria UTC
CardFirstSix Cadena(6) Requerido Los primeros 6 dígitos del número de la tarjeta
CardLastFour Cadena(4) Requerido Los últimos 4 dígitos del número de la tarjeta
CardType Cadena Requerido El sistema de pago de la tarjeta: Visa, MasterCard, American Express, or Carnet
CardExpDate Cadena Requerido La fecha de expiración en el formato MM/AA
TestMode Bit (1 or 0) Requerido Signo del modo de prueba
Status Cadena Requerido El estado de pago después de la autorización: Completed
OperationType Cadena Requerido Tipo de operación: Pago/Reembolso
GatewayName Cadena Requerido Identificador del banco Adquirente
InvoiceId Cadena Opcional El número del pedido o de la factura especificado en los parámetros de pago
Name Cadena Opcional Nombre del titular de la tarjeta
Email Cadena Opcional Correo electrónico del pagador
IpAddress Cadena Opcional Dirección IP del pagador
IpCountry Cadena(2) Opcional The El código de dos letras del país en el que se encuentra el comprador según ISO3166-1
IpCity Cadena Opcional La ciudad en la que se encuentra el Pagador
IpRegion Cadena Opcional La región en la que se encuentra el Pagador
IpDistrict Cadena Opcional El distrito en el que se encuentra el Pagador
Issuer Cadena Opcional El nombre del banco emisor de la tarjeta
IssuerBankCountry Cadena(2) Opcional El código de dos letras del país del emisor de la tarjeta según ISO3166-1
Description Cadena Opcional Descripción del pago especificada en los parámetros de pago
TotalFee Decimal Requerido El valor de Total fee
CardProduct Cadena Opcional Tipo del producto de la tarjeta
Rrn Cadena Opcional El RRN es un identificador único de la transacción asignado por el banco adquirente

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:

Código Valor
0 El pago está registrado

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:

Parámetro Formato Uso Descripción
TransactionId Numérico Requerido Número de la transacción en el sistema
Amount Numérico, punto separador, dos dígitos después del punto Requerido Importe especificado en los parámetros de pago
Currency Cadena Requerido Moneda: MXN especificada en los parámetros de pago (ver referencia)
DateTime yyyy-MM-dd HH:mm:ss Requerido Fecha/hora de creación de pago en la zona horaria UTC
CardFirstSix Cadena(6) Requerido Los primeros 6 dígitos del número de la tarjeta
CardLastFour Cadena(4) Requerido Los últimos 4 dígitos del número de la tarjeta
CardType Cadena Requerido El sistema de pago de la tarjeta: Visa, MasterCard, American Express, or Carnet
CardExpDate Cadena Requerido La fecha de expiración en el formato MM/AA
TestMode Bit (1 or 0) Requerido Signo del modo de prueba
Reason Cadena Requerido La razón de rechazo
ReasonCode Int Requerido Código de error (véase la referencia)
OperationType Cadena Requerido Tipo de operación: Pago/Reembolso
InvoiceId Cadena Opcional El número del pedido o de la factura especificado en los parámetros de pago
Name Cadena Opcional Nombre del titular de la tarjeta
Email Cadena Opcional Correo electrónico del pagador
IpAddress Cadena Opcional Dirección IP del pagador
IpCountry Cadena(2) Opcional El código de dos letras del país en el que se encuentra el comprador según ISO3166-1
IpCity Cadena Opcional La ciudad en la que se encuentra el Pagador
IpRegion Cadena Opcional La región en la que se encuentra el Pagador
IpDistrict Cadena Opcional El distrito en el que se encuentra el Pagador
Issuer Cadena Opcional El nombre del banco emisor de la tarjeta
IssuerBankCountry Cadena(2) Opcional El código de dos letras del país del emisor de la tarjeta según ISO3166-1
Description Cadena Opcional Descripción del pago especificada en los parámetros de pago
Rrn Cadena Opcional El RRN es un identificador único de la transacción asignado por el banco adquirente

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:

Código Valor
0 El intento está registrado

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:

Parámetro Formato Uso Descripción
TransactionId Numérico Requerido El número de la transacción de reembolso en el sistema
PaymentTransactionId Int Requerido El número de la transacción de pago en el sistema (original)
Amount Numérico, punto separador, dos dígitos después del punto Requerido El importe de reembolso en la moneda de pago
DateTime yyyy-MM-dd HH:mm:ss Requerido Fecha/hora de reembolso en la zona horaria UTC
OperationType Cadena Requerido Tipo de operación: Pago/Reembolso
InvoiceId Cadena Opcional El número de la factura o del pedido de la transacción original
AccountId Cadena Opcional ID del pagador de la transacción original
Email Cadena Opcional Correo electrónico del pagador
Rrn Cadena Opcional El RRN es un identificador único de la transacción asignado por el banco adquirente

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:

Código Valor
0 Reembolso registrado

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:

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:

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:

Registro de pagos

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

Chequeo y registro de pagos

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

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:

Tipo Número de tarjeta Resultado de pago
Tarjeta Visa con 3-D Secure 4242 4242 4242 4242 Éxito
Tarjeta MasterCard con 3-D Secure 5555 5555 5555 4444 Éxito
Tarjeta Visa con 3-D Secure 4012 8888 8888 1881 Fondos insuficientes
Tarjeta MasterCard con 3-D Secure 5105 1051 0510 5100 Fondos insuficientes

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.

Código Nombre Razón Mensaje para el pagador
5001 Refer To Card Issuer El emisor ha rechazado la operación Contacta con tu banco o utiliza otra tarjeta
5003 Invalid Merchant El emisor ha rechazado la operación Contacta con tu banco o utiliza otra tarjeta
5004 Pick Up Card Tarjeta perdida Contacta con tu banco o utiliza otra tarjeta
5005 Do Not Honor El emisor ha rechazado la operación sin explicación alguna
- código CVV incorrecto en el caso de MasterCard;
- limitaciones internas del banco emisor;
- la tarjeta está bloqueada o todavía no está activada;
- la tarjeta no sirve para los pagos en línea o no dispone de 3-D secure.
Contacta con tu banco o utiliza otra tarjeta
5006 Error Operación fallida debido a una falla en la red o un código CVV incorrecto Asegúrate de que los datos de la tarjeta introducidos son correctos o utiliza otra tarjeta
5007 Pick Up Card Special Conditions Tarjeta perdida Contacta con tu banco o utiliza otra tarjeta
5012 Invalid Transaction La tarjeta no está destinada a los pagos en línea Contacta con tu banco o utiliza otra tarjeta
5013 Amount Error Importe de transacción demasiado pequeño o demasiado grande Asegúrate de que el importe es correcto
5014 Invalid Card Number Número de tarjeta inválido Asegúrate de que los datos de la tarjeta introducidos son correctos o utiliza otra tarjeta
5015 No Such Issuer Emisor de tarjeta desconocido Utiliza otra tarjeta
5019 Transaction Error El emisor ha rechazado la operación sin explicación alguna
- código CVV incorrecto en el caso de MasterCard;
- limitaciones internas del banco emisor;
- la tarjeta está bloqueada o todavía no está activada;
- la tarjeta no sirve para los pagos en línea o no dispone de 3-D secure.
Contacta con tu banco o utiliza otra tarjeta
5030 Format Error Error por parte del Adquirente – transacción formada de manera incorrecta Vuelve a intentar
5031 Bank Is Not Supported By Switch Emisor de tarjeta desconocido Utiliza otra tarjeta
5033 Expired Card Pickup Tarjeta expirada a retirar Contacta con tu banco o utiliza otra tarjeta
5034 Suspected Fraud Fallo de emisor – se sospecha el fraude Contacta con tu banco o utiliza otra tarjeta
5036 Restricted Card La tarjeta no está destinada a los pagos en línea Contacta con tu banco o utiliza otra tarjeta
5041 Lost Card Tarjeta perdida Contacta con tu banco o utiliza otra tarjeta
5043 Stolen Card Tarjeta robada Contacta con tu banco o utiliza otra tarjeta
5051 Insufficient Funds Fondos insuficientes Fondos insuficientes
5054 Expired Card La tarjeta está expirada o la fecha de expiración es incorrecta Asegúrate de que los datos de la tarjeta introducidos son correctos o utiliza otra tarjeta
5057 Transaction Is Not Permitted Limitación de la tarjeta
— limitaciones internas del emisor
— la tarjeta está bloqueada o todavía no está activada;
— la tarjeta no sirve para los pagos en línea o no dispone de 3-D secure.
Contacta con tu banco o utiliza otra tarjeta
5062 Restricted Card 2 La tarjeta no está destinada a los pagos en línea Contacta con tu banco o utiliza otra tarjeta
5063 Security Violation La tarjeta está bloqueada por violación de seguridad Utiliza otra tarjeta
5065 Exceed Withdrawal Frequency Excedido el límite de transacciones de la tarjeta Contacta con tu banco o utiliza otra tarjeta
5082 Incorrect CVV Código CVV incorrecto Código CVV incorrecto
5091 Timeout Emisor no está disponible Vuelve a intentar más tarde o utiliza otra tarjeta
5092 Cannot Reach Network Emisor no está disponible Vuelve a intentar más tarde o utiliza otra tarjeta
5096 System Error Error del banco Adquirente o de la red Vuelve a intentar
5204 Unable To Process La operación no puede ser procesada por otras razones Contacta con tu banco o utiliza otra tarjeta
5206 Authentication failed Fallida la autentificación de 3-D secure Contacta con tu banco o utiliza otra tarjeta
5207 Authentication unavailable La autentificación de 3-D secure no está disponible Contacta con tu banco o utiliza otra tarjeta
5300 Anti Fraud Límites de transacción del Adquirente Utiliza otra tarjeta

Lista de las respuestas del procesador de las notificaciones de chequeo

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

Código Nombre Razón
3001 InvalidInvoiceId Devuelto por procesador de callback {"code":10}
3002 InvalidAccountId Devuelto por procesador de callback {"code":11}
3003 InvalidAmount Devuelto por procesador de callback {"code":12}
3004 OutOfDate Devuelto por procesador de callback {"code":20}
3005 FormatError El procesador de callback ha devuelto un código distinto del expected
3006 Unavailable Servicio no disponible
3007 UnableToConnect Incapaz de conectarse (404, 504, 508 etc.)
3008 NotAccepted Devuelto por procesador de callback {"code":13}

Tipos de operaciones

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

Código Nombre
Payment Pago
Refund Reembolso

Estados de transacciones

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

Estado Descripción Uso Acciones posibles
AwaitingAuthentication Esperando la autentificación Mientras el pagador espera los resultados de 3-D Secure en el sitio web del emisor Ninguna acción
Authorized Autorizada Cuando la operación está autorizada Confirmar, Cancelar
Completed Completada Cuando la operación está confirmada Reembolsar
Cancelled Cancelada En el caso de cancelación de una operación Ninguna acción
Declined Rechazada En el caso de no poder completar la transacción (Fondos insuficientes, etc) Ninguna acción

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.

Nombre Código
Mexican peso MXN

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.

Código Nombre
Check Chequeo
Pay Pago
Fail Falla
Refund Reembolso