Payway SDK Javascript

Modulo para conexión con gateway de pago Payway

Introducción
- Alcance
- Diagrama de secuencia
Instalación
- Ambientes
Uso
- Inicializar la clase correspondiente al conector
- Operatoria del Gateway
- Generación de Token de Pago
- Integración con Cybersource
  - Device fingerprinter
- Tablas de referencia
- Mensajes de Error
- Advertencias
  Introducción
  
  El flujo de una transacción a través de las sdks consta de dos pasos, la generación de un token de pago por parte del cliente y el procesamiento de pago por parte del comercio. Existen sdks específicas para realizar estas funciones en distintos lenguajes que se detallan a continuación:
Generación de un token de pago. Se utiliza alguna de las siguentes sdks front-end :
- sdk Javascript
Procesamiento de pago. Se utiliza alguna de las siguentes sdks back-end :
- sdk Java
- sdk PHP
- sdk .Net
- sdk Node

Alcance

La sdk Javascript provee soporte para su aplicación front-end, encargandose de la generación de un token de pago por parte de un cliente. Este token debe ser enviado al comercio al realizar el pago. Esta sdk permite la comunicación del cliente con la API Payway utilizando su API Key pública¹.

Para procesar el pago con Payway, el comercio podr´ realizarlo a través de alguna de las siguentes sdks front-backend:

imagen de sdks

^{_1 - Las API Keys serán provistas por el equipo de Soporte de Payway (soporte@payway.com.ar)}

Atención! La sdk Javascript cumple con el estándar ECMA Script 6 por lo que no será compatible en versiones muy antiguas de Browsers. Podrá encontrar la información necesaria en el siguiente sitio: Tabla de Browsers soportados

_{Volver a inicio}

Diagrama de secuencia

El flujo de una transacción a través de las sdks consta de dos pasos, a saber:

sdk front-end: Se realiza una solicitud de token de pago con la Llave de Acceso pública (public API Key), enviando los datos sensibles de la tarjeta (PAN, mes y año de expiración, código de seguridad, titular, y tipo y número de documento) y obteniéndose como resultado un token que permitirá realizar la transacción posterior.
sdk back-end: Se ejecuta el pago con la Llave de Acceso privada (private API Key), enviando el token generado en el Paso 1 más el identificador de la transacción a nivel comercio, el monto total, la moneda y la cantidad de cuotas.

A continuación, se presenta un diagrama con el Flujo de un Pago.

imagen de configuracion

_{Volver a inicio}

Instalación

Se debe agregar en el HTML el siguiente tag.

<script src="https://live.decidir.com/static/v2.6.4/decidir.js"></script>

Compatibilidad

Si quiere disponibilizar su producto en componentes web embebidos WebView de Android inferiores a v33.0.0.0, deberá incluir previo a la SDK, la siguiente librería que incluye objetos de compatibilidad que WebView reconoce:

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/6.26.0/polyfill.min.js"></script>

Solamente se recomienda incluir ésta librería en casos excepcionales ya que agrega compatibilidad a versiones muy antiguas e influye en el tamaño de su aplicación

_{Volver a inicio}

Ambientes

El sdk Javascript permite trabajar con los ambientes Sandbox y Produccón de Payway. El ambiente se debe instanciar indicando su URL.

// ...codigo...
const urlSandbox = "https://developers.decidir.com/api/v2";
const urlProduccion = "https://live.decidir.com/api/v2";
//Para el ambiente de desarrollo
const decidirSandbox = new Decidir(urlSandbox);
decidirSandbox.setTimeout(0);//se configura sin timeout
//Para el ambiente de produccion
const decidirProduccion = new Decidir(urlProduccion);
decidirProduccion.setTimeout(3000);//se configura el timeout en milisegundos
// ...codigo...

_{Volver a inicio}

Uso

Inicializar la clase correspondiente al conector.

Instanciación de la clase Decidir

La misma recibe como parámetros la public key provista por Payway para el comercio y el ambiente en que se trabajará.

La API Key será provista por el equipo de Soporte de Payway (soporte@payway.com.ar).

