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 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 este:
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.
  1. 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.moneylender.com/callback/
  2. 2.
    Hay que definir en qué dominio se cargará el widget.
  3. 3.
    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:
  4. 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.

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.

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

Parámetro
id
Explicación
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.
Parámetro
action
Explicación
Obligatorio, establecer con valor “payment”.
Parámetro
countryCode
Explicación
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.
Parámetro
banksShownPSD2
Explicación
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.
Parámetro
defaultBank
Explicación
En caso de tener valor, muestra al usuario un banco seleccionado por defecto.
Parámetro
autoStart
Explicación
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.
Parámetro
defaultLanguage
Explicación
En caso de tener valor, carga el widget en el idioma indicado. Formato ISO 3166-1. Actualmente ES y EN disponibles.
Parámetro
showSandbox
Explicación
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.
Parámetro
showSplashScreen
Explicación
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.
Parámetro
showCheckTerms
Explicación
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.
Parámetro
URLredirectAfterOK
Explicación
URL Redirección tras completar el pago
Parámetro
URLredirectAfterKO
Explicación
URL Redirección en caso de error
Parámetro
dailyFrequency
Explicación
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.
Parámetro
validUntil
Explicación
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.
Parámetro
paymentType
Explicación
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.
Parámetro
amount
Explicación
Obligatorio: Importe del pago en formato float. Por ejemplo, mil euros con 55 céntimos = 1000.55
Parámetro
currency
Explicación
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.
Parámetro
sourceIBAN
Explicación
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.
Parámetro
sourceCreditorName
Explicación
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.
Parámetro
destinationIBAN
Explicación
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.
Parámetro
destinationCreditorName
Explicación
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.
Parámetro
paymentDescription
Explicación
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.
Parámetro
firstQuotaDay
Explicación
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.
Parámetro
frequency
Explicación
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.
Parámetro
numberOfQuotas
Explicación
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.
Parámetro
urlCallback
Explicación
Obligatorio: URL Callback en caso de éxito a establecer de forma obligatoria.
Parámetro
urlCallbackError
Explicación
Obligatorio: URL Callback en caso de error a establecer de forma obligatoria.
Parámetro
singleTab
Explicación
Obligatorio: Establecer valor: 1

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:
https://afterbanks.atlassian.net/servicedesk/customer/portal/
  • 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: