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 (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>   </body>
</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 [e-mail], 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

Parámetro	Descripción
id	Obligatorio. Identificador único de la operación generado por el cliente con el que se identificará la información recibida en el callback. En el caso de una operación de pago, este identificador aparecerá en el concepto del pago, por lo que es aconsejable que coincida con un identificador de pedido, o código de factura. Solo se permiten caracteres alfanuméricos y guión.
action	Obligatorio. Valores posibles: “read”, “payment”, “broker”, “ownership”, “insurance” o “utilities”.
countryCode	Códigos de país separados por coma en ISO 3166-1, por ejemplo ES para España, o ALL para todos los disponibles. Filtra el listado de bancos que se muestra al usuario. Si no se especifica valor, tomará por defecto el del país del usuario.
banksShownPSD2	Obligatorio cuando el valor de "action" es "read" o "payment". Códigos de bancos separados por coma. El listado completo está disponible en el método https://apipsd2.afterbanks.com/listOfSupportedBanks/, en la key "service". Filtra el listado de bancos que se muestra al usuario.
banksShownV3	Obligatorio cuando el valor de "action" es "read", "payment", "broker" o "titularidad". Códigos de bancos separados por coma. El listado completo está disponible en los métodos https://api.afterbanks.com/V3/forms/ y https://api.afterbanks.com/Broker/forms/ , en la key "service". Dependiendo del país, encontrarás bancos en este listado que también están disponibles en el listado del parámetro anterior. En ese caso, puedes elegir cualquiera de ellos. Filtra el listado de bancos que se muestra al usuario.
servicesShown	Obligatorio cuando el valor de "action" es "insurance" o "utilities". Códigos de servicios separados por coma. Los servicios soportados están disponible en los métodos https://api.afterbanks.com/Insurance/forms/ y https://api.afterbanks.com/Utilities/forms/, en la key "service". Filtra el listado de servicios que se muestra al usuario. Si no se especifica valor, tomará por defecto el valor "ALL", mostrando todos los disponibles en el "countryCode" seleccionado.
defaultService	En caso de tener valor, muestra al usuario un banco o servicio seleccionado, en lugar del selector de servicios. Ahorra un click cuando es conocido qué servicio tiene intención de agregar el usuario.
autoStart	En caso de haber recibido un servicio válido en el parámetro defaultBank o haber detectado el banco automáticamente en función del IBAN de origen indicado en el parámetro sourceIBAN, el flujo de consentimiento se iniciará sin pedir al usuario que seleccione el banco. Los valores posibles son 0 ó 1. El valor por defecto es 0, desactivado.
defaultLanguage	En caso de tener valor, carga el widget en el idioma indicado. Formato ISO 3166-1. Actualmente ES y EN disponibles.
showSandbox	Muestra al usuario bancos con nombre Sandbox que permiten al cliente hacer pruebas con un servicio mock. Los valores posibles son 0 ó 1. El valor por defecto es 0, desactivado.
showSplashScreen	Muestra una una pantalla inicial explicando al usuario en qué consiste el servicio. Los valores posibles son 0 ó 1. El valor por defecto es 0, desactivado.
showCheckTerms	Muestra una casilla de verificación de aceptación de términos junto al enlace de términos y condiciones. Los valores posibles son 0 ó 1. El valor por defecto es 1, activado.
URLredirectAfterOK	Si el flujo termina correctamente, URL a la que redirigir al usuario. Se tomará en cuenta si el callback del cliente no devuelve una url donde quiere ser redirigido en la key nextURL. Observa que este parámetro es opcional ya que hay otras opciones para controlar cómo continúa el flujo, detalladas en esta guía, como la notificación a la página padre mediante un evento javascript, o que sea la respuesta proporcionada por la URL de callback la que indique la URL de redirect.
URLredirectAfterKO	Si el flujo no termina correctamente, URL a la que redirigir al usuario. Se tomará en cuenta si el callback del cliente no devuelve una url donde quiere ser redirigido en la key nextURL. Observa que este parámetro es opcional.
dailyFrequency	Tomado en consideración cuando el valor de action es read. Número máximo de veces que se podrá acceder al día con el token obtenido en modo lectura. Los valores posibles son del 1 al 4. El valor por defecto es 4.
validUntil	Tomado en consideración cuando el valor de action es read. Fecha hasta la que serán válidos los tokens de consentimiento de acceso, en formato dd-mm-yyyy. El valor máximo es 89 días desde la fecha actual. El valor por defecto es el día actual.
paymentType	Obligatorio si el valor de action es payment. Los valores posibles son: normal, instant, normalPeriodic o instantPeriodic. El valor por defecto es normal. Desaconsejamos indicar pago instantáneo, ya que la probabilidad de que el banco del cliente le cargue una comisión es muy alta, y las APIs regulatorias no informan sobre la comisión a los TPP, por lo que no es un factor controlable por el widget.
amount	Obligatorio si el valor de action es payment. Importe del pago en formato float. Por ejemplo, mil euros con 55 céntimos = 1000.55
currency	Tomado en consideración cuando el valor del parámetro action es payment. Código de la divisa en formato ISO 4217. El valor por defecto es EUR.
sourceIBAN	Tomado en consideración cuando el valor del parámetro action es payment. IBAN del origen de los fondos. En caso de no especificarse el valor, se mostrará un selector de cuentas al usuario final. En caso de no tener fondos suficientes para el pago en el IBAN indicado también se mostrará el selector de cuentas.
sourceCreditorName	Tomado en consideración cuando el valor de action es payment. Nombre de la persona que realiza el pago. Este valor es utilizado para realizar el control de Blanqueo de Capitales (PBC). Si se especifica su valor el widget será capaz de iniciar pagos directos, de otro modo el widget siempre deberá realizar el pago en dos pasos, para en el primero obtener el nombre del titular de la cuenta origen.
destinationIBAN	Tomado en consideración cuando el valor del parámetro action es payment. IBAN de destino. En caso de no especificarse valor, se tomará el IBAN que Arcopay tenga configurado en su backend. Si necesitas conocer o modificar el valor de destinationIBAN en backend, escribe un ticket a soporte.
destinationCreditorName	Obligatorio si el parámetro destinationIBAN no es vacío. Nombre del titular de la cuenta. En caso de no especificarse valor, se tomará el IBAN en el que se va a recibir el pago.
paymentDescription	Tomado en consideración cuando el valor de action es payment. Concepto del pago. La longitud máxima es de 140 caracteres. En caso de no especificarse el valor, este parámetro tomará el valor de id.
firstQuotaDay	Obligatorio si el valor del parámetro action es payment y el valor del parámetro paymentType es Periodic. Si el cobro es periódico. Día del primer cargo de la cuota, en formato dd-mm-yyyy.
frequency	Obligatorio si el valor del parámetro action es payment y el valor del parámetro paymentType es Periodic. Si el cobro es periódico. Los valores posibles son daily, weekly, everyTwoWeeks, monthly, everyTwoMonths, quarterly, annual.
payments	Parámetro utilizado para iniciar pagos Bulk. Tipo de dato aceptado: array de objetos. Si el valor del parámetro action es "payment" y no se recibe un paymentType o amount, existe la posibilidad de realizar un pago Bulk pasando un array de pagos en este parámetro. Dentro de éste array habrán varios objetos de pago con la siguiente información sobre cada uno de ellos: amount, destinationIBAN, destinationCreditorName y paymentDescription. Array de ejemplo pago bulk: [{"amount":12.01,"destinationIBAN":"ES4400490001532110022225","destinationCreditorName":"John","paymentDescription":"Pago bulk 1"},{"amount":0.1,"destinationIBAN":"ES94 2038 6214 0930 0005 0386","destinationCreditorName":"Mock","paymentDescription":"Pago bulk 2"}]
numberOfQuotas	Obligatorio si el valor del parámetro action es payment y el valor del parámetro paymentType es Periodic. Si el cobro es periódico. Valor entero que indica el número de pagos que se harán. Por ejemplo, si la orden corresponde a la devolución de un préstamo en 60 cuotas. El valor será 60.
payFromIframe	Parámetro utilizado para ejecutar el proceso del pago sin salir del iframe de Afterbanks Arcopay si se especifica el valor: 1 Operativo con los siguientes servicios: ['bbva','sabadell','sandbox','ibercaja','kutxabank','cajamar','openbank','evobanco','selfbank','cajasur','renta4','arquia','colonya','caixaontinyent','pichincha']

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.

Widget hospedado en arcopay.io para pagos (smartlinks de pagos)

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": "[phone]"
  }
 }
]