SDK de Tokenización

El SDK de tokenización de Paylands, es una libreria Javascript que permite guardar las tarjetas de los clientes utilizando un formulario contenido en un iframe dentro del dominio de Paylands. De este modo los comercios que no puedan gestionar datos de tarjeta, pueden utilizar este formulario para solicitarlos a los usuarios sin que el propio comercio intervenga en la recopilación y almacenamiento de dichos datos. Este proceso devuelve al comercio la tarjeta tokenizada.

El SDK de Javascript se comunica con la web del cliente mediante eventos, de forma que cada método del SDK lanzará un evento al DOM que podrá ser recogido por el cliente para actuar en consecuencia.

Integración

Vamos a realizar la integración del SDK Javascript de Tokenización para cargar el formulario y enviar la tarjeta a Paylands.

1. Cargar la libreria SDK en tu web o app

La librería se puede obtener en el siguiente enlace:

https://api.paylands.com/js/v1-iframe.js

Puedes cargar la libreria copiando y pegando el siguiente script en tu web:

<script type="text/javascript" src="https://api.paylands.com/js/v1-iframe.js"></script>

Una vez cargada la librería existirá una nueva variable global paylands con la que podremos interactuar.

2. Crear el usuario cliente al cual se le asignará la tarjeta

Para mostrar el formulario es necesario crear primero el cliente al cual le asignaremos la tarjeta. Desde tu servidor debes hacer una petición a la API de Paylands para Crear el cliente.

curl --request POST 'https://api.paylands.com/v1/customer' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "121149a0ba5361191d740fa898784a8b",
  "customer_ext_id": "customer15487"
}'

Esta petición retorna el token del cliente que deberemos usar en el próximo paso.

{
  "message": "OK",
  "code": 200,
  "current_time": "2017-01-12T09:12:58+0100",
  "Customer": {
    "external_id": "customer15487",
    "token": "TOKEN"
  }
}

3. Mostrar el formulario

Con el token del usuario deberemos hacer una llamada al método paylands.initializate() cuando se lance el evento paylandsLoaded en el DOM. De no hacerlo así, la variable paylands podría no estar inicializada.

En nuestro DOM creamos un div donde queremos mostrar el formulario.

<div id="paylands-iframe"></div>

Con esta llamada Javascript cargaremos el formulario en el div paylands-iframe para el cliente del token obtenido en el paso anterior.

<script>
window.addEventListener('message', receiveMessage => {
    if (receiveMessage.data === 'paylandsLoaded') {
        //Escuchamos el mensaje paylandsLoaded para continuar
        console.log('PaylandsLoaded', paylands);
        //Si estamos haciendo pruebas debemos cambiar el modo a sandbox
        //En producción quitar esta linea
        paylands.setMode('sandbox');
        //Inicializamos el formulario
        paylands.initializate(
            'TOKEN',
            'paylands-iframe'
        )
    }
}, false);
</script>

El formulario aparecerá con el siguiente formato.

Puedes personalizar la apariencia del formulario en el Backend de Paylands → Personalización → Plantillas. Al pulsar el botón crear nueva, podrás seleccionar la plantilla de tipo Carta de tokenización donde te permitirá modificar completamente su apariencia. En el caso de haber configurado una plantilla personalizada deberemos aplicarla en nuestro código utilizando el método setTemplate.

paylands.setTemplate(
    'C082AA84-EC2D-4ED2-9312-D0992832E490' // UUID de la plantilla creada
)

note

La personalización mediante una plantilla de Carta de tokenización es completamente opcional. Si no se utiliza setTemplate, el formulario cargará la plantilla por defecto.

4. Guardar la tarjeta

Una vez el formulario esté cargado y el usuario haya introducido sus datos de tarjeta, haremos una petición a paylands.storeSourceCard() para almacenarla en Paylands.

Al ejecutar el método paylands.storeSourceCard(), en primer lugar se validan los datos introducidos y dependiendo de si hay algún error o no, se lanzará el evento error o validation respectivamente. Esta validación sólo valida el formato de los datos introducidos.

info

Si se necesita comprobar que la tarjeta tiene fondos, que no está bloqueada, etc, este método admite dos parámetros: el primero es un valor booleano a true para indicar que se necesita validar la tarjeta contra la entidad bancaria. El segundo parámetro es el service_uuid incluido junto a las credenciales de la API. La validación consiste en un cargo de 0€ en la tarjeta del usuario para comprobar que la tarjeta es válida.

Veamos como lo haríamos:

paylands.storeSourceCard(
    true, //queremos validar la tarjeta contra el banco
    '3BF33A39-897E-4FBB-98CA-D1C0C55CA898' //service_uuid
)

5. Informar al usuario del resultado

El paso anterior lanzará un evento mediante el cual se podrá informar al usuario si la operación se ha realizado correctamente o ha habido algún error.

• Si el evento es error, se indicarán los elementos erróneos del formulario.
• Si el evento es savedCard, significa que la tarjeta se ha tokenizado.

