Guía integración pagos en línea

Guía de integración para pagos en línea con Widget Javascript.

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 .html o .php donde se incluirá el widget:
Creamos un simple html con una estructura básica:

<!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 3 scripts necesarios para el funcionamiento del widget. Justo antes de la etiqueta de cierre del <body> incluímos los siguientes 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 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 este:

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.

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.moneylender.com/callback/
Hay que definir en qué dominio se cargará el widget.
Una vez tengamos estos dos detalles claros hay que abrir un ticket al servicio técnico de Aterbanks-Arcopay en: https://afterbanks.atlassian.net/servicedesk/customer/portal/1
- 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 abriremos un ticket eligiendo la opción de soporte técnico:
- Indicando los detalles necesarios para realizar la configuración:
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.

Para que todo funcione bien deberemos responder a la llamada recibida en el callback como mínimo un JSON con las keys result, reason y nextURL:

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

El JSON que se envía al callback tras el pago es el siguiente:

{
    "token": "<Token generado>",
    "paymentId": "<Identificador del pago>",
    "service": "<Nombre de la entidad con el que se ha realizado el pago>",
    "clientId": "<Id cliente con el que se ha cargado el widget>"
}

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

WIDGET HOSPEDADO EN ARCOPAY.IO

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

GESTIÓN DE ERRORES Y ENVÍO DE EVENTOS

Para reportar cualquier incidencia o comunicación con el equipo técnico, por favor utilice siempre nuestra herramienta
de tickets en la plataforma de Jira. Nos facilita un mejor seguimiento:

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

ACCESO A LA API

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 API, documentada en los siguientes enlaces:

PreviousGuía de integración del Widget NextPreguntas frecuentes sobre integración por API

Last updated 5 months ago