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
Todas las versiones son compatibles.
Las instrucciones para la instalación se encuentran en el archivo.
PrestaShop
Versiones actualmente compatibles – 1.7 o posterior.
Por favor, contacte [email protected] para obtener ayuda con la instalación del plugin para este CMS.
Magento
Versiones actualmente compatibles – 2.0 o posterior.
Por favor, contacte [email protected] para obtener ayuda con la instalación del plugin para este CMS.
Ecwid / Lightspeed E-Series
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
},
onPendingPayment: function() { // La función se llama al crear una transacción de pago en efectivo (mostrando un código de barras al cliente)
// ejemplo...
}
}
)
};
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
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 |
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) |
disableEmail | bool | Opcional | El parámetro es una opción que te permite ocultar el bloque de correo electrónico en el widget. Para ocultar el bloque, no debes pasar el parámetro requireEmail o debes pasarle el valor false |
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. |
onPendingPayment | 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 se crea una transacción de pago en efectivo. En el caso de indicar una página, al cliente será dirigido a la página indicada |
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 |
Checkout
DEMO CHECKOUT
Para las pruebas se pueden utilizar tanto datos reales como datos ficticios de tarjetas. No se realizará ningún cargo de fondos.
REQUERIMIENTOS
REQUERIMIENTOS PARA EL FORMULARIO:
- Debe funcionar a través de una conexión HTTPS con un certificado SSL válido.
- Los campos no deben contener el atributo "name" — esto evita que los datos de la tarjeta se transmitan al servidor al enviar el formulario.
- El campo para ingresar el número de tarjeta debe permitir entre 16 y 19 dígitos.
REQUERIMIENTOS PARA EL CRIPTOGRAMA:
- Debe ser generado únicamente por el script original checkout, cargado desde las direcciones del sistema.
- El criptograma no puede guardarse después del pago y no puede reutilizarse.
REQUERIMIENTOS DE SEGURIDAD SEGÚN EL ESTANDAR PCI DSS:
Según el estandar PCI DSS, este método de conexión se clasifica como "E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that doesn’t directly receive cardholder data but that can impact the security of the payment transaction. No electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises.", es decir, el procesamiento de los datos de pago lo realiza un tercero, pero el sitio web influye en la seguridad de los datos de la tarjeta.
Para cumplir con los requerimientos del estándar, es necesario completar la hoja de autoevaluación SAQ-EP y superar pruebas ASV cada tres meses.
Para más información sobre el cumplimiento del estándar PCI DSS, consulte la sección PCI DSS.
INSTALACIÓN
Para generar un criptograma, es necesario incluir el script checkout en la página del formulario de pago:
<script src="https://checkout.tiptoppay.mx/checkout.js"></script>
Elija una opción que le resulte más cómoda para transferir los datos de la tarjeta:
- Transferencia a un script
- Formulario para ingresar los datos
A continuación, se debe enviar el criptograma generado de la tarjeta al servidor y llamar al método de pago a través de la API.
OPCIÓN DE TRANSFERENCIA DE LOS DATOS DE LA TARJETA DIRECTAMENTE A UN SCRIPT
1) Inicializar el script checkout
const checkout = new tiptop.Checkout({
publicId: 'test_api_000000000000000002',
});
2) Llamar al método de generación de criptogramas, transfiriendo a él los datos de la tarjeta
const fieldValues = {
cvv: '911',
cardNumber: '4242 4242 4242 4242',
expDateMonth: '12',
expDateYear: '24',
}
checkout.createPaymentCryptogram(fieldValues)
.then((cryptogram) => {
console.log(cryptogram);
}).catch((errors) => {
console.log(errors)
});
OPCIÓN UTILIZANDO EL FORMULARIO:
1) Crear un formulario para ingresar los datos de la tarjeta: Los campos para ingresar los datos de la tarjeta deben estar etiquetados con atributos:
<form id="paymentFormSample" autocomplete="off">
<input type="text" data-ttp="cardNumber">
<input type="text" data-ttp="expDateMonth">
<input type="text" data-ttp="expDateYear">
<input type="text" data-ttp="cvv">
<input type="text" data-ttp="name">
<button type="submit">Оплатить 100 р.</button>
</form>
- data-ttp="cardNumber" — campo con el número de tarjeta;
- data-ttp="expDateMonth" — campo del mes de la fecha de caducidad;
- data-ttp="expDateYear" — campo del año de la fecha de caducidad;
- data-ttp="cvv" — campo con el código CVV;
- data-ttp="name" — campo con el nombre y apellidos del titular de la tarjeta.
2) Inicializar el script checkout
const checkout = new tiptop.Checkout({
publicId: 'test_api_000000000000000002',
container: document.getElementById("paymentFormSample")
});
3) Llamar al método de generación de criptogramas
checkout.createPaymentCryptogram()
.then((cryptogram) => {
console.log(cryptogram); // cryptogram
}).catch((errors) => {
console.log(errors)
});
AL DISEÑAR UN FORMULARIO PROPIO O TRANSFERIR DATOS A UN SCRIPT, TENGA EN CUENTA LOS SIGUIENTES ASPECTOS:
- La longitud del número de tarjeta varía entre 16 (15 para tarjetas AMEX) y 19 dígitos. Más información aquí;
- El script checkout no funciona en navegadores anticuados e inseguros que no son compatibles con los protocolos de cifrado TLS versión 1.1 o superior. Por ejemplo, en Internet Explorer 7;
- la ventana 3DS se puede mostrar tanto en una nueva ventana como en un marco sobre la página. El tamaño de la ventana debe ser de al menos 500x500 píxeles.
MÉTODOS
MÉTODO ASÍNCRONO PARA LA GENERACIÓN DE CRIPTOGRAMAS.
En este método en caso de error de validación de los datos de la tarjeta, en lugar de un mensaje localizado se generará un código de error, consulte el ejemplo a continuación.
async createPaymentCryptogram(fieldValues: CardData): Promise<string>
МEl método devuelve Promise
const checkout = new tiptop.Checkout({
publicId: 'test_api_000000000000000002'
});
const fieldValues = {
cvv: '911',
cardNumber: '4242 4242 4242 4242',
expDateMonth: '12',
expDateYear: '24',
}
checkout.createPaymentCryptogram(fieldValues)
.then((cryptogram) => {
console.log(cryptogram);
});
DESCRIPCIÓN DEL OBJETO CARDDATA:
export interface CardData {
cvv?: string; // Código CVV/CVC
cardNumber?: string; // Número de tarjeta, los espacios no tienen importancia
expDateMonth?: string; // Fecha de caducidad de la tarjeta — mes
expDateYear?: string; // Fecha de caducidad de la tarjeta — año
expDateMonthYear?: string; // Fecha de caducidad de la tarjeta, se ignoran todos los caracteres excepto los dígitos,
//Si la cadena tiene 2, 3 o 5 caracteres, el primer dígito se considera como el mes, los restantes como el año.
//Si la cadena tiene 4 o 6 caracteres, los dos primeros caracteres se consideran el mes y los dos restantes el año.
}
Parámetro | Descripción | Tipo | Obligatorio * |
---|---|---|---|
cvv | Código CVV/CVC | string | No * |
cardNumber | Número de tarjeta, los espacios no tienen importancia | string | No es obligatorio si el campo está vinculado en el formulario |
expDateMonth | Fecha de caducidad de la tarjeta — mes | string | No es obligatorio si el campo está vinculado en el formulario o si se transfiere el campo expDateMonthYear |
expDateYear | Fecha de caducidad de la tarjeta — año | string | No es obligatorio si el campo está vinculado en el formulario o si se transmiten los campos |
expDateMonth
y expDateYear
expDateMonthYear | Fecha de caducidad de la tarjeta, se ignoran todos los caracteres excepto los dígitos. Si la cadena tiene 2, 3 o 5 caracteres, el primer dígito se considera como el mes y los restantes como el año. Si la cadena tiene 4 o 6 caracteres, los dos primeros se consideran el mes y los restantes el año. | string | No es obligatorio si el campo está vinculado en el formulario o si se transmiten los campos expDateMonth
у expDateYear
name | Nombre del titular de la tarjeta | string | No
GESTIÓN DE ERRORES EN LA VALIDACIÓN DE DATOS DE TARJETAS:
const fieldValues = {
cvv: '91', // CVV no válido
cardNumber: '4242 4242 4242 424', // Número de tarjeta no válido
expDateMonth: '12',
expDateYear: '24',
}
checkout.createPaymentCryptogram(fieldValues)
.then((cryptogram) => {
console.log(cryptogram);
})
.catch((errors) => {
console.log(errors);
/* Resulta
{
cardNumber: "CardNumber_Invalid",
cvv: "Cvv_Invalid"
}
*/
});
Código de error | Descripción |
---|---|
CardNumber_Empty | Número de tarjeta en blanco |
CardNumber_Invalid | Número de tarjeta incorrecto |
Cvv_Empty | CVV en blanco |
Cvv_Invalid | CVV incorrecto |
ExpDateMonthYear_Empty | Año y mes en blanco |
ExpDateMonthYear_Invalid | Año y mes incorrectos |
ExpDateMonth_Empty | Mes en blanco |
ExpDateMonth_Invalid | Mes incorrecto |
ExpDateYear_Empty | Año en blanco |
ExpDateYear_Invalid | Año incorrecto |
Name_Empty | Nombre en blanco * |
Name_Invalid | Nombre incorrecto * |
Name_TooLong | Nombre demasiado largo * |
Name_TooShort | Nombre demasiado corto * |
MÉTODO PARA LA GENERACIÓN DE CRIPTOGRAMAS
El método devuelve un criptograma en caso de generación exitosa y un objeto con una lista de errores en caso de que existan errores en los datos de la tarjeta
Este método puede tomar como entrada un objeto con datos de la tarjeta y puede utilizarse en un esquema antiguo vinculado a un formulario HTML. Si se utiliza la vinculación del formulario y este mismo parámetro se encuentra en el objeto CardData, se producirá un error al intentar generar un criptograma.
Script para la creación del criptograma:
this.createCryptogram = function () {
var result = checkout.createCryptogramPacket();
if (result.success) {
// Se ha creado el criptograma
alert(result.packet);
}
else {
// se han detectado errores en los datos introducidos, objeto `result.messages` con formato:
// { name: "Hay demasiados caracteres en el nombre del titular de la tarjeta», cardNumber: "Número de tarjeta incorrecto" }
// donde `name`, `cardNumber` corresponden a los valores de los atributos `<input ... data-ttp="cardNumber">`
for (var msgName in result.messages) {
alert(result.messages[msgName]);
}
}
};
$(function () {
/* Creación de checkout */
checkout = new tiptop.Checkout(
// public id la cuenta personal
"test_api_00000000000000000000001",
// Etiqueta que contiene los campos con datos de la tarjeta
document.getElementById("paymentFormSample"));
});
API
API: interfaz de programación del sistema para interactuar con los sistemas de empresas comerciales y de servicios.
La interfaz opera en api.tiptoppay.mx es compatible con funciones para realizar pagos, cancelar pagos, reembolsar dinero, completar pagos en dos pasos, crear y cancelar suscripciones con pagos recurrentes, así como enviar facturas por correo.
Principio de funcionamiento
Los parámetros se transmiten utilizando el método POST en el cuerpo de la consulta según el formato "clave=valor" o en JSON.
La API no puede procesar más de 150,000 campos en una sola consulta. El tiempo de espera para obtener una respuesta de la API es de 5 minutos.
En todas las consultas a la API, si se transfiere un número con una parte fraccionaria a un campo entero, no se producirá ningún error, pero sí un redondeo matemático.
La API limita el número máximo de consultas simultáneas a 5 para terminales de prueba y a 30 para terminales operativos. Si el número de consultas al sitio web que se están procesando es superior al límite - la API devolverá una respuesta con el código HTTP 429 (Too many Requests) hasta que se complete el procesamiento de al menos una consulta. Si necesita modificar los límites, contacte a su gestor personal o a [email protected].
La elección del formato de transferencia de parámetros se determina en el lado del cliente y se gestiona a través del encabezado de la consulta Content-Type.
- Para los parámetros clave=valor» Content-Type: application/x-www-form-urlencoded;
- Para los parámetros JSON Content-Type Content-Type: application/json;
El sistema devuelve la respuesta en formato JSON, que incluye como mínimo dos parámetros: Success y Message:
{ "Success": false, "Message": "Invalid Amount value" }
Autenticación de consultas
Para autenticar una consulta se utiliza HTTP Basic Auth, que envía el nombre de usuario y la contraseña en el encabezado de la consulta HTTP. En calidad de nombre de usuario se utiliza Public ID y como contraseña se utiliza API Secret. Ambos valores se pueden obtener en el área personal del usuario de el panel de TipTop Pay.
Idempotencia de la API
Idempotencia: es una propiedad de la API que permite obtener en una consulta repetida el mismo resultado que en la consulta inicial, sin necesidad de volver a procesar. Esto significa que puede enviar varias consultas al sistema con el mismo identificador, pero solo se procesará una consulta exitosa y todas las respuestas serán idénticas. De esta forma se implementa la protección contra los errores de red que pueden causar duplicación de registros y acciones.
Para habilitar la idempotencia, deberá transferir en la consulta a la API un encabezado con la clave X-Request-ID que contenga un identificador único. La creación del identificador de la consulta queda de su parte: ésta puede ser un GUID, una combinación de número de pedido, fecha e importe o cualquier otro valor a su discreción.
Cada nueva consulta que necesite procesarse debe incluir un nuevo valor X-Request-ID. El resultado procesado se guarda en el sistema durante 1 hora.
Método de prueba
Para verificar la interacción con la API se puede recurrir a un método de prueba.
Dirección del método
https://api.tiptoppay.mx/test
Parámetros de la consulta:
Ninguno.
Ejemplo de respuesta:
Como respuesta, el método devuelve el estado de la consulta.
{"Success":true,"Message":"bd6353c3-0ed6-4a65-946f-083664bf8dbd"}
Pago mediante criptograma
Método para realizar pagos mediante un criptograma resultante de un algoritmo de cifrado. Para generar el criptograma, utilice el script Checkout.
Direcciones de los métodos::
https://api.tiptoppay.mx/payments/cards/charge
Parámetros de la consulta:
PARÁMETRO | FORMATO | APLICACIÓN | DESCRIPCIÓN |
---|---|---|---|
AMOUNT | NUMBER | OBLIGATORIO | IMPORTE DEL PAGO EN MONEDA, PUNTO COMO DELIMITADOR. EL NÚMERO DE SIGNOS DISTINTOS DE CERO DESPUÉS DEL PUNTO ES 2. |
CURRENCY | STRING | OPCIONAL | MONEDA: MXN/USD/EUR/GBP (CONSULTE EL MANUAL). SI NO SE TRANSFIERE EL PARÁMETRO, POR DEFECTO TOMARÁ EL VALOR MXN |
IPADDRESS | STRING | OBLIGATORIO | DIRECCIÓN IP DEL PAGADOR |
CARDCRYPTOGRAMPACKET | STRING | OBLIGATORIO | CRIPTOGRAMA DE LOS DATOS DE PAGO |
NAME | STRING | OPCIONAL | NOMBRE DEL TITULAR DE LA TARJETA EN CARACTERES LATINOS |
PAYMENTURL | STRING | OPCIONAL | DIRECCIÓN DEL SITIO WEB DESDE EL QUE SE LLAMA AL SCRIPT CHECKOUT |
INVOICEID | STRING | OPCIONAL | NÚMERO DE FACTURA O PEDIDO |
DESCRIPTION | STRING | OPCIONAL | DESCRIPCIÓN DEL PAGO EN FORMATO LIBRE |
CULTURENAME | STRING | OPCIONAL | IDIOMA DE LAS NOTIFICACIONES |
ACCOUNTID | STRING | OPCIONAL | IDENTIFICADOR OBLIGATORIO DE USUARIO PARA CREAR LA SUSCRIPCIÓN Y RECIBIR EL TOKEN |
STRING | OPCIONAL | CORREO ELECTRÓNICO DEL PAGADOR AL QUE SE ENVIARÁ EL RECIBO DE PAGO | |
PAYER | OBJECT | OPCIONAL | CAMPO ADICIONAL AL QUE SE TRANSFIERE LA INFORMACIÓN SOBRE EL PAGADOR. UTILICE LOS SIGUIENTES PARÁMETROS: FirstName , LastName , MiddleName , Birth , Street , Address , City , Country , Phone , Postcode |
JSONDATA | JSON | OPCIONAL | CUALQUIER OTRO DATO QUE VAYA A ASOCIARSE A LA OPERACIÓN |
En respuesta, el servidor devuelve un JSON con tres componentes:
- campo success — resultado de la consulta;
- campo message — descripción del error;
- objeto model — información detallada.
Posibles variantes de respuesta:
- Consulta creada incorrectamente:
success — false
message — descripción del error - Se requiere autenticación 3-D Secure:
success — false
model — información para realizar la autenticación - Operación rechazada:
success — false
model — información sobre la operación y el código de error - Operación aceptada:
success — true
model — información sobre la operación
Ejemplo de consulta para el pago mediante criptograma:
{
"Amount":10,
"Currency":"MXT",
"InvoiceId":"1234567",
"IpAddress": "123.123.123.123",
"Description":"Test",
"AccountId":"user_x",
"Name":"CARDHOLDER NAME",
"CardCryptogramPacket":"01492500008719030128SMfLeYdKp5dSQVIiO5l6ZCJiPdel4uDjdFTTz1UnXY+3QaZcNOW8lmXg0H670MclS4lI+qLkujKF4pR5Ri+T/E04Ufq3t5ntMUVLuZ998DLm+OVHV7FxIGR7snckpg47A73v7/y88Q5dxxvVZtDVi0qCcJAiZrgKLyLCqypnMfhjsgCEPF6d4OMzkgNQiynZvKysI2q+xc9cL0+CMmQTUPytnxX52k9qLNZ55cnE8kuLvqSK+TOG7Fz03moGcVvbb9XTg1oTDL4pl9rgkG3XvvTJOwol3JDxL1i6x+VpaRxpLJg0Zd9/9xRJOBMGmwAxo8/xyvGuAj85sxLJL6fA=="
"Payer":
{
"FirstName":"Test",
"LastName":"Test",
"MiddleName":"Test",
"Birth":"1955-02-24",
"Address":"test address",
"Street":"Street",
"City":"City",
"Country":"MX",
"Phone":"123",
"Postcode":"345"
}
}
Ejemplo de respuesta: consulta incorrecta:
{"Success":false,"Message":"Amount is required"}
Ejemplo de respuesta: se requiere autenticación 3-D Secure:
{
"Model": {
"TransactionId": 891463508,
"PaReq": "+/eyJNZXJjaGFudE5hbWUiOm51bGwsIkZpcnN0U2l4IjoiNDI0MjQyIiwiTGFzdEZvdXIiOiI0MjQyIiwiQW1vdW50IjoxMDAuMCwiQ3VycmVuY3lDb2RlIjoiUlVCIiwiRGF0ZSI6IjIwMjEtMTAtMjVUMDA6MDA6MDArMDM6MDAiLCJDdXN0b21lck5hbWUiOm51bGwsIkN1bHR1cmVOYW1lIjoicnUtUlUifQ==",
"GoReq": null,
"AcsUrl": "https://demo.tiptoppay.mx/acs",
"ThreeDsSessionData": null,
"IFrameIsAllowed": true,
"FrameWidth": null,
"FrameHeight": null,
"ThreeDsCallbackId": "7be4d37f0a434c0a8a7fc0e328368d7d",
"EscrowAccumulationId": null
},
"Success": false,
"Message": null
}
Ejemplo de respuesta: operación rechazada. En el campo código de error ReasonCode (consulte el manual):
{
"Model": {
"ReasonCode": 5051,
"PublicId": "pk_**********************************",
"TerminalUrl": "http://test.test",
"TransactionId": 891583633,
"Amount": 10,
"Currency": "MXN",
"CurrencyCode": 0,
"PaymentAmount": 10,
"PaymentCurrency": "MXN",
"PaymentCurrencyCode": 0,
"InvoiceId": "1234567",
"AccountId": "user_x",
"Email": null,
"Description": "Test",
"JsonData": null,
"CreatedDate": "/Date(1635154784619)/",
"PayoutDate": null,
"PayoutDateIso": null,
"PayoutAmount": null,
"CreatedDateIso": "2021-10-25T09:39:44",
"AuthDate": null,
"AuthDateIso": null,
"ConfirmDate": null,
"ConfirmDateIso": null,
"AuthCode": null,
"TestMode": true,
"Rrn": null,
"OriginalTransactionId": null,
"FallBackScenarioDeclinedTransactionId": null,
"IpAddress": "123.123.123.123",
"IpCountry": "CN",
"IpCity": "Beijing",
"IpRegion": "Beijing",
"IpDistrict": "Beijing",
"IpLatitude": 39.9289,
"IpLongitude": 116.3883,
"CardFirstSix": "400005",
"CardLastFour": "5556",
"CardExpDate": "12/25",
"CardType": "Visa",
"CardProduct": null,
"CardCategory": null,
"EscrowAccumulationId": null,
"IssuerBankCountry": "US",
"Issuer": "ITS Bank",
"CardTypeCode": 0,
"Status": "Declined",
"StatusCode": 5,
"CultureName": "kk",
"Reason": "InsufficientFunds",
"CardHolderMessage": "InsufficientFunds",
"Type": 0,
"Refunded": false,
"Name": "CARDHOLDER NAME",
"Token": "tk_255c42192323f2e09ea17635302c3",
"SubscriptionId": null,
"GatewayName": "Test",
"ApplePay": false,
"AndroidPay": false,
"WalletType": "",
"TotalFee": 0
},
"Success": false,
"Message": null
}
Ejemplo de respuesta: operación aceptada:
{
"Model": {
"ReasonCode": 0,
"PublicId": "pk_********************************",
"TerminalUrl": "http://test.test",
"TransactionId": 891510444,
"Amount": 10,
"Currency": "MXN",
"CurrencyCode": 0,
"PaymentAmount": 10,
"PaymentCurrency": "MXN",
"PaymentCurrencyCode": 0,
"InvoiceId": "1234567",
"AccountId": "user_x",
"Email": null,
"Description": "Test",
"JsonData": null,
"CreatedDate": "/Date(1635150224630)/",
"PayoutDate": null,
"PayoutDateIso": null,
"PayoutAmount": null,
"CreatedDateIso": "2021-10-25T08:23:44",
"AuthDate": "/Date(1635150224739)/",
"AuthDateIso": "2021-10-25T08:23:44",
"ConfirmDate": null,
"ConfirmDateIso": null,
"AuthCode": "A1B2C3",
"TestMode": true,
"Rrn": null,
"OriginalTransactionId": null,
"FallBackScenarioDeclinedTransactionId": null,
"IpAddress": "123.123.123.123",
"IpCountry": "CN",
"IpCity": "Beijing",
"IpRegion": "Beijing",
"IpDistrict": "Beijing",
"IpLatitude": 39.9289,
"IpLongitude": 116.3883,
"CardFirstSix": "411111",
"CardLastFour": "1111",
"CardExpDate": "11/25",
"CardType": "Visa",
"CardProduct": "C",
"CardCategory": "Visa Signature (Signature)",
"EscrowAccumulationId": null,
"IssuerBankCountry": "MX",
"Issuer": "TipTop Pay",
"CardTypeCode": 0,
"Status": "Authorized",
"StatusCode": 2,
"CultureName": "kk",
"Reason": "Approved",
"CardHolderMessage": "Payment success",
"Type": 0,
"Refunded": false,
"Name": "CARDHOLDER NAME",
"Token": "0a0afb77-8f41-4de2-9524-1057f9695303",
"SubscriptionId": null,
"GatewayName": "Test",
"ApplePay": false,
"AndroidPay": false,
"WalletType": "",
"TotalFee": 0
},
"Success": true,
"Message": null
}
Procesamiento Secure 3-D
Para realizar la autenticación 3-D Secure, deberá enviar al pagador a la dirección especificada en el parámetro AcsUrl de la la respuesta del servidor con siguientes parámetros:
- MD — Parámetro TransactionId de la respuesta del servidor;
- PaReq — parámetro homónimo de la respuesta del servidor;
- TermUrl — dirección en su sitio web para redirigir al pagador después de la autenticación.
EJEMPLO DE FORMULARIO:
<form name="downloadForm" action="AcsUrl" method="POST">
<input type="hidden" name="PaReq" value="eJxVUdtugkAQ/RXDe9mLgo0Z1nhpU9PQasWmPhLYAKksuEChfn13uVR9mGTO7MzZM2dg3qSn0Q+X\nRZIJxyAmNkZcBFmYiMgxDt7zw6MxZ+DFkvP1ngeV5AxcXhR+xEdJ6BhpEZnEYLBdfPAzg56JKSKT\nAhqgGpFB7IuSgR+cl5s3NqFTG2NAPYSUy82aETqeWPYUUAdB+ClnwSmrwtz/TbkoC0BtDYKsEqX8\nZfZkDGgAUMkTi8synyFU17V5N2nKCpBuAHRVs610VijCJgmZu17UXTxhFWP34l7evYPlegsHkO6A\n0C85o5hMsI3piNIZHc+IBaitg59qJYzgdrUOQK7/WNy+3FZAeSqV5cMqAwLe5JlQwpny8T8HdFW8\netFuBqUyahV+Hjf27vWCaSx22fe+KY6kXKZfJLK1x22TZkyUS8QiHaUGgDQN6s+H+tOq7O7kf8hd\nt30=">
<input type="hidden" name="MD" value="504">
<input type="hidden" name="TermUrl" value="https://example.com/post3ds?order=1234567">
</form>
<script>
window.onload = submitForm;
function submitForm() { downloadForm.submit(); }
</script>
Para completar su pago, utilice el siguiente método Post3ds.
Dirección del método:
https://api.tiptoppay.mx/payments/cards/post3ds
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
TransactionId | Long | Obligatorio | Valor del parámetro MD |
PaRes | String | Obligatorio | Valor del parámetro homónimo |
En respuesta a una consulta correctamente formulada, el servidor devolverá información sobre la transacción exitosa o sobre la operación rechazada.
Pago con token (pago recurrente)
Método de pago mediante un token obtenido al pagar con criptograma o a través de la notificación Pay.
Dirección del método::
https://api.tiptoppay.mx/payments/tokens/charge
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
Amount | Number | Obligatorio | Importe del pago en moneda, punto como delimitador. El número de signos distintos de cero después del punto es 2. |
Currency | String | Opcional | Moneda: MXN/USD/EUR/GBP (consulte el manual). Si no se transfiere el parámetro, por defecto tomará el valor MXN |
AccountId | String | Obligatorio | Identificador del usuario |
TrInitiatorCode | Int | Opcional | Signo del iniciador del cargo de fondos. Valores posibles: 0 - la operación es iniciada por la empresa comercial y de servicios sobre la base de credenciales previamente guardadas; 1 - la operación es iniciada por el titular de la tarjeta (cliente) sobre la base de credenciales previamente guardadas. |
Token | String | Obligatorio | Token |
InvoiceId | String | Opcional | Número de factura o pedido |
Description | String | Opcional | Propósito del pago en formato libre |
IpAddress | String | Opcional | Dirección IP del pagador |
String | Opcional | Correo electrónico del pagador al que se enviará el recibo de pago | |
Payer | Object | Opcional | Campo adicional al que se transfiere la información sobre el pagador. Utilice los siguientes parámetros: FirstName , LastName , MiddleName , Birth , Street , Address , City , Country , Phone , Postcode |
JsonData | Json | Opcional | Cualquier otro dato que vaya a asociarse a la operación |
En respuesta, el servidor devuelve un JSON con tres componentes: el campo success — resultado de la consulta, el campo message — descripción del error, el objeto model — información detallada.
POSIBLES OPCIONES
- Consulta creada incorrectamente:
success — false
message — descripción del error - Operación rechazada:
success — false
model — información sobre la operación y el código de error - Operación aceptada:
success — true
model — información sobre la operación
Ejemplo de consulta de pago por token:
{
"Amount":59,
"Currency":"MXN",
"InvoiceId":"1234567",
"Description":"Description example",
"AccountId":"user_x",
"Token":"success_1111a3e0-2428-48fb-a530-12815d90d0e8",
"Payer":
{
"FirstName":"Test",
"LastName":"Test",
"MiddleName":"Test",
"Birth":"1955-02-24",
"Address":"test address",
"Street":"Street",
"City":"City",
"Country":"MX",
"Phone":"123",
"Postcode":"345"
}
}
Ejemplo de respuesta: consulta incorrecta
{"Success":false,"Message":"Amount is required"}
Ejemplo de respuesta: operación rechazada. En el campo código de error ReasonCode (consulte el manual)
{
"Model": {
"ReasonCode": 5051,
"PublicId": "pk_**********************************",
"TerminalUrl": "http://test.test",
"TransactionId": 891583633,
"Amount": 100,
"Currency": "MXN",
"CurrencyCode": 0,
"PaymentAmount": 100,
"PaymentCurrency": "MXN",
"PaymentCurrencyCode": 0,
"InvoiceId": "1234567",
"AccountId": "user_x",
"Email": null,
"Description": "Decription test",
"JsonData": null,
"CreatedDate": "/Date(1635154784619)/",
"PayoutDate": null,
"PayoutDateIso": null,
"PayoutAmount": null,
"CreatedDateIso": "2021-10-25T09:39:44",
"AuthDate": null,
"AuthDateIso": null,
"ConfirmDate": null,
"ConfirmDateIso": null,
"AuthCode": null,
"TestMode": true,
"Rrn": null,
"OriginalTransactionId": null,
"FallBackScenarioDeclinedTransactionId": null,
"IpAddress": "123.123.123.123",
"IpCountry": "CN",
"IpCity": "Beijing",
"IpRegion": "Beijing",
"IpDistrict": "Beijing",
"IpLatitude": 39.9289,
"IpLongitude": 116.3883,
"CardFirstSix": "400005",
"CardLastFour": "5556",
"CardExpDate": "12/25",
"CardType": "Visa",
"CardProduct": null,
"CardCategory": null,
"EscrowAccumulationId": null,
"IssuerBankCountry": "US",
"Issuer": "ITS Bank",
"CardTypeCode": 0,
"Status": "Declined",
"StatusCode": 5,
"CultureName": "mx",
"Reason": "InsufficientFunds",
"Type": 0,
"Refunded": false,
"Name": "CARDHOLDER NAME",
"Token": "tk_255c42192323f2e09ea17635302c3",
"SubscriptionId": null,
"GatewayName": "Test",
"ApplePay": false,
"AndroidPay": false,
"WalletType": "",
"TotalFee": 0
},
"Success": false,
"Message": null
}
Ejemplo de respuesta: operación aceptada
{
"Model": {
"ReasonCode": 0,
"PublicId": "pk_**************************",
"TerminalUrl": "http://test.test",
"TransactionId": 897728064,
"Amount": 59,
"Currency": "MXN",
"CurrencyCode": 0,
"PaymentAmount": 59,
"PaymentCurrency": "MXN",
"PaymentCurrencyCode": 0,
"InvoiceId": 1234567,
"AccountId": "user_x",
"Email": null,
"Description": "Decription test",
"JsonData": null,
"CreatedDate": "/Date(1635562705992)/",
"PayoutDate": null,
"PayoutDateIso": null,
"PayoutAmount": null,
"CreatedDateIso": "2021-10-30T02:58:25",
"AuthDate": "/Date(1635562706070)/",
"AuthDateIso": "2021-10-30T02:58:26",
"ConfirmDate": "/Date(1635562706070)/",
"ConfirmDateIso": "2021-10-30T02:58:26",
"AuthCode": "A1B2C3",
"TestMode": true,
"Rrn": null,
"OriginalTransactionId": null,
"FallBackScenarioDeclinedTransactionId": null,
"IpAddress": "87.251.91.164",
"IpCountry": "MX",
"IpCity": "City",
"IpRegion": "Region",
"IpDistrict": "District",
"IpLatitude": 55.03923,
"IpLongitude": 82.927818,
"CardFirstSix": "424242",
"CardLastFour": "4242",
"CardExpDate": "12/25",
"CardType": "Visa",
"CardProduct": "I",
"CardCategory": "Visa Infinite Infinite",
"EscrowAccumulationId": null,
"IssuerBankCountry": "MX",
"Issuer": "TipTop Pay",
"CardTypeCode": 0,
"Status": "Completed",
"StatusCode": 3,
"CultureName": "mx",
"Reason": "Approved",
"CardHolderMessage": "Payment has been successfully completed",
"Type": 0,
"Refunded": false,
"Name": "SER",
"Token": "success_1111a3e0-2428-48fb-a530-12815d90d0e8",
"SubscriptionId": null,
"GatewayName": "Test",
"ApplePay": false,
"AndroidPay": false,
"WalletType": "",
"TotalFee": 0
},
"Success": true,
"Message": null
}
Confirmación de pago
Para los pagos realizados bajo el esquema de dos etapas, se requiere la confirmación del pago, que puede realizarse a través del Área personal o utilizando un método API.
Dirección del método:
https://api.tiptoppay.mx/payments/confirm
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
TransactionId | Long | Obligatorio | Número de operación en el sistema |
Amount | Number | Obligatorio | Importe de la confirmación en la moneda de la operación, punto como delimitador. El número de signos distintos de cero después del punto es 2. |
JsonData | Json | Opcional | Cualquier otro dato asociado con la operación |
Ejemplo de consulta:
{"TransactionId":455,"Amount":65.98}
Ejemplo de respuesta:
{"Success":true,"Message":null}
Anulación del pago
La cancelación del pago se puede realizar a través del Área personal o utilizando un método API.
Dirección del método:
https://api.tiptoppay.mx/payments/void
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
TransactionId | Long | Obligatorio | Número de operación en el sistema |
Ejemplo de consulta:
{"TransactionId":455}
Ejemplo de respuesta:
{"Success":true,"Message":null}
Reembolso de fondos
El reembolso se puede efectuar a través del Área personal o utilizando un método API.
Dirección del método:
https://api.tiptoppay.mx/payments/refund
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
TransactionId | Long | Obligatorio | Número de operación de pago |
Amount | Number | Obligatorio | Importe del reembolso en la moneda de la operación, punto como delimitador. El número de signos distintos de cero después del punto es 2. |
JsonData | Json | Opcional | Cualquier otro dato asociado con la operación |
Ejemplo de consulta:
{"TransactionId":455, "Amount": 100}
Ejemplo de respuesta:
{
"Model": {
"TransactionId": 568
},
"Success": true,
"Message": null
}
Cash payments
Dirección del método:
https://api.tiptoppay.mx/payments/altpay/pay
Ejemplo de consulta:
{
"PublicId": "pk_**************************",
"Amount": 100,
"Currency": "MXN",
"Description": "A basket of oranges",
"CultureName": "en",
"PaymentUrl": "https://www.google.com",
"InvoiceId": "42",
"AccountId": "[email protected]",
"Scenario": 3,
"AltPayType": "CashOxxo",
"Scheme": 0,
"ReturnRedirectUrl": "{redirectUrl}"
"Email": "[email protected]",
"Payer": {
"FirstName": "Client",
"Email": "[email protected]"
}
}
Dependiendo de la tienda seleccionada en la consulta POST: /payments/altpay/pay, se enviará uno u otro AltPayType
Tiendas de conveniencia:
AltPayType = CashCStores
OXXO:
AltPayType = CashOxxo
Farmacias:
AltPayType = CashFarmacias
Pago SPEI
Dirección del método:
https://api.tiptoppay.mx/payments/altpay/pay
Ejemplo de consulta:
{
"PublicId": "pk_**************************",
"AltPayType": 5,
"Scenario": 3,
"Amount": 111,
"Currency": "MXN",
"Description": "SPEI",
"Email": "[email protected]",
"InvoiceId": "20",
"JsonData": null,
"CultureName": "es-ES"
}
Ejemplo de respuesta:
{
"Model": {
"transactionId": 0,
"providerTransactionId": "string",
"status": "Unknown",
"statusCode": 0,
"extensionData": {
"clabe": 0,
"expiredDate": "2022-07-10T05:05:40.078Z",
"link": "string",
"gateway": "string"
},
"amount": 0,
},
"Success": true,
"Message": "string"
}
Ejemplo de respuesta: en caso de formato incorrecto de consulta
{
"ErrorCode": "400",
}
Ejemplo de respuesta: ya se ha generado una cuenta CLABE para este transactionId
{
"ErrorCode": "401",
"ErrorMessage": "CLABE account has already been generated for this TransactionID"
}
Ejemplo de respuesta: todos los valores únicos para la cuenta CLABE están ocupados
{
"ErrorCode": "402",
"ErrorMessage": "All unique values for the CLABE account are occupied"
}
Ejemplo de respuesta: error interno del servidor
{
"ErrorCode": "500",
}
Creación de una suscripción con pagos recurrentes
Método para creación de una suscripción con pagos recurrentes.
Dirección del método:
https://api.tiptoppay.mx/subscriptions/create
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
Token | String | Obligatorio | Token de la tarjeta, emitido por el sistema tras el primer pago |
AccountId | String | Obligatorio | Identificador del usuario |
Description | String | Obligatorio | Propósito del pago en formato libre |
String | Opcional | Correo electrónico del pagador | |
Amount | Number | Obligatorio | Importe del pago en moneda, punto como delimitador. El número de signos distintos de cero después del punto es 2. |
Currency | String | Obligatorio | Moneda: MXN/USD/EUR/GBP (consulte el manual) |
RequireConfirmation | Bool | Obligatorio | Si el valor es true, los pagos se efectuarán según un esquema de dos etapas |
StartDate | DateTime | Obligatorio | Fecha y hora del primer pago programado en la zona horaria UTC. El valor debe estar en el futuro |
Interval | String | Obligatorio | Intervalo. Posibles valores: Day, Week, Month |
Period | Int | Obligatorio | Periodo. En combinación con el intervalo, 1 Month significa una vez al mes y 2 Week significa una vez cada quince días. Debe ser mayor que 0 |
MaxPeriods | Int | Opcional | Número máximo de pagos en una suscripción. Si se indica, debe ser mayor que 0 |
En respuesta a una consulta generada correctamente, el sistema devolverá un mensaje sobre una operación completada correctamente y el identificador de la suscripción.
Ejemplo de consulta:
{
"token": "477BBA133C182267FE5F086924ABDC5DB71F77BFC27F01F2843F2CDC69D89F05",
"accountId": "user_x",
"description": "Subscription on example.com",
"email": "[email protected]",
"amount": 399,
"Currency": "MXN",
"requireConfirmation": false,
"startDate": "2021-11-02T21:00:00",
"interval": "Day",
"period": 5
}
Ejemplo de respuesta:
{
"Model": {
"Id": "sc_221da6421dc44dbd2cc3464f6f083",
"AccountId": "user_x",
"Description": "Subscription on example.com",
"Email": "[email protected]",
"Amount": 399,
"CurrencyCode": 0,
"Currency": "MXN",
"RequireConfirmation": false,
"StartDate": "/Date(1635886800000)/",
"StartDateIso": "2021-11-02T21:00:00",
"IntervalCode": 2,
"Interval": "Day",
"Period": 5,
"MaxPeriods": null,
"CultureName": "mx",
"StatusCode": 0,
"Status": "Active",
"SuccessfulTransactionsNumber": 0,
"FailedTransactionsNumber": 0,
"LastTransactionDate": null,
"LastTransactionDateIso": null,
"NextTransactionDate": "/Date(1635886800000)/",
"NextTransactionDateIso": "2021-11-02T21:00:00",
"FailoverSchemeId": null
},
"Success": true,
"Message": null
}
Solicitud de información sobre la suscripción
Método para obtener información sobre el estado de la suscripción.
Dirección del método:
https://api.tiptoppay.mx/subscriptions/get
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
Id | String | Obligatorio | ID de la suscripción |
Ejemplo de consulta:
{"Id":"sc_8cf8a9338fb8ebf7202b08d09c938"}
Ejemplo de respuesta:
{
"Model": {
"Id": "sc_8cf8a9338fb8ebf7202b08d09c938",
"AccountId": "user_x",
"Description": null,
"Email": "[email protected]",
"Amount": 399,
"CurrencyCode": 0,
"Currency": "MXN",
"RequireConfirmation": false,
"StartDate": "/Date(1635886800000)/",
"StartDateIso": "2021-11-02T21:00:00",
"IntervalCode": 2,
"Interval": "Day",
"Period": 5,
"MaxPeriods": null,
"CultureName": "mx",
"StatusCode": 3,
"Status": "Cancelled",
"SuccessfulTransactionsNumber": 0,
"FailedTransactionsNumber": 0,
"LastTransactionDate": null,
"LastTransactionDateIso": null,
"NextTransactionDate": null,
"NextTransactionDateIso": null,
"Receipt": null,
"FailoverSchemeId": null
},
"Success": true,
"Message": null
}
Búsqueda de suscripciones
Método para obtener una lista de suscripciones para una cuenta específica.
Dirección del método:
https://api.tiptoppay.mx/subscriptions/find
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
accountId | String | Obligatorio | Identificador del usuario |
Ejemplo de consulta:
{"accountId":"[email protected]"}
Ejemplo de respuesta:
{
"Model": [
{
"Id": "sc_221da6421dc44dbd2cc3464f6f083",
"AccountId": "user_x",
"Description": null,
"Email": "[email protected]",
"Amount": 399,
"CurrencyCode": 0,
"Currency": "MXN",
"RequireConfirmation": false,
"StartDate": "/Date(1635886800000)/",
"StartDateIso": "2021-11-02T21:00:00",
"IntervalCode": 2,
"Interval": "Day",
"Period": 5,
"MaxPeriods": null,
"CultureName": "mx",
"StatusCode": 3,
"Status": "Cancelled",
"SuccessfulTransactionsNumber": 0,
"FailedTransactionsNumber": 0,
"LastTransactionDate": null,
"LastTransactionDateIso": null,
"NextTransactionDate": null,
"NextTransactionDateIso": null,
"FailoverSchemeId": null
},
{
"Id": "sc_3ffc96c001e152b341817341b075a",
"AccountId": "user_x",
"Description": null,
"Email": "[email protected]",
"Amount": 999,
"CurrencyCode": 0,
"Currency": "MXN",
"RequireConfirmation": false,
"StartDate": "/Date(1635973200000)/",
"StartDateIso": "2021-11-03T21:00:00",
"IntervalCode": 2,
"Interval": "Day",
"Period": 5,
"MaxPeriods": null,
"CultureName": "mx",
"StatusCode": 0,
"Status": "Active",
"SuccessfulTransactionsNumber": 0,
"FailedTransactionsNumber": 0,
"LastTransactionDate": null,
"LastTransactionDateIso": null,
"NextTransactionDate": "/Date(1635973200000)/",
"NextTransactionDateIso": "2021-11-03T21:00:00",
"FailoverSchemeId": null
}
],
"Success": true,
"Message": null
}
Modificación de una suscripción con pagos recurrentes
Método para modificar una suscripción creada previamente.
Dirección del método:
https://api.tiptoppay.mx/subscriptions/update
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
Id | String | Obligatorio | ID de la suscripción |
Description | String | Opcional | Para cambiar la finalidad del pago |
Amount | Number | Opcional | Para modificar el importe de pago en la moneda, punto como delimitador. El número de signos distintos de cero después del punto es 2. |
Currency | String | Opcional | Moneda: MXN/USD/EUR/GBP (consulte el manual) |
RequireConfirmation | Bool | Opcional | Para cambiar el sistema de pago |
StartDate | DateTime | Opcional | Para cambiar la fecha y hora del primer o siguiente pago en la zona horaria UTC |
Interval | String | Opcional | Para cambiar el intervalo. Posibles valores: Day, Week, Month |
Period | Int | Opcional | Para cambiar el periodo. En combinación con el intervalo, 1 Month significa una vez al mes y 2 Week significa una vez cada quince días |
MaxPeriods | Int | Opcional | Para cambiar el número máximo de pagos en una suscripción |
CultureName | String | Opcional | Idioma de las notificaciones |
En respuesta a una consulta generada correctamente, el sistema devolverá un mensaje sobre una operación completada correctamente y los parámetros de la suscripción.
Ejemplo de consulta:
{
"Id":"sc_3ffc96c001e152b341817341b075a",
"description":"cambio de recurrencia",
"amount":499,
"Currency":"MXN"
}
Ejemplo de respuesta:
{
"Model": {
"Id": "sc_3ffc96c001e152b341817341b075a",
"AccountId": "user_x",
"Description": "cambio de recurrencia",
"Email": "[email protected]",
"Amount": 499,
"CurrencyCode": 0,
"Currency": "MXN",
"RequireConfirmation": false,
"StartDate": "/Date(1635973200000)/",
"StartDateIso": "2021-11-03T21:00:00",
"IntervalCode": 2,
"Interval": "Day",
"Period": 2,
"MaxPeriods": null,
"CultureName": "mx",
"StatusCode": 0,
"Status": "Active",
"SuccessfulTransactionsNumber": 0,
"FailedTransactionsNumber": 0,
"LastTransactionDate": null,
"LastTransactionDateIso": null,
"NextTransactionDate": "/Date(1635973200000)/",
"NextTransactionDateIso": "2021-11-03T21:00:00",
"FailoverSchemeId": null
},
"Success": true,
"Message": null
}
Cancelación de una suscripción con pagos recurrentes
Método de cancelación de una suscripción con pagos recurrentes.
Dirección del método:
https://api.tiptoppay.mx/subscriptions/cancel
Parámetros de la consulta:
Parámetro | Formato | Aplicación | Descripción |
---|---|---|---|
Id | String | Obligatorio | ID de la suscripción |
En respuesta a una consulta generada correctamente, el sistema devolverá un mensaje sobre la operación completada correctamente.
Ejemplo de consulta:
{"Id":"sc_cc673fdc50b3577e60eee9081e440"}
Ejemplo de respuesta:
{"Success":true,"Message":null}
Solicitud de ajustes del terminal
Método para obtener los métodos de pago disponibles por el ID público del terminal, que se transmite en el parámetro query.
Dirección del método:
https://api.tiptoppay.mx/merchant/configuration/?terminalPublicId=?&paymentUrl=?&language=?
Parámetros de la solicitud:
№ de orden | Nombre | Tipo | Tipo de datos | Descripción |
---|---|---|---|---|
1 | terminalPublicId | query | string | ID público del terminal |
2 | paymentUrl | query | string | la dirección del sitio desde el que se realiza la llamada |
3 | language | query | enum |
localización |
Ejemplo de solicitud:
https://api.tiptoppay.mx/merchant/configuration/?terminalPublicId=pk_798df82a361070a52485c827dc6f4&paymentUrl=https%3A%2F%2Fdemo-pre-mx.tiptoppay.mx&language=es
Ejemplo de respuesta:
{
"Model": {
"LogoUrl": "https://static.tiptoppay.mx/test_api_00000000000000000000002/logo.PNG",
"TerminalUrl": "demo.tiptoppay.mx",
"TerminalFullUrl": "https://demo.tiptoppay.mx",
"WidgetUrl": "https://widget.tiptoppay.mx/",
"IsCharity": false,
"IsTest": true,
"TerminalName": "Demo site",
"SkipExpiryValidation": true,
"AgreementPath": "",
"IsCvvRequired": true,
"ExternalPaymentMethods": [
{
"Type": 16,
"Enabled": true
}
],
"Features": {
"IsAllowedNotSanctionedCards": true,
"IsQiwi": false,
"IsForeignCurrencyGateway": false,
"IsSaveCard": 2,
"IsPayOrderingEnabled": true,
"IsThreeCardInput": true
},
"SupportedCards": [
0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15,
16,
17,
100
],
"DisplayAdvertiseBannerOnWidget": false,
"BannerAdvertiseUrl": null,
"Status": 0
},
"Success": true,
"Message": null,
"ErrorCode": null
}
Obtención de datos para el pago a plazos con tarjeta
Endpoint está diseñado para obtener los periodos de pago a plazos disponibles para las compras a plazos y el importe mensual aproximado de pago para estos periodos.
Dirección del método:
https://api.tiptoppay.mx/installments/calculate/sum-by-period?amount=&terminalPublicId=
Parámetros de la solicitud:
№ de orden | Nombre | Tipo | Tipo de datos | Descripción |
---|---|---|---|---|
1 | terminalPublicId | query | string | ID público del terminal |
2 | amount | query | decimal | importe del pago a plazos con tarjeta |
Ejemplo de solicitud:
https://api.tiptoppay.mx/installments/calculate/sum-by-period?terminalPublicId=pk_798df82a361070a52485c827dc6f4&amount=110
Ejemplo de respuesta:
{
"Model": {
"IsCardInstallmentAvailable": true,
"Configuration": [
{
"Term": 3,
"MonthlyPayment": 36.67
}
]
},
"Success": true,
"Message": null,
"ErrorCode": null
}
Verificación de tarjeta por bin
El método está destinado a obtener información precisa sobre una tarjeta bancaria a partir de sus seis, siete u ocho primeros dígitos.
Dirección del método:
https://api.tiptoppay.mx/bins/info?Bin=¤cy=&amount=&isAllowedNotSanctionedCards=&isQiwi=&IsCheckCard=&TerminalPublicId=&SevenNumberHash=&EightNumberHash=
Parámetros de la solicitud:
Campo | Tipo | Tipo de datos | Descripción |
---|---|---|---|
Bin | query | string | 6 primeros dígitos del número de la tarjeta |
currency | query | string | moneda de la operación |
amount | query | decimal | importe de la operación |
isAllowedNotSanctionedCards | query | boolean | soporte para tarjetas no sancionadas |
isQiwi | query | boolean | si la pasarela desde la que se realiza el pago es la pasarela Qiwi |
isForeignCurrencyGateway | query | boolean | la pasarela desde la que se realiza el pago admite únicamente transacciones en moneda extranjera |
SevenNumberHash | query | string | hash de los siete primeros dígitos del número de tarjeta |
EightNumberHash | query | string | hash de los ocho primeros dígitos del número de tarjeta |
TerminalPublicId | query | string | el ID público del terminal es necesario para verificar en la tarjeta la posibilidad de pagar a plazos |
IsCheckCard | query | boolean | se utiliza para la verificación de la tarjeta para el pago a plazos con tarjeta true - verificamos la tarjeta false - no verificamos la tarjeta asegúrese de transmitir el valor true para comprobar si la tarjeta permite la posibilidad de pago a plazos |
Ejemplo de solicitud:
https://api.tiptoppay.mx/bins/info?Bin=400000¤cy=MXN&amount=110&isAllowedNotSanctionedCards=true&isQiwi=false&IsCheckCard=true&TerminalPublicId=pk_798df82a361070a52485c827dc6f4&SevenNumberHash=5033663954b22fc24d494bbf51402ee403bafc1ff40f35b7a1f5ae4e9e4b0ffe7598574ea0c8e56597f69b6f617a5fb37c278b3273c3ff6df3d6f9f4e16af052&EightNumberHash=68a1a1fd4de784e3a2e0e956d0a63ac4ca540ef90e7fd9a2ddc92cf68e52e29792db64f6615054a6e5460467f0b7abe055c899136d98ce6ebab3d580bc55ec86
Ejemplo de respuesta:
{
"Model": {
"LogoUrl": "",
"BankName": "Bank Banorte Mexico",
"Currency": null,
"ConvertedAmount": null,
"HideCvvInput": false,
"CardType": null,
"CountryCode": 484,
"IsCardAllowed": true
},
"Success": true,
"Message": null,
"ErrorCode": null
}
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 |
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 |
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 |
CustomFields | Array | Opcional | Campos personalizados transmitidos por el comerciante en la solicitud 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 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 |
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 |
CustomFields | Array | Opcional | Campos personalizados transmitidos por el comerciante en la solicitud 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 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 |
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 |
CustomFields | Array | Opcional | Campos personalizados transmitidos por el comerciante en la solicitud 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 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:
- 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.
Pago a plazos con tarjeta
TipTopPay ofrece el método de pago: pago a plazos con tarjeta. El pago a plazos con tarjeta solo está disponible para los titulares de tarjetas de crédito emitidas por un banco mexicano. Para activar el pago a plazos, debe ponerse en contacto con un gestor personal de TipTopPay.
Pago a plazos en el widget
Si el pago por un producto en el sitio web está disponible a plazos, el cliente verá un botón "Pagar en meses sin intereses" en el widget, al pulsarlo el cliente pasará a una página separada del widget.
En la página de pago a plazos, el cliente deberá introducir los datos de la tarjeta*, seleccionar el periodo de pago a plazos* y pulsar en Pagar.
*Los requerimientos para los datos de la tarjeta, y los plazos disponibles pueden ser precisados por su gestor personal en TipTopPay.
Para integrar el pago a plazos con tarjeta, debe realizar el siguiente procedimiento:
- Verifique si su sitio web permite el pago a plazos con tarjeta, para realizar la verificación necesita llamar al método
GET: /merchant/configuration/?terminalPublicId=&paymentUrl=&language=
- Si en la respuesta aparece la matriz "ExternalPaymentMethods" con
{ "Type": 16, "Enabled": true }
, significa que el pago a plazos está permitido en su sitio web. Es necesario para pasar al siguiente paso del algoritmo. - En caso contrario, el pago a plazos no está disponible en su terminal.
- Si en la respuesta aparece la matriz "ExternalPaymentMethods" con
- Obtenga los periodos disponibles para el pago a plazos y el importe mensual aproximado de dichos periodos para el pago de esta compra. Para ello, se debe llamar al método
GET: api/installments/calculate/sum-by-period?amount=&terminalPublicId=
- Si la respuesta es
IsCardInstallmentAvailable:false
, no será posible pagar esta compra a plazos. - Si la respuesta es
IsCardInstallmentAvailable:true
, en la matriz Configuration se mostrarán los periodos para pagar esta compra a plazos y el importe mensual aproximado de pago para cada periodo.
- Si la respuesta es
- Para realizar un pago a plazos, el cliente debe introducir los datos de la tarjeta que cumplan los requerimientos para el pago a plazos, seleccionar el periodo de pago a plazos y pulsar Pagar.
- Puede verificar los datos de la tarjeta por su cuenta o utilizar nuestro mecanismo para verificar la posibilidad de pagar a plazos.
- Para verificar los datos de la tarjeta y determinar la posibilidad de pagar a plazos con tarjetas en el sistema Tiptoppay, es necesario hacer una llamada a GET bins/info y a Path params además de los campos con el número de la tarjeta se debe transmitir
IsCheckCard:true
,TerminalPublicId: <su TerminalPublicId>
.- Si como respuesta aparece el campo
IsCardAllowed:true
, la tarjeta es apropiada para el pago a plazos. - Si en la respuesta aparece el campo
IsCardAllowed:false
, la tarjeta no es apropiada para el pago a plazos. El cliente debe indicar los datos de una tarjeta diferente. El pago a plazos con una tarjeta de este tipo será rechazado indiándose un error.
- Si como respuesta aparece el campo
- Para verificar los datos de la tarjeta y determinar la posibilidad de pagar a plazos con tarjetas en el sistema Tiptoppay, es necesario hacer una llamada a GET bins/info y a Path params además de los campos con el número de la tarjeta se debe transmitir
- Puede verificar los datos de la tarjeta por su cuenta o utilizar nuestro mecanismo para verificar la posibilidad de pagar a plazos.
- Para realizar una solicitud de pago a plazos, es necesario llamar al método
POST: /payments/cards/charge
, en cuyo cuerpo se deben transmitir los datos del pago a plazos en el campo InstallmentData. Consulte la descripción del campo por separado, en la descripción del método/payments/cards/charge
. En la respuesta, habrá recibido los datos para pasar la verificación 3DS. - Realice la verificación 3DS para el pago a plazos con tarjeta. El proceso de verificación 3DS no difiere de la verificación 3DS que se realiza para pagar con tarjeta sin cuotas. Si desea una descripción de la verificación 3DS, consulte la sección correspondiente.
- Después de pasar la verificación 3DS recibirá el resultado del pago a plazos con tarjeta. La descripción de los campos con el resultado del pago podrá consultarla en la descripción de los campos de respuesta al método
/payments/cards/charge
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:
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 |
5061 | Exceeds Approval Amount | Haz superado el límite de pago de la tarjeta. Realiza un aumento del límite dentro de la configuración de la tarjeta o te sugerimos utilizar otra tarjeta para completar tú pagó | El pago no pudo completarse: limite de la tarjeta excedido |
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 |
5302 | Reintento automático de autenticación | La autenticación 3DS es solicitada por Antifraude, se creará automáticamente una transacción subsiguiente | – |
6018 | No se admite el método de pago | No se admite el método de pago seleccionado | Utiliza otro metodo de pago |
6019 | No están configurados los límites del importe | No están configurados los límites del importe para realizar transacciones utilizando el método de pago seleccionado | Utiliza otro metodo de pago |
6020 | Plazo de MSI (Meses sin intereses) no encontrado | No se ha configurado el período de MSI (Meses sin intereses) para realizar transacciones utilizando el método de pago seleccionado | Utiliza otro metodo de pago |
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 |