Openpay.js

Introducción

¿Qué es Openpay.js?

Openpay.js es una librería Javascript diseñada para facilitar la creación de tokens en base a datos de tarjetas de crédito y débito desde una página web sin la necesidad que la información del alta pase por el servidor origen (El servidor del comercio).

Ventajas:

  • Es seguro, la información de la tarjeta no tiene que pasar por el servidor origen, sino que es enviada directamente a Openpay.
  • Es la manera más rápida y sencilla para integrar nuestro módulo de cobros en tu página web.

Primeros pasos

El primer paso para la integración consiste en agregar la librería Openpay.js a tu página como se ve a continuación:

<script type="text/javascript" src="https://js.openpay.mx/openpay.v1.min.js"></script>

Configuración

Para poder utilizar Openpay.js es necesario que se configuren tanto el ID de comercio, como la llave pública que te fueron asignados cuando creaste tu cuenta en el dashboard del ambiente de sandbox. Con estos datos, Openpay podrá identificar tus operaciones y podrá asignar tus tarjetas y cobros.

La configuración de ambos datos se hace con los métodos OpenPay.setId() y OpenPay.setApiKey(), respectivamente:

OpenPay.setId('MERCHANT_ID');
OpenPay.setApiKey('PUBLIC_API_KEY');

Nota: Tanto el MERCHANT-ID como el PUBLIC_API_KEY, los puedes consultar en el dashboard al entrar en tu cuenta de openpay, en la página de inicio o en la página de tu perfil.

Recuerda: Nunca debes utilizar tu llave privada con está librería, debido a que la llave es visible del lado del cliente.

Habilitar modo sandbox

Para que pruebes tu implementación, existe el ambiente de sandbox, el cual se habilita con el método: OpenPay.setSandboxMode().

OpenPay.setSandboxMode(FLAG);

El parámetro FLAG es una bandera true/false para activar o desactivar el modo de pruebas.

Si es necesario, se puede utilizar el método OpenPay.getSandboxMode() para determinar el estatus del modo sandbox en cualquier momento:

OpenPay.getSandboxMode(); // TRUE/FALSE, dependiendo si el modo está activado o no.

Nota: El ambiente de sandbox tiene las mismas funcionalidades que producción, pero solo permite el uso de ciertos números de tarjeta, elegidos con el fines de probar, mas información en la sección de pruebas.

Creación tokens sin formulario

Una vez que instalaste y configuraste la librería, para crear un token es necesario llamar al método OpenPay.token.create()

OpenPay.token.create(CREATE_PARAMETERS_OBJECT, SUCCESS_CALLBACK, ERROR_CALLBACK);

Los parámetros que recibe el método son:

  • El parámetro CREATE_PARAMETERS_OBJECT es un objeto Javascript que contiene la información de la tarjeta.
  • El parámetro SUCCESS_CALLBACK define la función que se llamará en caso de que la operación haya sido exitosa.
  • El parámetro ERROR_CALLBACK define la función que se llamará en caso de que la operación haya fallado.

Ejemplo de creación de token:

OpenPay.token.create({
      "card_number":"4111111111111111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "cvv2":"110",
      "address":{
         "city":"Querétaro",
         "line3":"Queretaro",
         "postal_code":"76900",
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "state":"Queretaro",
         "country_code":"MX"
      }
}, onSuccess, onError);

El método regresa un objeto tipo token del cual necesitaras posteriormente el id del token. La definición del objeto token la encontrarás aquí.

Creación de tokens con formulario

La librería Openpay.js te facilita la extracción de la información de la tarjeta desde formulario para su posterior envió por medio del método OpenPay.token.extractFormAndCreate()

OpenPay.token.extractFormAndCreate(CREATE_FORM_OBJECT, SUCCESS_CALLBACK, ERROR_CALLBACK);

Los parámetros que recibe el método son:

  • El parámetro CREATE_FORM_OBJECT es un objeto tipo form que contiene la información de la tarjeta.
  • El parámetro SUCCESS_CALLBACK define la función que se llamará en caso de que la operación haya sido correcta.
  • El parámetro ERROR_CALLBACK define la función que se llamará en caso de que la operación haya fallado.

Para empezar a crear tokens, es necesario tener un formulario como este:

