Todo-pago-sdk NPM

Todo Pago - módulo SDK-NodeJS para conexión con gateway de pago

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.

Volver a inicio

Versiones de node soportadas

La versión implementada del SDK, esta testeada para versiones desde Node 0.10.x en adelante.

Volver a inicio

Generalidades

Esta versión soporta únicamente pago en moneda nacional argentina (CURRENCYCODE = 32).

Volver a inicio

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 test

Volver a inicio

Uso

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

imagen de configuracion

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': 'todopago@hotmail.com',
    'CSSTEMAIL': 'todopago@hotmail.com',

    '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':'some@someurl.com', //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':'some@someurl.com', //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.
	...........................................................

Volver a inicio

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

Volver a inicio

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

Ejemplo

.............................................
var parameters = { TIMEOUT = 10*60*1000 }
.............................................

Volver a inicio

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.

Volver a inicio

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.

estado

Volver a inicio

Consulta de operaciones por rango de tiempo

obtener operaciones por rango

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("-------------------***-------------------");
	});

Volver a inicio

Devoluciones

devolucion total

devolucion parcial

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 voidRequest de 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 voidRequest de 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("-------------------***-------------------");
	});

Volver a inicio

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.

Volver a inicio

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: 'todopago@mail.com',
    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

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 = 'micuentademail@gmail.com';
	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("-------------------***-------------------");
	});

Volver a inicio

Tablas de Referencia

Provincias

Volver a inicio

Tabla de errores operativos

sdk TodoPago web-services gateway

soap xml2js node-rest-client

@everything-registry/sub-chunk-2956 @infinitebrahmanuniverse/nolb-tod

1.5.0

6 years ago

1.4.0

6 years ago