todo-pago-sdk
v1.5.0
Published
<a name="inicio"></a> Todo Pago - módulo SDK-NodeJS para conexión con gateway de pago =======
Downloads
3
Maintainers
equipo_ecommerceReadme
Todo Pago - módulo SDK-NodeJS para conexión con gateway de pago
- Instalación
- Ambientes
- Uso
- Tablas de referencia
- Tabla de errores operativos
- Tabla de errores de integración
Instalación
Se debe descargar la última versión desde del botón Download ZIP o desde https://github.com/TodoPago/sdk-nodejs/archive/master.zip. Una vez descargado y descomprimido, debe incluirse el archivo todo-pago.js como módulo del proyecto.
Versiones de node soportadas
La versión implementada del SDK, esta testeada para versiones desde Node 0.10.x en adelante.
Generalidades
Esta versión soporta únicamente pago en moneda nacional argentina (CURRENCYCODE = 32).
Modo test
- Para utlilizar el modo test se debe pasar un end point de prueba (provisto por TODO PAGO).
var options = {
endpoint : "developers",
Authorization:'PRISMA f3d8b72c94ab4a06be2ef7c95490f7d3'
}; // End Point = "developers" para testUso
Inicializar la clase correspondiente al conector (todo-pago.js)
- Importar el módulo:
var sdk = require('../lib/todo-pago'); - Crear dos objetos (uno de configuración y el otro con los parámetros)
- La configuración debe contar con el ApiKey provisto por Todo Pago
var parameters = {
};
var options = {
endpoint : "developers", // "developers" o "production"
Authorization:'PRISMA f3d8b72c94ab4a06be2ef7c95490f7d3'
};- Los datos como Authorization , merchantId y ApiKey se pueden obtener mediante el método getCredentials Obtener Credenciales Volver a inicio
Operatoria Agrupador
Mediante una única y simple adhesión, los vendedores acceden a todos los medios de pago que el Botón de pago ofrezca sin necesidad de contar con ningún tipo de contrato adicional con cada medio de pago. La funcionalidad “agrupador” de TodoPago, se ocupa de gestionar los acuerdos necesarios con todos los medios de pago a efectos de disponibilizarlos en el Botón.
Para acceder al servicio, los vendedores podrán adherirse en el sitio exclusivo de TodoPago o a través de su ejecutivo comercial. En estos procesos se generará el usuario y clave para este servicio.
Una vez adheridos se creará automáticamente una cuenta virtual, en la cual se acreditarán los fondos provenientes de los cobros realizados con la presente modalidad de pago. Volver a inicio
Diagrama de secuencia
Solicitud de autorización
- En este caso hay que llamar a sendAuthorizeRequest(), el resultado se obtendrá mediante la funcion callback:
var parameters = {
'Session': 'ABCDEF-1234-12221-FDE1-00000200',
'Security':'f3d8b72c94ab4a06be2ef7c95490f7d3',
'EncodingMethod':'XML',
'Merchant':2153,
'URL_OK':'http://someurl.com/ok/',
'URL_ERROR':'http://someurl.com/fail/',
'MERCHANT': "2153",
'OPERATIONID':"60",
'CURRENCYCODE': "032",
'AMOUNT':"54",
'MAXINSTALLMENTS':"3",
'MAXINSTALLMENTS':"6"
};
//Control de Fraude
var fraudControl = {
'CSBTCITY': 'Villa General Belgrano',
'CSSTCITY': 'Villa General Belgrano',
'CSBTCOUNTRY': 'AR',
'CSSTCOUNTRY': 'AR',
'CSBTEMAIL': '[email protected]',
'CSSTEMAIL': '[email protected]',
'CSBTFIRSTNAME': 'Juan',
'CSSTFIRSTNAME': 'Juan',
'CSBTLASTNAME': 'Perez',
'CSSTLASTNAME': 'Perez',
'CSBTPHONENUMBER': '541160913988',
'CSSTPHONENUMBER': '541160913988',
'CSBTPOSTALCODE': ' 1010',
'CSSTPOSTALCODE': ' 1010',
'CSBTSTATE': 'B',
'CSSTSTATE': 'B',
'CSBTSTREET1': 'Cerrito 740',
'CSSTSTREET1': 'Cerrito 740',
'CSBTCUSTOMERID': '453458',
'CSBTIPADDRESS': '192.0.0.4',
'CSPTCURRENCY': 'ARS',
'CSPTGRANDTOTALAMOUNT': '99.00',
'CSMDD7': '',
'CSMDD8': 'Y',
'CSMDD9': '',
'CSMDD10': '',
'CSMDD11': '',
'CSMDD12': '',
'CSMDD13': '',
'CSMDD14': '',
'CSMDD15': '',
'CSMDD16': '',
'CSITPRODUCTCODE': 'electronic_good#chocho',
'CSITPRODUCTDESCRIPTION': 'NOTEBOOK L845 SP4304LA DF TOSHIBA#chocho',
'CSITPRODUCTNAME': 'NOTEBOOK L845 SP4304LA DF TOSHIBA#chocho',
'CSITPRODUCTSKU': 'LEVJNSL36GN#chocho',
'CSITTOTALAMOUNT': '1254.40#10.00',
'CSITQUANTITY': '1#1',
'CSITUNITPRICE': '1254.40#15.00'
};
sdk.sendAutorizeRequest(options, parameters, fraudControl, function(result, err){
console.log("------------- sendAutorizeRequest ---------------");
if(result){
console.log(result);
}
if(err){
console.error(err);
}
console.log("------------------------------------------------");
});Datos propios del comercio
Datos propios del comercio - Ejemplo
var parameters = {
'Session': 'ABCDEF-1234-12221-FDE1-00000200',
'Security':'f3d8b72c94ab4a06be2ef7c95490f7d3',
'EncodingMethod':'XML',
'Merchant':15846,
'URL_OK':'http://someurl.com/ok/',
'URL_ERROR':'http://someurl.com/fail/',
'MERCHANT': "2153",
'OPERATIONID':"60",
'CURRENCYCODE': "032",
'AMOUNT':"54",
'MAXINSTALLMENTS':"3",
'MAXINSTALLMENTS':"6"
};Datos propios de la operación
Respuesta
Datos adicionales para control de fraude
Los datos adicionales para control de fraude son obligatorios para la operatoria con TodoPago.
Parámetros Generales:
Parámetros del vertical "Retail":
Datos a enviar por cada producto, los valores deben estar separados con "#":
Parámetros Adicionales en el post inicial:
var payload = {
'CSBTCITY':'Villa General Belgrano', //Ciudad de facturación, MANDATORIO.
'CSBTCOUNTRY':'AR', //País de facturación. MANDATORIO. Código ISO. (http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf)
'CSBTCUSTOMERID':'453458', //Identificador del usuario al que se le emite la factura. MANDATORIO. No puede contener un correo electrónico.
'CSBTIPADDRESS':'192.0.0.4', //IP de la PC del comprador. MANDATORIO.
'CSBTEMAIL':'[email protected]', //Mail del usuario al que se le emite la factura. MANDATORIO.
'CSBTFIRSTNAME':'Juan' ,//Nombre del usuario al que se le emite la factura. MANDATORIO.
'CSBTLASTNAME':'Perez', //Apellido del usuario al que se le emite la factura. MANDATORIO.
'CSBTPHONENUMBER':'541160913988', //Teléfono del usuario al que se le emite la factura. No utilizar guiones, puntos o espacios. Incluir código de país. MANDATORIO.
'CSBTPOSTALCODE':'1010', //Código Postal de la dirección de facturación. MANDATORIO.
'CSBTSTATE':'B', //Provincia de la dirección de facturación. MANDATORIO. Ver tabla anexa de provincias.
'CSBTSTREET1':'Some Street 2153', //Domicilio de facturación (calle y nro). MANDATORIO.
'CSBTSTREET2':'Piso 8', //Complemento del domicilio. (piso, departamento). NO MANDATORIO.
'CSPTCURRENCY':'ARS', //Moneda. MANDATORIO.
'CSPTGRANDTOTALAMOUNT':'125.38', //Con decimales opcional usando el puntos como separador de decimales. No se permiten comas, ni como separador de miles ni como separador de decimales. MANDATORIO. (Ejemplos:$125,38-> 125.38 $12-> 12 o 12.00)
'CSMDD7':'', // Fecha registro comprador(num Dias). NO MANDATORIO.
'CSMDD8':'', //Usuario Guest? (Y/N). En caso de ser Y, el campo CSMDD9 no deberá enviarse. NO MANDATORIO.
'CSMDD9':'', //Customer password Hash: criptograma asociado al password del comprador final. NO MANDATORIO.
'CSMDD10':'', //Histórica de compras del comprador (Num transacciones). NO MANDATORIO.
'CSMDD11':'', //Customer Cell Phone. NO MANDATORIO.
//Retail
'CSSTCITY':'Villa General Belgrano', //Ciudad de envío de la orden. MANDATORIO.
'CSSTCOUNTRY':'', //País de envío de la orden. MANDATORIO.
'CSSTEMAIL':'[email protected]', //Mail del destinatario, MANDATORIO.
'CSSTFIRSTNAME':'Jose', //Nombre del destinatario. MANDATORIO.
'CSSTLASTNAME':'Perez', //Apellido del destinatario. MANDATORIO.
'CSSTPHONENUMBER':'541155893737', //Número de teléfono del destinatario. MANDATORIO.
'CSSTPOSTALCODE':'1010', //Código postal del domicilio de envío. MANDATORIO.
'CSSTSTATE':'B', //Provincia de envío. MANDATORIO. Son de 1 caracter
'CSSTSTREET1':'Some Street 2153', //Domicilio de envío. MANDATORIO.
'CSMDD12':'',//Shipping DeadLine (Num Dias). NO MADATORIO.
'CSMDD13':'',//Método de Despacho. NO MANDATORIO.
'CSMDD14':'',//Customer requires Tax Bill ? (Y/N). NO MANDATORIO.
'CSMDD15':'',//Customer Loyality Number. NO MANDATORIO.
'CSMDD16':'',//Promotional / Coupon Code. NO MANDATORIO.
//Datos a enviar por cada producto, los valores deben estar separado con #:
'CSITPRODUCTCODE':'electronic_good', //Código de producto. CONDICIONAL. Valores posibles(adult_content;coupon;default;electronic_good;electronic_software;gift_certificate;handling_only;service;shipping_and_handling;shipping_only;subscription)
'CSITPRODUCTDESCRIPTION':'Test Prd Description', //Descripción del producto. CONDICIONAL.
'CSITPRODUCTNAME':'TestPrd', //Nombre del producto. CONDICIONAL.
'CSITPRODUCTSKU':'SKU1234', //Código identificador del producto. CONDICIONAL.
'CSITTOTALAMOUNT':'10.01', //CSITTOTALAMOUNT=CSITUNITPRICE*CSITQUANTITY "999999[.CC]" Con decimales opcional usando el puntos como separador de decimales. No se permiten comas, ni como separador de miles ni como separador de decimales. CONDICIONAL.
'CSITQUANTITY':'1', //Cantidad del producto. CONDICIONAL.
'CSITUNITPRICE':'10.01', //Formato Idem CSITTOTALAMOUNT. CONDICIONAL.
...........................................................Opciones adicionales
Dentro del parámetro $optionsSAR_operacion pueden enviarse opciones adicionales que habilitan características para esa transacción en particular. A continuación se describen las mismas
Rango de Cuotas
Es posible setear el rango de cuotas a mostrar en el formulario entre un mínimo y un máximo, enviando los siguientes parametros adicionales
Tiempo de vida de la transacción
Es posible setear el tiempo máximo disponible para que el cliente complete el pago en el formulario, el valor por defecto es de 30 minutos. El rango posible es de 5 minutos a 6 horas. Los valores deben ser expresados en milisegundos
Confirmación de transacción
- En este caso hay que llamar a getAuthorizeAnswer(), enviando como parámetro un objeto como se describe a continuación.
var parameters = {
'Security' : 'f3d8b72c94ab4a06be2ef7c95490f7d3',
'Merchant' : '2153',
'RequestKey' : '710268a7-7688-c8bf-68c9-430107e6b9da',
'AnswerKey' : '693ca9cc-c940-06a4-8d96-1ab0d66f3ee6'
};
sdk.getAutorizeAnswer(options, parameters, function(result, err){
console.log("getAutorizeAnswer");
console.log(result);
console.log(err);
console.log("-------------------");
});
result :
{ StatusCode = -1,
StatusMessage = APROBADA,
AuthorizationKey = 1294-329E-F2FD-1AD8-3614-1218-2693-1378,
EncodingMethod = XML,
Payload = { Answer = { DATETIME = 2014/08/11 15:24:38,
RESULTCODE = -1,
RESULTMESSAGE = APROBADA,
CURRENCYNAME = Pesos,
PAYMENTMETHODNAME = VISA,
TICKETNUMBER = 12,
CARDNUMBERVISIBLE = 450799******4905,
AUTHORIZATIONCODE = TEST38,
INSTALLMENTPAYMENTS = 6,
TEA = 22.00,
CFT = 0.00
},
{ Request = { MERCHANT = 12345678,
OPERATIONID = ABCDEF-1234-12221-FDE1-00000012,
AMOUNT = 1.00,
CURRENCYCODE = 032,
AMOUNTBUYER = 1.20}
}
}
Tiempo de vida de la transacción
Es posible setear el tiempo máximo disponible para que el cliente complete el pago en el formulario, el valor por defecto es de 30 minutos. El rango posible es de 5 minutos a 6 horas. Los valores deben ser expresados en milisegundos
Ejemplo
.............................................
var parameters = { TIMEOUT = 10*60*1000 }
.............................................El campo o elemento Payload es utilizado para retornar los datos de la respuesta de la transacción. En la siguiente Tabla se muestran los valores enviados en el campo Answer de dicho elemento. (El otro campo presente, de nombre Request contiene información enviada en el requerimiento del GetAuthorizeAnswer)
Datos de referencia
Este método devuelve el resumen de los datos de la transacción.
Aclaración: El campo AMOUNTBUYER es el monto efectivamente pagado por el comprador, que incluye el costo financiero total.
Ejemplo
- Existe un ejemplo en la carpeta https://github.com/TodoPago/SDK-Node.js/tree/master/ejemplo que muestra los resultados de los métodos principales del SDK.
- Para ejecutar este ejemplo correr la linea de comando npm install y luego ejecutar node ejemplo.js
Características
Status de la operación
- El SDK cuenta con un método para consultar el status de la transacción desde la misma SDK. El método se utiliza de la siguiente manera:
sdk.getStatus(options, merchant, operationId, callback);// Merchant es el id site y operationId es el id operación que se envió en el objeto a través del método sendAuthorizeRequest()- Dicho método retornara el status actual de la transacción en Todopago.
Consulta de operaciones por rango de tiempo
En este caso hay que llamar a getByRangeDateTime() y devolvera todas las operaciones realizadas en el rango de fechas dado
var parameters = {
'MERCHANT': '2153',
'STARTDATE': '2015-01-01T17:34:42.903',
'ENDDATE': '2015-12-10T17:34:42.903'
};
sdk.getByRangeDateTime(options, parameters, function(result, err){
console.log("-------------------***-------------------");
console.log("GetByRangeDateTime");
console.log(result);
console.log(err);
console.log("-------------------***-------------------");
});
Devoluciones
El SDK dispone de métodos para realizar la devolución online, total o parcial, de una transacción realizada a traves de TodoPago.
- Devolución Total
- Se debe llamar al método
voidRequestde la siguiente manera:
Campo | Requerido | Descripción | Tipo de Dato | Valores posibles / Ejemplo -----------------|------------|--------------------------------------------------------------------- |--------------|--------------------------- Security | Sí | API Key del comercio asignada por TodoPago | alfanumérico | 837BE68A892F06C17B944F344AEE8F5F Merchant | Sí | Nro de comercio asignado por TodoPago | numérico | 12345 RequestKey | No* | RequestKey devuelto como respuesta del servicio SendAutorizeRequest | alfanumérico | 6d2589f2-37e6-1334-7565-3dc19404480c AuthorizationKey | No* | AuthorizationKey devuelto como respuesta del servicio GetAuthorizeAnswer | alfanumérico | 4a2569a2-38e6-4589-1564-4480c3dc1940
*Es requerida la presencia de sólo uno de estos 2 campos
var parameters = {
'Security': '108fc2b7c8a640f2bdd3ed505817ffde',
'Merchant': '2669',
'RequestKey': '0d801e1c-e6b1-672c-b717-5ddbe5ab97d6',
'AMOUNT': 1.00
};
sdk.voidRequest(options, parameters, function(result, err){
console.log("-------------------***-------------------");
console.log("VoidRequest");
console.log(result);
console.log(err);
console.log("-------------------***-------------------");
});- También se puede llamar al método
voidRequestde esta otra manera:
var parameters = {
'Security': '108fc2b7c8a640f2bdd3ed505817ffde',
'Merchant': '2669',
'AuthorizationKey': '0d801e1c-e6b1-672c-b717-5ddbe5ab97d6',
'AMOUNT': 1.00
};
sdk.voidRequest(options, parameters, function(result, err){
console.log("-------------------***-------------------");
console.log("VoidRequest");
console.log(result);
console.log(err);
console.log("-------------------***-------------------");
});Devolución parcial
Se debe llamar al método returnRequest de la siguiente manera:
var parameters = {
'Security': '108fc2b7c8a640f2bdd3ed505817ffde',
'Merchant': '2669',
'RequestKey': '0d801e1c-e6b1-672c-b717-5ddbe5ab97d6',
'AMOUNT': 1.00
};
sdk.returnRequest(options, parameters, function(result, err){
console.log("-------------------***-------------------");
console.log("ReturnRequest");
console.log(result);
console.log(err);
console.log("-------------------***-------------------");
});También se puede llamar al método returnRequest de la esta otra manera:
var parameters = {
'Security': '108fc2b7c8a640f2bdd3ed505817ffde',
'Merchant': '2669',
'AuthorizationKey': '0d801e1c-e6b1-672c-b717-5ddbe5ab97d6',
'AMOUNT': 1.00
};
sdk.returnRequest(options, parameters, function(result, err){
console.log("-------------------***-------------------");
console.log("ReturnRequest");
console.log(result);
console.log(err);
console.log("-------------------***-------------------");
});- El monto de devolución se calcula en base al costo original del producto sin los impuestos agregados.
Formulario híbrido
Conceptos básicos El formulario híbrido, es una alternativa al medio de pago actual por redirección al formulario externo de TodoPago. Con el mismo, se busca que el comercio pueda adecuar el look and feel del formulario a su propio diseño.
Librería El formulario requiere incluir en la página una librería Javascript de TodoPago. El endpoint depende del entorno:
- Desarrollo: https://developers.todopago.com.ar/resources/v2/TPBSAForm.min.js
- Producción: https://forms.todopago.com.ar/resources/v2/TPBSAForm.min.js
Restricciones y libertades en la implementación
- Por ningún motivo podrá bajarse el javascript provisto ni realizar cambios en el mismo. Siempre deberá ser tomado de los servidores de TodoPago.
- Ninguno de los campos del formulario podrá contar con el atributo name.
- Se deberá proveer de manera obligatoria un botón para gestionar el pago con Billetera Todo Pago.
- Todos los elementos de tipo son completados por la API de Todo Pago.
- Los campos tienen un id por defecto. Si se prefiere utilizar otros ids se deberán especificar los mismos cuando se inicialice el script de Todo Pago.
- Pueden aplicarse todos los detalles visuales que se crean necesarios, la API de Todo Pago no altera los atributos class y style.
- Puede utilizarse la API para setear los atributos placeholder del formulario, para ello deberá especificar dichos placeholders en la inicialización del formulario "window.TPFORMAPI.hybridForm.setItem". En caso de que no se especifiquen los placeholders se usarán los valores por defecto de la API.
HTML del formulario
El formulario implementado debe contar al menos con los siguientes campos.
<body>
<select id="formaPagoCbx"></select>
<input id="numeroTarjetaTxt"/>
<label id="numeroTarjetaLbl"></label>
<select id="medioPagoCbx"></select>
<select id="bancoCbx"></select>
<select id="promosCbx"></select>
<label id="promosLbl"></label>
<label id="peiLbl"></label>
<input id="peiCbx"/>
<select id="mesCbx"></select>
<select id="anioCbx"></select>
<label id="fechaLbl"></label>
<input id="codigoSeguridadTxt"/>
<label id="codigoSeguridadLbl"></label>
<input id="nombreTxt"/>
<select id="tipoDocCbx"></select>
<input id="nroDocTxt"/>
<input id="emailTxt"/>
<label id="tokenPeiLbl"></label>
<input id="tokenPeiTxt"/>
<button id="MY_btnConfirmarPago"/>
<button id="MY_btnPagarConBilletera"/>
</body>Inizialización y parámetros requeridos Para inicializar el formulario se usa window.TPFORMAPI.hybridForm.initForm. El cual permite setear los elementos y ids requeridos.
Para inicializar un ítem de pago, es necesario llamar a window.TPFORMAPI.hybridForm.setItem. Este requiere obligatoriamente el parámetro publicKey que corresponde al PublicRequestKey (entregado por el SAR). Se sugiere agregar los parámetros usuario, e-mail, tipo de documento y numero.
Javascript
/************* CONFIGURACION DEL API ***********************/
window.TPFORMAPI.hybridForm.initForm({
callbackValidationErrorFunction: 'validationCollector',
callbackBilleteraFunction: 'billeteraPaymentResponse',
callbackCustomSuccessFunction: 'customPaymentSuccessResponse',
callbackCustomErrorFunction: 'customPaymentErrorResponse',
botonPagarId: 'MY_btnConfirmarPago',
botonPagarConBilleteraId: 'MY_btnPagarConBilletera',
modalCssClass: 'modal-class',
modalContentCssClass: 'modal-content',
beforeRequest: 'initLoading',
afterRequest: 'stopLoading'
});
/************* SETEO UN ITEM PARA COMPRAR ******************/
window.TPFORMAPI.hybridForm.setItem({
publicKey: 'taf08222e-7b32-63d4-d0a6-5cabedrb5782', //obligatorio
defaultNombreApellido: 'Usuario',
defaultNumeroDoc: 20234211,
defaultMail: '[email protected]',
defaultTipoDoc: 'DNI'
});
/************* FUNCIONES CALLBACKS *************************/
function validationCollector(parametros) {
console.log("My validation collector callback");
console.log(parametros.field + " -> " + parametros.error);
}
function billeteraPaymentResponse(response) {
console.log("My billetera payment callback");
console.log(response.ResultCode + " -> " +response.ResultMessage);
}
function customPaymentSuccessResponse(response) {
console.log("My custom payment success callback");
console.log(response.ResultCode + " -> " +response.ResultMessage);
}
function customPaymentErrorResponse(response) {
console.log("My custom payment error callback");
console.log(response.ResultCode + " -> " +response.ResultMessage);
}
function initLoading() {
console.log('Loading...');
}
function stopLoading() {
console.log('Stop loading...');
}
Callbacks El formulario define callbacks javascript, que son llamados según el estado y la información del pago realizado:
- billeteraPaymentResponse: Devuelve response si el pago con billetera se realizó correctamente.
- customPaymentSuccessResponse: Devuelve response si el pago se realizo correctamente.
- customPaymentErrorResponse: Si hubo algún error durante el proceso de pago, este devuelve el response con el código y mensaje correspondiente. Volver a inicio
Obtener Credenciales
- Los datos como Authorization , merchantId y ApiKey se pueden obtener mediante el método getCredentials del objeto User llamada desde el sdk.
- Se debe pasar por parámetro los datos de ingreso de todoPago (mail y password) en caso de no tener una cuenta podes registrarte en http://www.todopago.com.ar/registrate y generar tus credenciales en Soluciones para Vendedores -> Comercios:Integración
var email = '[email protected]';
var pass = 'Password01';
sdk.getCredentials(email, pass, options , function(result, err){
console.log("-------------------***-------------------");
console.log("getCredentials:");
console.log(result);
console.log('err: ');
console.log(err);
console.log("-------------------***-------------------");
});