A partir de ahora y por el resto de la documentación, se ejemplificará utilizando una APIKey habilitada para operar en el ambiente Sandbox.

const publicApiKey = "e9cdb99fff374b5f91da4480c8dca741";
const urlSandbox = "https://developers.decidir.com/api/v2";
//Para el ambiente de desarrollo
const decidir = new Decidir(urlSandbox);
//Se indica la public API Key
decidir.setPublishableKey(publicApiKey);
decidir.setTimeout(5000);//timeout de 5 segundos
// ...codigo...

_{Volver a inicio}

Operatoria del Gateway

Generación de Token de Pago

La sdk javascript permite generar, desde el navegador, un token de pago con los datos de la tarjeta del cliente. Éste se deberá enviar luego al backend del comercio para realizar la transacción de pago correpondiente.

El token de pago puede ser generado de 2 formas como se muestra a continuación.

_{Volver a inicio}

Con datos de tarjeta

Mediante este recurso, se genera un token de pago a partir de los datos de la tarjeta del cliente. Debe enviarse un formulario web, con los campos marcados con el atributo data-decidir indicando el parametro al que corresponde.

Campo	Descripcion	Oblig	Restricciones	Ejemplo
card_number	numero de tc	SI	Mayor o igual a 15 numeros	"4507990000004905"
card_expiration_month	mes de vto de tc	SI	No debe ser anterior a la fecha (mes/año) del dia actual	07
card_expiration_year	año de vto de tc	SI	No debe ser anterior a la fecha (mes/año) del dia actual	17
card_holder_birthday	año de nac del titutal	NO	El formato a respetar es ddMMYYYY	01091994
card_holder_door_number	nro puerta del titular	NO	Debe ser numerico	1502
security_code	codigo de seguridad	NO	Sin validacion	234
card_holder_name	titular (como figura en la tc)	SI	Mayor igual a 1 letra	Valentin Santiago Gomez
type	tipo de documento	NO	Sin validacion	dni/DNI, cuil/CUIL
number	nro de documento	NO	Sin validacion	23968498
device_unique_identifier	identificador único del dispositivo	NO	Sin validacion	12345

<form action="" method="post" id="formulario" >
  <fieldset>
        <ul>
      <li>
        <label for="card_number">Numero de tarjeta:</label>
        <input type="text" data-decidir="card_number" placeholder="XXXXXXXXXXXXXXXX" value="4507990000004905"/>
      </li>
      <li>
        <label for="security_code">Codigo de seguridad:</label>
      <input type="text"  data-decidir="security_code" placeholder="XXX" value="123" />
      </li>
      <li>
        <label for="card_expiration_month">Mes de vencimiento:</label>
        <input type="text"  data-decidir="card_expiration_month" placeholder="MM" value="12"/>
      </li>
      <li>
        <label for="card_expiration_year">Año de vencimiento:</label>
        <input type="text"  data-decidir="card_expiration_year" placeholder="AA" value="20"/>
      </li>
      <li>
        <label for="card_holder_name">Nombre del titular:</label>
        <input type="text" data-decidir="card_holder_name" placeholder="TITULAR" value="TITULAR"/>
      </li>
      <li>
        <label for="card_holder_doc_type">Tipo de documento:</label>
        <select data-decidir="card_holder_doc_type">
                    <option value="dni">DNI</option>
                </select>
      </li>
      <li>
        <label for="card_holder_doc_type">Numero de documento:</label>
        <input type="text"data-decidir="card_holder_doc_number" placeholder="XXXXXXXXXX" value="27859328"/>
      </li>
<!-  Adicional se pueden agregar los datos de fecha de nacimiento y nro de puerta relacionados al titular de la tarjeta ->
      <li>
        <label for="card_holder_birthday">Card holder birthday:</label>
        <input type="text" id="card_holder_birthday" data-decidir="card_holder_birthday" placeholder="ddMMYYYY" value="04091994"/>
       </li>
       <li>
        <label for="card_holder_door_number">Card holder door number:</label>
        <input type="text" id="card_holder_door_number" data-decidir="card_holder_door_number" placeholder="NUM" value="1"/>
       </li>
    </ul>
    <input type="submit" value="Generar Token" />
  </fieldset>
</form>

Y la invocación en Javascript

const publicApiKey = "e9cdb99fff374b5f91da4480c8dca741";
const urlSandbox = "https://developers.decidir.com/api/v2";
//Para el ambiente de desarrollo
const decidir = new Decidir(urlSandbox);
//Se indica la public API Key
decidir.setPublishableKey(publicApiKey);
decidir.setTimeout(5000);//timeout de 5 segundos
//formulario
var form = document.querySelector('#formulario');
//Asigna la funcion de invocacion al evento de submit del formulario
addEvent(form,'submit',sendForm));
//funcion para manejar la respuesta
function sdkResponseHandler(status, response) {
    if (status != 200 && status != 201) {
    //Manejo de error: Ver Respuesta de Error
    //...codigo...
  } else {
    //Manejo de respuesta donde response = {token: "99ab0740-4ef9-4b38-bdf9-c4c963459b22"}
    //..codigo...
  }
}
//funcion de invocacion con sdk
function sendForm(event) {
  event.preventDefault();
  decidir.createToken(form, sdkResponseHandler);//formulario y callback
  return false;
}
//..codigo...

_{Volver a inicio}

Con tarjeta tokenizada

<form action="" method="post" id="formulario" >
    <fieldset>
        <ul>
            <li>
                <label for="token">Tarjeta tokenizada:</label>
                <input type="text"  data-decidir="token" placeholder="xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx" value="70b03ded-9116-45be-91ca-27a6969ad6ac"/>
            </li>
            <li>
                <label for="security_code">Codigo de seguridad:</label>
                <input type="text"  data-decidir="security_code" placeholder="XXX" value="123" />
            </li>
        </ul>
      <input type="submit" value="Generar Token" />
    </fieldset>
</form>

Y la invocación en Javascript

const publicApiKey = "e9cdb99fff374b5f91da4480c8dca741";
const urlSandbox = "https://developers.decidir.com/api/v2";
//Para el ambiente de desarrollo
const decidir = new Decidir(urlSandbox);
//Se indica la public API Key
decidir.setPublishableKey(publicApiKey);
decidir.setTimeout(5000);//timeout de 5 segundos
//formulario
var form = document.querySelector('#formulario');
//Asigna la funcion de invocacion al evento de submit del formulario
addEvent(form,'submit',sendForm));
//funcion para manejar la respuesta
function sdkResponseHandler(status, response) {
    if (status != 200 && status != 201) {
    //Manejo de error: Ver Respuesta de Error
    //...codigo...
  } else {
    //Manejo de respuesta donde response = {token: "99ab0740-4ef9-4b38-bdf9-c4c963459b22"}
    //..codigo...
  }
}
//funcion de invocacion con sdk
function sendForm(event){
  event.preventDefault();
  decidir.createToken(form, sdkResponseHandler);//formulario y callback
  return false;
};
//..codigo...

_{Volver a inicio}

Pago offline

Mediante este recurso, se genera un token de pago offline a partir de los datos del cliente. Debe enviarse un formulario web, con los campos marcados con el atributo data-decidir indicando el parámetro al que corresponde.

<form action="" method="post" id="formulario" >
  <fieldset>
        <ul>
      <li>
        <label for="customer_name">Nombre del cliente:</label>
        <input type="text" data-decidir="customer_name" placeholder="TITULAR" value="TITULAR"/>
      </li>
      <li>
        <label for="customer_doc_type">Tipo de documento:</label>
        <select data-decidir="customer_doc_type">
                    <option value="dni">DNI</option>
                </select>
      </li>
      <li>
        <label for="customer_doc_number">Numero de documento:</label>
        <input type="text" data-decidir="customer_doc_number" placeholder="XXXXXXXXXX" value="27859328"/>
      </li>
    </ul>
    <input type="submit" value="Generar Token" />
  </fieldset>
</form>

Y la invocación en Javascript

