Guía integración pagos en línea

Instrucciones de integración

Checklist de 3 puntos

Crear URL de callback.
Integrar el bloque de javascript en el documento en el que se pretende integrar el iframe.
Notificar la configuración necesaria al equipo de soporte de Arcopay.

Paso a paso

Crear un fichero .html o .php donde se se incluirá el widget.

Definir en el archivo una estructura básica de un documento HTML

<!DOCTYPE html>
<html lang="es">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Arcopay PSD2 Widget: Pagos en línea</title>
</head>

<body>
</body>
</html>

En el body del html incluímos unas etiquetas que nos ayudarán a mostrar el widget y los eventos que este envía.

<body>
    <h1>Arcopay PSD2 Widget</h1>
    <h2 id='frameResponse'></h2>
    <div id='arcopayContainer'></div>
</body>

El siguiente paso será incluir los tres scripts necesarios para el funcionamiento del widget. Justo antes de la etiqueta de cierre del <body> incluímos los siguientes tres scripts

Script de configuración de ejemplo para iniciar un pago en línea.

<script>
    let parameters = {
        "id": "Test-0001",
        "action": "payment",
        "countryCode": "ALL",
        "banksShownPSD2": "ALL",
        "defaultBank": "",
        "autoStart": 0,
        "defaultLanguage": "ES",
        "showSandbox": 0,
        "showSplashScreen": 0,
        "showCheckTerms": 0,
        "urlCallback": "<URL Callback a establecer de forma obligatoria>",
        "urlCallbackError": "<URL Callback en caso de error a establecer de forma obligatoria>",
        "URLredirectAfterOK": "<URL Redirección tras completar el pago>",
        "URLredirectAfterKO": "<URL Redirección en caso de error>",
        "dailyFrequency": 4,
        "validUntil": "31-12-2024",
        "paymentType": "normal",
        "amount": 0.01,
        "currency": "EUR",
        "sourceIBAN": "",
        "sourceCreditorName": "<Nombre del ordenante>",
        "destinationIBAN": "ES4400490001532110022225", // CRUZ ROJA
        "destinationCreditorName": "Cruz Roja",
        "paymentDescription": "",
        "firstQuotaDay": "",
        "frequency": "",
        "numberOfQuotas": ""
    };
</script>

Script encargado de recibir eventos desde el widget

