# 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 .html o .php donde se incluirá el widget: * Creamos un simple html con una estructura básica: ```html Arcopay PSD2 Widget: Pagos en línea ``` * En el body del html incluímos unas etiquetas que nos ayudarán a mostrar el widget y los eventos que este envía: ```html

Arcopay PSD2 Widget

``` * El siguiente paso será incluir los 3 scripts necesarios para el funcionamiento del widget. Justo antes de la etiqueta de cierre del \ incluímos los siguientes scripts: * Script de configuración de ejemplo para iniciar un pago en línea. ```html ``` * Script encargado de recibir eventos desde el widget: ```html ``` * [Script encargado de cargar el widget:](#user-content-fn-1)[^1] ```html ``` * 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. 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/](https://www.google.com/url?q=https://www.moneymas.com/callback/\&sa=D\&source=editors\&ust=1706633404264452\&usg=AOvVaw3mCqJMb9BNSGRkbau2V2IH) 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: [https://afterbanks.atlassian.net/servicedesk/customer/portal/1](https://www.google.com/url?q=https://afterbanks.atlassian.net/servicedesk/customer/portal/1\&sa=D\&source=editors\&ust=1706633404265217\&usg=AOvVaw3iAHukIEb0aWDm_jpB2r2O) * 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. 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 {% code overflow="wrap" %} ```json {"result":"OK", "reason":"Datos recibidos correctamente por el callback del cliente", "nextURL":""} ``` {% endcode %} * Cuando es KO ```json {"result":"KO", "reason":"Explicación del error", "nextURL":""} ``` #### El JSON que se envía al callback tras el pago es el siguiente: ```json { "token": "", "paymentId": "", "service": "", "clientId": "" } ``` ### Flujo del pago: * Para hacer pruebas podemos configurar el widget con los siguientes parámetros de ejemplo y utilizar el sandbox. ```javascript let parameters = { "id": "test-0001", "action": "payment", "client": "", "banksShownPSD2": "ALL", "defaultBank": "", "urlCallback": "", "urlCallbackError": "", "getCallbackResult": 1, "defaultLanguage": "es", "showSandbox": 1, "showSplashScreen": 0, "showCheckTerms": 1, "URLredirectAfterOK": "", "URLredirectAfterKO": "", "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](https://www.google.com/url?q=https://docs.google.com/document/d/1_3OnE13N7v36FEvEVm3B7lGbUWfFm0pLY9oc3MrZZGk/edit%23\&sa=D\&source=editors\&ust=1706633404276762\&usg=AOvVaw0UTVLA1wo6W5xSrbffiDYx) ### 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](https://www.google.com/url?q=https://app.swaggerhub.com/apis/Afterbanks/Afterbanks-PSD2-ES\&sa=D\&source=editors\&ust=1706633404277767\&usg=AOvVaw2RfPRL6ji9qScFq64hQ_tH) 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: ```json [ { "linkForPayment":"https://arcopay.io/payWithYourBank/cEv-DOVDMro/", "code":0, "additional_info":{ "status":"sent", "phoneNumber":"+34644501035" } } ] ``` ### ### LISTADO DE PARÁMETROS
ParámetroExplicació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.

actionObligatorio, establecer con valor “payment”.
countryCodeCó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.
banksShownPSD2Có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.
defaultBankEn caso de tener valor, muestra al usuario un banco seleccionado por defecto.
autoStartEn 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.
defaultLanguageEn caso de tener valor, carga el widget en el idioma indicado. Formato ISO 3166-1. Actualmente ES y EN disponibles.
showSandboxMuestra 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.
showSplashScreenMuestra 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.
showCheckTermsMuestra 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.
URLredirectAfterOKURL Redirección tras completar el pago
URLredirectAfterKOURL 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.

paymentTypeObligatorio: 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.
amountObligatorio: 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.

urlCallbackObligatorio: URL Callback en caso de éxito a establecer de forma obligatoria.
urlCallbackErrorObligatorio: URL Callback en caso de error a establecer de forma obligatoria.
singleTabObligatorio: 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](https://www.google.com/url?q=https://docs.google.com/spreadsheets/d/1uSklhc5NQrocf3yc7qk-sUsSkcOGdVO2pAvMoxnQDvE/edit%23gid%3D0\&sa=D\&source=editors\&ust=1706633404314366\&usg=AOvVaw3qvvGPnQRKSe7TkrOM6zuV)
### 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: * ES: [https://app.swaggerhub.com/apis/Afterbanks/Afterbanks-PSD2-ES/](https://www.google.com/url?q=https://app.swaggerhub.com/apis/Afterbanks/Afterbanks-PSD2-ES/\&sa=D\&source=editors\&ust=1706633404315398\&usg=AOvVaw0GV3CPjbh5P25gnQyp9itt) * EN: [https://app.swaggerhub.com/apis/Afterbanks/Afterbanks-PSD2-EN/](https://www.google.com/url?q=https://app.swaggerhub.com/apis/Afterbanks/Afterbanks-PSD2-EN/\&sa=D\&source=editors\&ust=1706633404315943\&usg=AOvVaw3duPC3VVgYIZyxAkczZD76) [^1]: --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-es.arcopay.io/guia-integracion-pagos-en-linea.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.