Guía de integración del Widget

El widget javascript que te proporcionamos simplifica la integración tanto de la API de Agregación Bancaria como de la API de Iniciación de Pagos.

Especificaciones

El widget javascript que te proporcionamos simplifica la integración de cualquiera de las APIs de Afterbanks Arcopay. Las más utilizadas son la API de Agregación Bancaria con Identificación de Titularidad (PSD2 y NO-PSD2) y la API de Iniciación de Pagos (PSD2) que utilizan a diario más de 100 clientes para conectar a más de 500.000 cuentas de bancos de todo el mundo cada día, pero este mismo widget, en base a su parametrización descrita más adelante, permite el uso de:

  • API Utilities, que conecta con los proveedores de energía y telecomunicaciones, descarga las facturas en formato PDF y extrae información de utilidad en formato JSON normalizado, como es el código CUPs, tarifa contratada y líneas de la factura.

  • API Broker, que obtiene la posición y el detalle de carteras de valores: fondos y acciones.

  • API Insurance, que conecta con las aseguradoras y descarga las pólizas contratadas de las distintas ramas: auto, hogar, salud, etc.

Esta guía describe el proceso para crear un iframe mostrando un listado de servicios, que permite al usuario final iniciar el flujo de obtención de consentimiento para conectar con su banco y extraer su información transaccional o para iniciar un pago.

Una vez finaliza el flujo, el widget envía la respuesta a una URL de callback en el servidor del cliente y adicionalmente notifica, mediante el envío de un evento, a la página padre.

Resultado final y ejemplos

En democenter.arcopay.io puedes ver diferentes ejemplos.

En el siguiente enlace puedes ver y probar el widget en funcionamiento en Codepen.

Instrucciones para la integración

La integración consta de tres fases: (1) crear una URL de callback, (2) integrar el bloque en el documento donde debe aparecer el selector de bancos, (3) notificar al equipo de Arcopay para finalizar la activación.

1. Creación de la URL de callback

En función a la configuración establecida en el momento de la contratación del widget, recibirás una respuesta diferente en tu URL de callback:

  • Banco utilizado + Lectura con posición global.

  • Banco utilizado + Lectura con posición global y movimientos.

  • Banco utilizado + Información del Pago.

Te proporcionamos el siguiente bloque de código en PHP que puedes utilizar como base para tu URL de callback, que tendrá un nombre similar a https://www.tuempresa.com/callback-widget/

<?php
    header('Content-Type: application/json; charset=UTF-8');
    header('Access-Control-Allow-Origin: *');
    setlocale(LC_ALL, 'es_ES.UTF-8');
     
    $jsonRecibido = file_get_contents('php://input');
    $jsonEnArray  = json_decode($jsonRecibido, true);
     
    if ((array_key_exists('id', $jsonEnArray) && array_key_exists('token', $jsonEnArray) && array_key_exists('consentId', $jsonEnArray) && array_key_exists('globalPosition', $jsonEnArray) && (count($jsonEnArray['globalPosition'])>0)) || (array_key_exists('id', $jsonEnArray) && array_key_exists('token', $jsonEnArray) && array_key_exists('paymentId', $jsonEnArray))) {
        $id = $jsonEnArray['id'];
        // Es PSD2
        if (array_key_exists('consentId', $jsonEnArray)) {
            // Es read
        } else {
            // Es payment
        }
        echo '{"result":"OK", "reason":"Datos recibidos correctamente por el callback del cliente", "nextURL":""}';
    } else if (array_key_exists('id', $jsonEnArray) && array_key_exists('token', $jsonEnArray) && array_key_exists('jsonResponse', $jsonEnArray) && count($jsonEnArray['jsonResponse'])>0) {
        // Es V3 read
        echo '{"result":"OK", "reason":"Datos recibidos correctamente por el callback del cliente", "nextURL":""}';
    } else {
        // Es error
        echo '{"result":"KO", "reason":"El JSON recibido por el callback del cliente no tiene la estructura esperada", "nextURL":""}';
    }
?>

Cuando Arcopay se comunica con tu URL de callback para enviarte el resultado de la ejecución del widget, espera obtener una de las siguientes respuestas:

// Cuando es OK:
{
	"result": "OK",
	"reason": "Datos recibidos correctamente por el callback del cliente",
	"nextURL": ""
}
// Cuando es KO:
{
	"result": "KO",
	"reason": "Explicación del error",
	"nextURL": ""
}

Te proporcionamos una colección Postman en el siguiente enlace que te permitirá lanzar pruebas en el callback que acabas de crear, de tal forma que puedas probar que la recepción de datos es correcta en tu lado: Postman Callback Tester.

