PinPad SDK

El SDK de PinPad está diseñado para simplificar la integración de dispositivos de entrada segura de PIN en tu aplicación.

Introducción

Un PIN pad, o dispositivo de entrada de PIN (PED), es un dispositivo electrónico utilizado en transacciones con tarjetas de débito, crédito o tarjetas inteligentes para aceptar y encriptar el número de identificación personal (PIN) del titular de la tarjeta. Este SDK proporciona una manera sencilla de crear y gestionar estos componentes en el frontend con solo una instancia de clase y la ejecución de un método.

De igual manera, el SDK de PinPad proporciona una forma sencilla de conectarse con el Backend de PlacetoPay para obtener las posiciones de los botones de acción del PinPad y generar el Pinblock cifrado del PIN ingresado por el usuario. Por lo tanto, debe conocer los siguientes conceptos:

• PIN: número de dígitos del titular de la tarjeta de 4 a 12 dígitos de longitud.
• PAN: el PAN del número de tarjeta para obtener más información.
• Formato: formato a aplicar al PIN, puede ser 0, 1, 2 o 3 más información ISO 9564.
  • Formato 0: el bloque PIN se construye mediante la operación XOR de dos campos de 64 bits: el campo PIN de texto sin formato y el campo de número de cuenta, ambos compuestos por 16 nibbles de cuatro bits. Este formato lo utiliza EBUS.
  • Formato 1: este formato se debe utilizar cuando no hay PAN disponible.
  • Formato 2: el formato 2 es solo para uso local con sistemas fuera de línea, por ejemplo, tarjetas inteligentes.
  • Formato 3: el formato 3 es el mismo que el formato 0, excepto que los dígitos de "relleno" son valores aleatorios de 10 a 15, y el primer nibble (que identifica el formato del bloque) tiene el valor 3.

Cómo funciona

El SDK de PinPad se compone de dos clases principales:

• PinPad: clase que se encarga de renderizar el componente del PinPad en el frontend.
• PinPadClient: clase que se encarga de conectarse con el Backend de PlacetoPay para obtener las posiciones de los botones de acción del PinPad y generar el Pinblock cifrado del PIN ingresado por el usuario.

En el siguiente diagrama se describe de forma visual con mas detalle el ciclo de vida de la integración:

Instalación

Para instalar el SDK de PinPad, simplemente ejecuta el siguiente comando en tu terminal:

npm install @placetopay/pinpad

Uso

Para comenzar a utilizar el SDK de PinPad, primero debes importar la clase PinPad desde el paquete @placetopay/pinpad:

import { PinPad } from '@placetopay/pinpad'

Luego, crea una instancia de la clase PinPad:

const pinpad = new PinPad()

Una vez tengas la instancia, puedes ejectuar el metodo render para mostrar el input para el PinPad. Este método recibe un selector CSS para el contenedor donde se renderizarán los componentes del PinPad y como segundo parámetro las posiciones (obtenidas del Backend) de los botones de acción:

pinpad.render('#your-pinpad-container', positions)

El pinpad renderizado contiene un input para el PIN, asi podrás obtener el valor ingresado por el usuario al momento de enviar el formulario:

const form = document.querySelector('#your-form')

form.addEventListener('submit', (event) => {
  event.preventDefault()

  const formData = new FormData(form)

  const pin = formData.get('pin')
})

Conexión con el Backend

URLs de ambientes para conectarte a los servicios de PlacetoPay PinPad:

Crear transacción y obtener posiciones de los botones

Para obtener las posiciones de los botones de acción del PinPad, debes conectarte con el Backend de PlacetoPay. Para esto, puedes utilizar el SDK de PlacetoPay:

const client = new PinPadClient(API_URL, AUTH_TOKEN)
const response = await client.createTransaction()
const positions = response.data.data.positions

La respuesta que obtiene de la solicitud tiene la siguiente estructura:

{
    "data": {
        "status": {
          "status": "OK",
          "message": "The Transaction has been successfully generated"
        },
        "data": {
            "positions": "1,2,3,4,5,6,7,8,9,0",
            "transactionId": "1234567890"
        }
    }
}

Enviar el PIN para encriptar

Una vez que el usuario haya ingresado el PIN, debes enviarlo al Backend para encriptarlo, para esto puedes utilizar el SDK de PlacetoPay y el método generatePinBlock con los siguientes datos:

const data = {
    transactionId,
    format,
    pin,
    pan,
}

client.generatePinBlock(data)
    .then(res => {
        return res.data
    }).catch(err => {
        return err
    })

Obtendrás una respuesta como esta:

{
    "status": {
        "status": "OK",
        "message": "The PIN has been successfully encrypted"
    },
    "data": {
        "pinBlock": "1234567890ABCDEF"
    }
}

Full example

import { PinPad, PinPadClient } from '@placetopay/pinpad'

const pinpad = new PinPad()
const client = new PinPadClient(API_URL, AUTH_TOKEN)

document.addEventListener('DOMContentLoaded', async () => {
  const response = await client.createTransaction()
  const positions = response.data.data.positions

  pinpad.render('#your-pinpad-container', positions)
})

const form = document.querySelector('#your-form')
form.addEventListener('submit', async (event) => {
  event.preventDefault()

  const formData = new FormData(form)

  // ...

  const pin = formData.get('pin')
  const data = {
    transactionId,
    format,
    pin,
    pan,
  }

  const encryptedPin = await client.generatePinBlock(data)
  console.log(encryptedPin)

  // ...
})

Uso con CDN

Si prefieres utilizar el SDK de PinPad a través de un CDN, puedes hacerlo agregando este script a la cabecera de tu HTML:

  <script async src="https://unpkg.com/@placetopay/pinpad-sdk@2/dist/pinpad-sdk.umd.js"></script>

Luego, puedes utilizar el SDK de la siguiente manera:

<script>
  const pinpad = new PinpadSDK.PinPad()
  pinpad.render('#your-pinpad-container', '1,2,3,4,5,6,7,8,9,0')
</script>

Y el cliente para conectarse al API de PlacetoPay:

<script>
  const client = new PinpadSDK.PinPadClient(API_URL, AUTH_TOKEN)
  client.createTransaction()
    .then(response => {
      const positions = response.data.data.positions
      pinpad.render('#your-pinpad-container', positions)
    })
</script>

Uso con CDN en Javascript Environments

Si estás utilizando el SDK de PinPad en un entorno de JavaScript, puedes importar el SDK de la siguiente manera:

const loadScript = (url) => {
  return new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.src = url;
    script.onload = resolve;
    script.onerror = reject;
    document.head.appendChild(script);
  });
};

// Load the PinPad SDK and render the PinPad Component
loadScript('YOUR_CDN_URL')
  .then(() => {
    if (!window.PinpadSDK) {
      throw new Error('PinpadSDK is not available');
    }

    const pinpad = new PinpadSDK.PinPad()
    const client = new PinpadSDK.PinPadClient(API_URL, AUTH_TOKEN)
    client.createTransaction()
      .then(response => {
        const positions = response.data.data.positions
        pinpad.render('#your-pinpad-container', positions)
      })
  });

Integración Avanzada

Conoce en detalle los métodos y eventos disponibles

PinPad

Constructor

const pinpad = new PinPad(options);

PinPad.render

Renderiza el PinPad en el contenedor especificado.

pinpad.render(selector, positions);

PinPadClient

PinPadClient.createTransaction

Método para crear obtener el transactionId y las positions de los botones.

const response = await client.createTransaction();
const { transactionId, positions } = response.data.data;

PinPadClient.generatePinBlock

Método para encriptar el PIN ingresado por el usuario.

const data = {
  transactionId,
  format,
  pin,
  pan,
}

const response = await client.generatePinBlock(data);
const { pinBlock } = response.data.data;

Playground