<form id="processCard" name="processCard">
    <p>Holder Name:</p><input data-openpay-card="holder_name" size="50" type="text">
    <p>Card number:</p><input data-openpay-card="card_number" size="50" type="text">
    <p>Expiration year:</p><input data-openpay-card="expiration_year" size="4" type="text">
    <p>Expiration month:</p><input data-openpay-card="expiration_month" size="4" type="text">
    <p>cvv2:</p><input data-openpay-card="cvv2" size="5" type="text">
    <p>Street:</p><input data-openpay-card-address="line1" size="20" type="text">
    <p>Number:</p><input data-openpay-card-address="line2" size="20" type="text">
    <p>References:</p><input data-openpay-card-address="line3" size="20" type="text">
    <p>Postal code:</p><input data-openpay-card-address="postal_code" size="6" type="text">
    <p>City:</p><input data-openpay-card-address="city" size="20" type="text">
    <p>State:</p><input data-openpay-card-address="state" size="20" type="text">
    <p>Country code:</p><input data-openpay-card-address="country_code" size="3" type="text">
    <input id="makeRequestCard" type="button" value="Make Card">
</form>

Nota: Lo mas importante es agregar los atributos data-openpay-card y data-openpay-card-address en los inputs donde se captura la información de la tarjeta y la dirección respectivamente, ya que así el método sabe que valores tomar.

Posteriormente al momento de generar el token, hacer una invocacion al metodo token.extractFormAndCreate(), como se muestra a continuación

OpenPay.token.extractFormAndCreate(
      $('#processCard'),
      successCard,
      errorCard,
      _customerId);

​El método regresa un objeto tipo token del cual necesitaras posteriormente el id del token. La definición del objeto token la encontrarás aquí.

Para ver un ejemplo descarga la página de ejemplo desde el sitio de github: openpay-js

Manejo de respuestas

Las funciones de respuesta son para manejar el resultado de las operaciones. Son funciones simples de Javascript pero que reciben como argumento un objeto tipo respuesta.

Los campos del objeto de respuesta se describen a continuación

Campo

Formato

Descripción

status

Integer

Describe el status HTTP de la operación. En caso de que se produzca un error antes de enviar la petición, el status será igual a cero. En caso de éxito es 200.

message

String

Solo se presenta en casos de error. Descripción corta del error que ha ocurrido. Puede ser uno de los siguientes valores: "Unknown error", "Request error", "Response error (Unknown final status)", "Empty or invalid OpenPay ID", "Empty or invalid API Key", "Browser error", "Timeout after X milliseconds".

data

Objeto

Contiene un Objeto Error con la información del error en la transacción proporcionada por el servidor de Openpay.

En caso de éxito contiene un objeto tipo token.

Notas: Aunque las funciones de respuesta son opcionales, recomendamos que se implementen para que el resultado de la transacción pueda ser monitoreado en la página web.

En caso de éxito: SuccessCallback

Esta función es llamada cuando la operación fue exitosa de principio a fin. Recibe un solo parámetro que es un objeto Javascript con los datos del token.

Ejemplo completo de implementación de una función SuccessCallback:

function SuccessCallback(response) {
    alert('Operación exitosa');
    var content = '', results = document.getElementById('resultDetail');
    content .= 'Id tarjeta: ' + response.data.id+ '
';
    content .= 'A nombre de: ' + response.data.holder_name + '
';
    content .= 'Marca de tarjeta usada: ' + response.data.brand + '
';
    results.innerHTML = content;
}

En caso de error: ErrorCallback

Esta función se ejecutará cada vez que una operación haya fallado (por cualquier circunstancia, antes o después de enviar la petición). Al igual que el SuccessCallback(), recibe un solo parámetro que es un objeto Javascript con el detalle del fallo.

Ejemplo completo de implementación de una función ErrorCallback:

function ErrorCallback(response) {
    alert('Fallo en la transacción');
    var content = '', results = document.getElementById('resultDetail');
    content .= 'Estatus del error: ' + response.data.status + '
';
    content .= 'Error: ' + response.message + '
';
    content .= 'Descripción: ' + response.data.description + '
';
    content .= 'ID de la petición: ' + response.data.request_id + '
';
    results.innerHTML = content;
}

Tipos de error

Además del campo status que guarda el estado de la transacción, es posible determinar el error que haya sucedido por medio del campo message. El mensaje puede ser uno de los siguientes:

  • Empty or invalid OpenPay ID: Sucede cuando no se ha configurado correctamente el ID de usuario con el método OpenPay.setId()
  • Empty or invalid API Key: Al igual que el error anterior, sucede cuando no se ha configurado el API Key con el método OpenPay.setApiKey()
  • Browser error: Es disparado cuando hay un error en el navegador que impide que la petición se realice correctamente. Puede provocarse por características que son necesarias para ejecutar cierto código y que están faltantes en el navegador. Para mayor información consulta la sección “Compatibilidad y requerimientos”.
  • Request error: Este error indica que hubo un error en el servidor de Openpay. Puede deberse a parámetros faltantes, formatos o algún otro problema que impide realizar correctamente la transacción.
  • Response error (Unknown final status): Cuando se genera este error, quiere decir que la petición de transacción fue enviada correctamente al servidor de Openpay pero no se recibió ninguna respuesta. Es posible que esto se deba a un problema en Openpay. Para mayor información contacta a OpenPay.
  • Timeout after X milliseconds: Se lanza cuando la petición ha tardado mucho tiempo en ejecutarse y, por tanto, expira el tiempo de respuesta.
  • Unknown error: Se genera cuando existe algún error desconocido que impide que la petición se realice. Puede ser por problemas en el navegador o de conectividad.

Funciones de validación

Además de las funciones para procesar cargos por tarjeta, Openpay.js también incluye algunas funciones para validad los principales datos que son necesarios para llevar a cabo la transacción, sobre todo los referentes a los números de tarjeta.

Los métodos disponibles son:

  • OpenPay.card.validateCardNumber()
  • OpenPay.card.validateCVC()
  • OpenPay.card.validateExpiry()
  • OpenPay.card.cardType()

Validación de número de tarjeta

Para realizar la validación de un número de tarjeta es posible utilizar el método OpenPay.card.validateCardNumber().

Este método recibe como parámetro un String con el número de tarjeta que se validará y regresará un true/false en caso de que se trate de un número de tarjeta válido y sea aceptado por Openpay. Ejemplo:

OpenPay.card.validateCardNumber('5555555555554444');

Este método es muy útil para determinar si un número de tarjeta es válido y si es candidato para utilizarse con Openpay, por eso recomendamos que se use sistemáticamente antes de intentar un cobro con tarjeta.

Ejemplos:

OpenPay.card.validateCardNumber('5555555555554444');
// TRUE. Número de tarjeta válido y aceptado por OpenPay (MASTERCARD)
OpenPay.card.validateCardNumber('378282246310005');
// FALSE. Número de tarjeta válido pero no aceptado por OpenPay (AMEX) 

Validación de Código de Seguridad

Para validar un código de seguridad se utiliza el método OpenPay.card.validateCVC().

Este método recibe como parámetro un String y devuelve true/false en caso de que la cadena sea válida.

Ejemplos:

OpenPay.card.validateCVC('123'); // válido
OpenPay.card.validateCVC('1234'); // válido
OpenPay.card.validateCVC('A23'); // inválido

Adiconalmente, el código de seguridad se puede validar pasando como segundo parámetro el número de la tarjeta, para determinar si el código es válido para el tipo de tarjeta en cuestión.

Ejemplos:

OpenPay.card.validateCVC('123','5555555555554444');
// válido, tarjeta MASTERCARD y CVC de longitud 3
OpenPay.card.validateCVC('1234','5555555555554444');
// inválido, tarjeta MASTERCARD y CVC de longitud 4
OpenPay.card.validateCVC('123','378282246310005');
// inválido, tarjeta AMERICAN EXPRESS y CVC de longitud 3
OpenPay.card.validateCVC('1234','378282246310005');
// válido, tarjeta AMERICAN EXPRESS y CVC de longitud 4

Validación de fecha de expiración

Para este propósito se utiliza el método OpenPay.card.validateExpiry().

Recibe como parámetros dos Strings que representan el mes y año de expiración de la tarjeta. Devuelve true/false cuando la combinación de ambos datos, mes y año, determinan una fecha de expiración válida. Ejemplo:

OpenPay.card.validateExpiry('01', '2013'); // inválido
OpenPay.card.validateExpiry('05', '2015'); // válido

Validación del tipo de tarjeta

Es posible determinar (en la mayoría de las veces) el tipo de tarjeta al que pertenece un número de tarjeta. Para eso, se utiliza el método OpenPay.card.cardType().

El método recibe como parámetro un número de tarjeta y devuelve un String con el nombre del tipo de tarjeta.

Ejemplos:

OpenPay.card.cardType('5555555555554444'); // Mastercard
OpenPay.card.cardType('4111111111111111'); //​ Visa
OpenPay.card.cardType('4917300800000000'); // Visa Electron
OpenPay.card.cardType('378282246310005'); // American Express
OpenPay.card.cardType('30569309025904'); // Diners Club Carte Blanche
OpenPay.card.cardType('6011111111111117'); // Discover
OpenPay.card.cardType('3530111333300000'); // JCB

Compatibilidad y requerimientos

Para utilizar Openpay.js es necesario contar con uno de los siguientes navegadores:

  • Chrome 29.0+
  • Firefox 23.0+
  • Safari 5.1+
  • Opera 17.0+
  • iOS Safari 4.0+
  • Android Browser 2.1+
  • Blackberry Browser 7.0+
  • IE Mobile 10.0

Los navegadores deben de contar con soporte para las librerías XMLHttpRequest y JSON Parser.