En función de si la entidad utilizada es una entidad accedida por PSD2 o no, la respuesta que se obtiene en el callback del widget es distinta. En caso de ser una entidad accedida por la vía PSD2 o por la vía NOPSD2/V3 obtendremos las siguientes objetos JSON en el cuerpo de la petición realizada al callback:

// Cuando es PSD2
{
	"id": "[string] Identificador utilizado al instanciar el widget y para identificar al cliente ",
	"token": "[string] Token de acceso para futuras sincronizaciones a través de las APIs",
	"consentId": "[string] Identificador del consentimiento otorgado por el usuario",
	"globalPosition": "[array] La posición global. Listado de productos con sus saldos y titulares.",
	"enhancedPosition": "[array] Listado de productos con las transacciones."
}
// Cuando es NOPSD2/V3
{
	"id": "[string] Identificador utilizado al instanciar el widget y para identificar al cliente ",
	"token": "[string] Token de acceso para futuras sincronizaciones a través de las APIs",
	"jsonResponse": "[array] Listado de productos con sus saldos, transacciones y titulares.",
	"jsonResponseID": "[object] Datos de identidad del usuario utilizado para el acceso. No es siempre posible obtener esta información."
}

2. Integración del iframe

Una vez hayas decidido la landing o paso de tu proceso donde se ubicará el selector de bancos, debes incluir el siguiente bloque de código:

1.- En el body ubicamos el conenedos que albergara el widget.

 <div id='arcopayContainer'></div>

2.- Añadimos el script para la generacion del widget (ejemplo para agregación mixta, los parámetros deben ir configurados en función de las necesidades y segun la tabla "Listado de parámetros")

<script>
    let parameters = {
        // ID de cliente
        "id": "Test-0001",
        // Acción del widget
        "action": "read",
        // Configuración del widget
        "countryCode": "ALL",
        "banksShownPSD2": "N26,bankinter,sandbox",
        "banksShownV3": "bbva,caixa,bankia,bankia_emp,ingdirect",
        "defaultBank": "",
        "autoStart": 0,
        "defaultLanguage": "ES",
        "showSandbox": 0,
        "showSplashScreen": 0,
        "showCheckTerms": 0,
        "URLredirectAfterOK": "",
        "URLredirectAfterKO": "",
        // Parámetros READ PSD2
        "dailyFrequency": 4,
        "validUntil": "31-12-2021"
    };
</script>
<script>
    function receiveFromFrame(ev) {
        if (ev.data != ''&& ev.data.code != undefined && ev.data.message != undefined) {
            let codigo = ev.data.code;
            let mensaje = ev.data.message;
            let widgetContainer = document.getElementById('arcopayContainer');
            console.warn(`${codigo} - ${mensaje}`);
            switch (codigo) {
                case 200:
                    if (parameters.action == 'read') {
                        document.getElementById('frameResponse').innerHTML = 'Lectura finalizada correctamente.';
                    }
                    break;
                case 9999: // Cambio en el tamaño del widget
                    widgetContainer.style.height = mensaje + 'px';
                    window.scrollTo(0, 0);
                    document.getElementById('iframeArcopay').contentWindow.postMessage({"action": "changeIframeHeight"}, 'https://www.afterbanks.com/');
                   break;
                default:
                    document.getElementById('frameResponse').innerHTML = `${codigo} - ${mensaje}`;
                    break;
            }
        }
    }
    window.addEventListener("message", receiveFromFrame, false);
</script>
<script src="https://static.afterbanks.com/appmain/PSD2ExternalForm/js/external_mixed.js"></script>

Ejemplo completo:

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Arcopay Widget</title>
</head>
<body>
    <h1>Arcopay Widget</h1>
    <h2 id='frameResponse'></h2>
    <div id='arcopayContainer'></div>
</body>
<script>
    let parameters = {
        // ID de cliente
        "id": "Test-0001",
        // Acción del widget
        "action": "read",
        // Configuración del widget
        "countryCode": "ALL",
        "banksShownPSD2": "N26,bankinter,sandbox",
        "banksShownV3": "bbva,caixa,bankia,bankia_emp,ingdirect",
        "defaultBank": "",
        "autoStart": 0,
        "defaultLanguage": "ES",
        "showSandbox": 0,
        "showSplashScreen": 0,
        "showCheckTerms": 0,
        "URLredirectAfterOK": "",
        "URLredirectAfterKO": "",
        // Parámetros READ PSD2
        "dailyFrequency": 4,
        "validUntil": "31-12-2021"
    };