const publicApiKey = "e9cdb99fff374b5f91da4480c8dca741";
const urlSandbox = "https://developers.decidir.com/api/v2";
//Para el ambiente de desarrollo
const decidir = new Decidir(urlSandbox);
//Se indica la public API Key
decidir.setPublishableKey(publicApiKey);
decidir.setTimeout(5000);//timeout de 5 segundos
//formulario
var form = document.querySelector('#formulario');
//Asigna la funcion de invocacion al evento de submit del formulario
addEvent(form,'submit',sendForm));
//funcion para manejar la respuesta
function sdkResponseHandler(status, response) {
    if (status != 200 && status != 201) {
    //Manejo de error: Ver Respuesta de Error
    //...codigo...
  } else {
    //Manejo de respuesta donde response = {token: "99ab0740-4ef9-4b38-bdf9-c4c963459b22"}
    //..codigo...
  }
}
//funcion de invocacion con sdk
function sendForm(event) {
  event.preventDefault();
  decidir.createToken(form, sdkResponseHandler);//formulario y callback
  return false;
}
//..codigo...

_{Volver a inicio}

Integración con Cybersource

Por default, la sdk javascript utiliza el Servicio de Control de Fraude Cybersource. Para inhabilitar esta funcionalidad, debe indicarse en un parámetro al momento de instanciar el objeto Decidir. Para realizar esto, debe invocarse al contrucutor con dos argumentos, el primero es la url el cual puede enviarse nulo para tomar la url por defecto, y el segundo que indica si se inhabilita Cybersource

const publicApiKey = "e9cdb99fff374b5f91da4480c8dca741";
const urlSandbox = "https://developers.decidir.com/api/v2";
const inhabilitarCS = true;
//Para el ambiente de desarrollo
const decidir = new Decidir(urlSandbox, inhabilitarCS);
//Se indica la public API Key
decidir.setPublishableKey(publicApiKey);
decidir.setTimeout(5000);//timeout de 5 segundos
// ...codigo...
}

_{Volver a inicio}

Device FingerPrint

El Device Fingerprint (DF) es la huella digital del dispositivo que realiza la transacción. Es un dato muy importante que se tiene en cuenta en el proceso de validación Para acceder a la documentación: https://decidir.api-docs.io/1.0/prevencion-de-fraude-by-cybersource/cs_device_fingerprint

_{Volver a inicio}

Tablas de Referencia

Respuesta de Error

{
    "error": [{
        "isValid": false,
        "error": {
            "type": "invalid_expiry_date",
            "message": "Expiry date is invalid",
            "param": "expiry_date"
        },
        "param": "expiry_date"
    },
    {
        "isValid": false,
        "error": {
            "type": "empty_card_holder_name",
            "message": "Card Holder Name is empty",
            "param": "card_holder_name"
        },
        "param": "card_holder_name"
    }]
}

Códigos de Error

Estos códigos de Errores son los status en las Excepciones.

Tipo	Mensaje	Parámetro
empty_card_number	Card Number is empty	card_holder_name
empty_card_holder_name	Card Holder Name is empty	card_number
nan_card_number	Card Number must be a number	card_number
invalid_card_number	Invalid Card Number	expiry_date
invalid_expiry_date	Expiry date is invalid	expiry_date
invalid_expiry_date	Expiry date is invalid	token
empty_token	Token is empty	token
invalid_param	Invalid param	any param

Advertencias

El uso de CardType no está disponible actualmente. Estamos trabajando para entregar ésta funcionalidad actualizada y mejorada.

_{Volver a inicio}

payway-ar / sdk-javascript-ventaonline

readme

Payway SDK Javascript

Introducción

Alcance

Diagrama de secuencia

Instalación

Compatibilidad

Ambientes

Uso

Inicializar la clase correspondiente al conector.

Operatoria del Gateway

Generación de Token de Pago

Con datos de tarjeta

Con tarjeta tokenizada

Pago offline

Integración con Cybersource

Device FingerPrint

Tablas de Referencia

Respuesta de Error

Códigos de Error

Advertencias