<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.';
                    } else {
                        document.getElementById('frameResponse').innerHTML = 'Pago finalizado 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 encargado de cargar el widget

<script src="https://static.afterbanks.com/appmain/PSD2ExternalFormPay/js/external_mixed.js"></script>

Probamos lo que tenemos hasta ahora, abrimos el html y deberíamos ver un error como el de la imagen.
Error esperado
Es el momento de configurar el widget.
Para no encontrar el error ocurrido en el paso anterior necesitamos que el equipo de soporte de Arcopay configure ciertos detalles a saber:
1. Hay que definir una url de callback, donde el widget enviará la información obtenida. La URL a crear debe existir en el dominio del cliente. Por ejemplo: https://www.example.com/callback/
2. Hay que definir en qué dominio se cargará el widget.
3. Una vez tengamos estos dos detalles claros hay que abrir un ticket al servicio técnico de Aterbanks-Arcopay en la herramienta de soporte Nuek Support
  En caso de no estar registrados tendremos que registrarnos, este paso es necesario puesto que posteriormente cualquier comunicación con el equipo de Arcopay se realizará por esta vía, donde se hace un seguimiento detallado de cada incidencia.
  Una vez registrados crearemos un ticket nuevo de tipo solicitud donde indicaremos en el título una breve descripción de la solicitud, p.e. &lquote;Registrar dominio de referencia y callback&rquote;., y a continuación en la descripción los detalles de configuración del widget, dominio de referencia, URL del callback, si deseamos que se genere un token de acceso, si se desea que se obtengan transacciones y la profundidad de las mismas.
4. La configuración por parte de Arcopay es muy rápida y no debería pasar mucho tiempo desde que solicitamos la configuración hasta que esté aplicada y podamos seguir con las pruebas en el widget.

El callback

Una vez el widget ha recuperado la información bancaria del usuario se realiza una llamada desde nuestros servidores al endpoint configurado previamente para remitir los datos recopilados. El cuerpo de la llamada contiene un objeto JSON que tiene la siguiente forma:

{
    "token": "Token vinculado al pago. Este dato es útil en caso de ser necesario renovar el consentimiento en caso de expiración.",
    "paymentId": "Identificador de la iniciación del pago solicitada. Es útil para consultar el estado del pago, y hacer un seguimiento del progreso del mismo.",
    "service": "Nombre del servicio o entidad a la que se solicita la iniciación.",
    "clientId": "Identificador de la sesión del widget utilizado en la inicialización del widget."
}

Para que todo funcione bien se debe responder a la llamada recibida en el callback con un objeto JSON con las claves "result", "reason" y "nextURL" (ver ejemplos):

Objeto JSON que debe obtenerse cuando el proceso de recepción del callback es correcto, de forma que se continue el flujo en el navegador hacia la URL indicada para este caso. En caso contrario no se continuará hacia esta dirección o se mostrará un mensaje de proceso correcto pero con errores en el procesamiento de la información en el cliente.
```
{"result":"OK", "reason":"Datos recibidos correctamente por el callback del cliente", "nextURL":""}
```
Objeto JSON que debe obtenerse cuando el proceso de recepción del callback es correcto, de forma que se continue el flujo en el navegador hacia la URL indicada para este caso. En caso contrario no se continuará hacia esta dirección o se mostrará un mensaje de proceso correcto pero con errores en el procesamiento de la información en el cliente.
```
{"result":"KO", "reason":"Explicación del error", "nextURL":""}
```

Flujo del pago

Para hacer pruebas podemos configurar el widget con los siguientes parámetros de ejemplo y utilizar el sandbox.

let parameters = {  "id": "test-0001",
                    "action": "payment",
                    "client": "",
                    "banksShownPSD2": "ALL",
                    "defaultBank": "",
                    "urlCallback": "<Sustituir por URL de callback>",
                    "urlCallbackError": "<Sustituir por URL de callback>",
                    "getCallbackResult": 1,
                    "defaultLanguage": "es",
                    "showSandbox": 1,
                    "showSplashScreen": 0,
                    "showCheckTerms": 1,
                    "URLredirectAfterOK": "<Sustituir por URL de redireccion>",
                    "URLredirectAfterKO": "<Sustituir por URL de redireccion>",
                    "paymentType": "normal",
                    "amount": 0.01,
                    "sourceCreditorName": "John Doe",
                    "destinationIBAN": "ES4400490001532110022225", // CRUZ ROJA
                    "singleTab": 1
                };

Seleccionamos el servicio de Sandbox de BBVA y pulsamos el botón de pagar:

Realizamos el login con el banco modo sandbox con los siguientes datos:
- Usuario: user1
- Contraseña: 1234 o 123456
- 2FA/OTP/SMS: 1234 o 123456
Seleccionamos la cuenta con la que queremos realizar el pago si no lo hemos especificado en los parámetros de carga (sourceIBAN) y hacemos click en pagar.
Aceptamos el pago e introducimos el OTP: 1234 o 123456
En este punto si el pago ha sido correcto, se ejecutará una redirección a la URL establecida en el parámetro “URLredirectAfterOK”. En caso de error a la URL “URLredirectAfterKO”.
Del mismo modo, el envío de la respuesta al callback. En caso de éxito a la URL “urlCallback” y en caso de error a la URL “urlCallbackError”.

Configuración adicional

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.
Guía de Signature Parámetros Widget

El método /payment/getLinkForPayment/, también compatible con el widget de pagos en línea, 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 de un solo uso lista para mostrar al cliente final. Opcionalmente, este mismo método permite enviar el smartlink por SMS. Ejemplo de respuesta:

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

Listado de parámetros

Parámetro	Explicació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. 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, establecer con valor “payment”.
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	Códigos de bancos separados por coma. El listado completo se puede obtener de la clave service del endpoint https://apipsd2.afterbanks.com/listOfSupportedBanks/. Filtra el listado de bancos que se muestra al usuario.
defaultBank	En caso de tener valor, muestra al usuario un banco seleccionado por defecto.
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 un banco con nombre Sandbox que permite 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 0, desactivado.
URLredirectAfterOK	URL Redirección tras completar el pago
URLredirectAfterKO	URL Redirección en caso de error
dailyFrequency	Tomado en consideración cuando el valor de action es read. Número máximo de veces que se podrá acceder con el token obtenido al día 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 89 días desde la fecha actual.
paymentType	Obligatorio: 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: Importe del pago en formato float. Por ejemplo, mil euros con 55 céntimos = 1000.55
currency	Tomado en consideración cuando el valor de 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 de 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 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 proceso de Blanqueo de Capitales. 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 de action es payment. IBAN de destino. En caso de no especificarse valor, se tomará el IBAN que Arcopay tenga configurado en su backend. Si necesita conocer o modificar el valor de destinationIBAN en backend, escriba un ticket a soporte. Si usted trabaja con varios bancos donde recibir pagos, puede enviarnos el listado completo, y el widget decidirá el valor de destinationIBAN en función al banco de origen del pago, convirtiendo así las transferencias en traspasos.
destinationCreditorName	Tomado en consideración cuando el valor de action es payment. 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. Longitud máxima 140 caracteres. En caso de no especificarse el valor, este parámetro tomará el valor de id.
firstQuotaDay	Obligatorio si el valor de action es payment y el 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 de action es payment y el paymentType es Periodic. Si el cobro es periódico. Los valores posibles son daily, weekly, everyTwoWeeks, monthly, everyTwoMonths, quarterly, annual.
numberOfQuotas	Obligatorio si el valor de action es payment y el 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.
urlCallback	Obligatorio: URL Callback en caso de éxito a establecer de forma obligatoria.
urlCallbackError	Obligatorio: URL Callback en caso de error a establecer de forma obligatoria.
singleTab	Obligatorio: Establecer valor: 1

Gestión de errores

Para reportar cualquier incidencia o comunicación con el equipo técnico, por favor utilice siempre nuestra herramienta de tickets en la plataforma de Nuek Support.

Envío de eventos

Los códigos de evento que puede enviar el widget se detallan en este documento.

Acceso a las APIs

En los casos en los que no se desee usar el widget, o se quiera hacer uso de funcionalidad adicional a la que aporta el widget, es posible hacer uso de la APIs, documentadas en los siguientes enlaces:

Instrucciones de integración​

Checklist de 3 puntos​

Paso a paso​

El callback​

Flujo del pago​

Configuración adicional​

Widget hospedado en arcopay.io​

Listado de parámetros​

Gestión de errores​

Envío de eventos​

Acceso a las APIs​