<script>
window.addEventListener('message', receiveMessage => {
    if (receiveMessage.data === 'error') {
        console.log('Error en la tarjeta');
    } else if (receiveMessage.data === 'savedCard') {
        console.log('Tarjeta guardada correctamente');
    }
}, false);
</script>

El evento savedCard contendrá los datos de la tarjeta tokenizada.

{
    "code": "200",
    "current_time": "2022-01-25T11:55:05+0200",
    "customer": {
        "external_id": "1239111NBC"
    },
    "source": {
        "object": "CARD",
        "uuid": "33SISMS-C254-4783-386C-603058EISAC25",
        "type": "C",
        "token": "elsellsSrfa2ercf119283BanScrIcana2f4be9acfMISUS188",
        "brand": "VISA",
        "country": 724,
        "holder": "UNKNOWN",
        "bin": 454881,
        "last4": "0004",
        "expire_month": "01",
        "expire_year": "22",
        "additional": null,
        "bank": "SERVIRED, SOCIEDAD ESPANOLA DE MEDIOS DE PAGO, S.A.",
        "prepaid": "",
        "validation_date": null
    }
}

6. Recibir los datos de la tarjeta en el servidor

Si existe la necesidad de recepcionar la notificación savedCard en el servidor, es posible hacerlo indicando la URL del servidor a la cual notificar mediante el método setURLPost.

paylands.setURLPost(
    'URL_NOTIFICACIÓN' // URL de tu servidor a la que notificará Paylands
)

La notificación enviada tendrá la misma estructura que recibe el evento savedCard:

{
    "code": "200",
    "current_time": "2022-01-25T11:55:05+0200",
    "customer": {
        "external_id": "1239111NBC"
    },
    "source": {
        "object": "CARD",
        "uuid": "33SISMS-C254-4783-386C-603058EISAC25",
        "type": "C",
        "token": "elsellsSrfa2ercf119283BanScrIcana2f4be9acfMISUS188",
        "brand": "VISA",
        "country": 724,
        "holder": "UNKNOWN",
        "bin": 454881,
        "last4": "0004",
        "expire_month": "01",
        "expire_year": "22",
        "additional": null,
        "bank": "SERVIRED, SOCIEDAD ESPANOLA DE MEDIOS DE PAGO, S.A.",
        "prepaid": "",
        "validation_date": null
    }
}

note

La recepción de la notificación en el servidor es completamente opcional. Si tu web/app no lo precisa, se puede obviar este paso.

Métodos

A continuación se detallan todos los métodos públicos que dispone la variable global paylands:

• setMode: utilizado cuando se están haciendo pruebas en sandbox. El valor que se debe pasar como parámetro es "sandbox". Si no se utiliza este método, se asume que las llamadas se hacen en producción.

• initializate: este es el método principal, el cual cargará el formulario de tarjeta. El primer parámetro debe ser el token obtenido al crear el usuario. El segundo parámetro es el elemento del DOM en el que se insertará el formulario.

• setTemplate: mediante este método se especifica la plantilla de formulario que se mostrará. Sólo recibe un parámetro, el UUID de la plantilla.

• validate: en cualquier momento puede ejecutarse este método para obtener el estado actual de los datos de la tarjeta. El evento lanzado es validation.

• setAdditional: mediante este método se asigna una descripción a la tarjeta.

• setURLPost: si se necesita que el guardado de la tarjeta envíe una notificación en background al servidor, se puede usar este método para especificar la URL a la que se enviarán los datos de la tarjeta tokenizada.

• storeSourceCard: este método se usa para almacenar la tarjeta en Paylands. En primer lugar se validan los datos introducidos y dependiendo de si hay algún error o no, se lanzará el evento error o validation respectivamente. Esta validación sólo valida el formato de los datos introducidos. Si se necesita comprobar que la tarjeta tiene fondos, que no está bloqueada, etc, este método admite dos parámetros: el primero es un valor booleano a true para indicar que se necesita validar la tarjeta contra la entidad bancaria. El segundo parámetro es el service_uuid incluido junto a las credenciales de la API. La validación consiste en un cargo de 0€ en la tarjeta del usuario para comprobar que la tarjeta es válida.

• setFocus: mediante este método se puede establecer el cursor en el input que se necesite:

  • Si no se especifica ningún parámetro, el foco se establecerá en el primer INPUT vacío
  • Si se especifica el ID de algún INPUT, el foco se establecerá sobre este.

Eventos

A continuación se detallan los eventos que el SDK lanza para ser tratados por la web/app del cliente:

• paylandsLoaded: este evento se lanza cuando el SDK ha sido cargado y la variable paylands está disponible para su uso.

• initiated: Este evento es lanzado cuando se ha cargado el formulario de tarjeta.

• validation: Este evento se lanza cuando se ejecuta el método validate.

  • Si se valida con todos los campos vacíos:

    

  • Si todos los campos son correctos:

    

• error: Este evento contendrá qué campos tienen datos incorrectos.

  

• savedCard: Este evento devuelve la tarjeta tokenizada.