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

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