</script>
<script>
    function receiveFromFrame(ev) {
        if (ev.data != ''&& ev.data.code != undefined && ev.data.message != undefined) {
            let codigo = ev.data.code;
            let mensaje = ev.data.message;
            let widgetContainer = document.getElementById('arcopayContainer');
            console.warn(`${codigo} - ${mensaje}`);
            switch (codigo) {
                case 200:
                    if (parameters.action == 'read') {
                        document.getElementById('frameResponse').innerHTML = 'Lectura finalizada correctamente.';
                    }
                    break;
                case 9999: // Cambio en el tamaño del widget
                    widgetContainer.style.height = mensaje + 'px';
                    window.scrollTo(0, 0);
                    document.getElementById('iframeArcopay').contentWindow.postMessage({"action": "changeIframeHeight"}, 'https://www.afterbanks.com/');
                   break;
                default:
                    document.getElementById('frameResponse').innerHTML = `${codigo} - ${mensaje}`;
                    break;
            }
        }
    }
    window.addEventListener("message", receiveFromFrame, false);
</script>
<script src="https://static.afterbanks.com/appmain/PSD2ExternalForm/js/external_mixed.js"></script>
</html>

Cada parámetro está descrito en la sección Listado de parámetros, más abajo.

Cuando abras la página recién creada en tu navegador, recibirás un mensaje de error indicando que te comuniques con el equipo de soporte de Arcopay para finalizar la configuración. Estás listo para pasar al último paso.

3. Notificar al equipo de Arcopay para finalizar la activación

Crea un ticket a soporte en la siguiente dirección. Si aún no tienes usuario de soporte, puedes registrarte en tu misma página: https://afterbanks.atlassian.net/servicedesk/customer/portal/1

Si trabajas en un equipo de desarrollo, es aconsejable que te registres en nuestro Jira con un buzón de correo genérico, por ejemplo programadores@tuempresa.com, para que varias personas de tu equipo puedan hacer seguimiento de los tickets.

En el ticket, escribe la siguiente información:

Asunto: Activación de Widget Cuerpo: La URL de callback es https://www.tuempresa.com/callback-widget/ y el dominio desde donde cargará el iframe es www.tuempresa.com

Listado de parámetros

Configuración avanzada (opcional)

Gestión de redirecciones

Cuando se complete una lectura o un pago, dependiendo de la respuesta proporcionada por tu URL de callback el widget procederá de la siguiente manera:

  • Si existe una key nextURL conteniendo una URL en el JSON devuelto por el callback del cliente, se redireccionará a esta url.

  • Si existe un parámetro URLredirectAfterOK o URLredirectAfterKO, se redireccionará a la url indicada.

  • Si no existe en la respuesta ningún valor indicando una URL, se mostrará en pantalla el resultado obtenido.

En los 3 casos anteriores, el iframe siempre enviará un evento notificando de la finalización correcta o del error a la ventana "parent" llamado "message", con el contenido del resultado obtenido. Por tanto las redirecciones también se pueden gestionar desde este punto, en el lado del front. En la sección gestión de errores y envío de eventos encontrarás un documento con la explicación detallada y la acción a tomar en cada uno de los posibles eventos enviados desde el widget.

Números de cuentas bancarias (IBANS) dinámicos para pagos

Es posible configurar un IBAN de destino por defecto para recibir los pagos, y no tener así que informarlo como parámetro en la carga del Widget.

También es posible configurar un conjunto de IBANs de destino a diferentes bancos. Esto es útil para que los pagos viajen más rápido y evitar posibles comisiones al cliente final. Por ejemplo, si tu empresa trabaja con: BBVA, Sabadell, Caixabank, Santander, ING Direct y Bankinter, puedes solicitar mediante un ticket que configuremos todos estos bancos en nuestro backend. Cuando el widget detecte que un cliente va a pagar con uno de estos bancos, utilizará el mismo como cuenta de destino, realizando un traspaso (inmediato y sin comisiones) en lugar de una transferencia.

Firma de los parámetros

Existe la opción de aplicar una capa extra de seguridad para asegurar que los datos recibidos por el widget no han sido alterados por ningún actor intermedio. La firma se realizará utilizando SHA_256 y una clave RSA generada por el cliente. La documentación está disponible bajo petición a soporte.

Existe la posibilidad de generar smartlinks de pagos que dirigen a una landing hospedada en arcopay.io. Esta opción simplifica la generación de enlaces con todos los datos de pago parametrizados, fáciles de compartir por mensajería como Whatsapp, SMS, QR, Email, PDF, etc.

El método /payment/getLinkForPayment/, documentado en la documentación PSD2 recibe como parámetro los datos necesarios para configurar un link de pago, y genera como respuesta una URL lista para mostrar al cliente final. Opcionalmente, este mismo método permite enviar el smartlink por SMS. Ejemplo de respuesta:

[
 {
  "linkForPayment": "https://www.arcopay.io/payWithYourBank/cEv-DOVDMro/",
  "code": 0,
  "additional_info": {
   "status": "sent",
   "phoneNumber": "+34644501035"
  }
 }
]

Last updated