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'];
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 {
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.

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 [email protected], 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.

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"
}
}
]