PayByBank

Introducción

PayByBank, PBB a partir de ahora, es una solución de pago con cuenta bancaria que permite el acceso a una red de pagos de banca abierta.

La solución de pagos de Addon Payments, PayByBank, está construida sobre Truelayer, que es una red de pagos para banca abierta que conecta bancos, comercios y clientes de Europa y de Reino Unido.

Con Truelayer (PayByBank en Addon Payments) puedes operar de dos formas:

1. Circuito abierto: El importe de los pagos se ingresa directamente en la cuenta bancaria de tu comercio, ajena a Truelayer. Esta modalidad no admite ni devoluciones ni pagos a clientes.

2. Circuito cerrado: El importe de los pagos se ingresa en la cuenta de tu comercio en la plataforma Truelayer. Pues transferir esos fondos a tus otras cuentas de forma manual o automática a través del panel de gestión de Truelayer.

Tipo de pago	Transferencia bancaria
Países disponibles	AUT, BEL, EST, FIN, FRA, DEU, IRL, ITA, LTU, NLD, POL, PRT, ROU, ESP, SWE, GBR
Divisas disponibles	Euro y libra esterlina
¿Necesita redirección?	Sí
¿Admite pago en dos pasos?	No
¿Admite devoluciones?	Sí, total y parcial (sólo en circuito cerrado)

Las devoluciones o pagos al cliente (Payouts) en la modalidad de circuito cerrado se efectúan con el saldo de tu cuenta de Truelayer. Si no tienes saldo, puedes esperar a recibir fondos o puedes hacer una transferencia a la cuenta de tu comercio en Truelayer. Puedes usar ambas operativas en tu comercio si se configuran dos productos, uno para cada operativa.

Por último, dispones de una colección Postman donde puedes probar las distintas operativas de PayByBank:

Postman

Operativas admitidas

PayByBank está disponible en los 3 tipos de integración. Por otro lado, las operativas admitidas son:

Autorización: Un pago normal del cliente a tu comercio. La captura del importe es automática.
Anulación: Cancelación total del importe del pago. A través del BackOffice o mediante endpoint. La operación a anular debe estar en un estado concreto. Más detalles en esta sección.
Devoluciones: Devoluciones totales o parciales. A través del BackOffice o mediante endpoint.
PayByLink: Envía a los clientes un enlace de pago, mediante mail, QR, etc. Únicamente para integraciones Host2Host.
Payout: Pago del comercio al cliente. No confundir con devoluciones.

Estas operativas están disponibles según la integración:

Operativa	Hosted	Host2Host	JavaScript
Autorización	Sí	Sí	Sí
Anulación (total)	No	Sí	No
Devolución (parcial y total)	No	Sí (circuito cerrado)	No
PayByLink	No	Sí	No
Payout	Sí (circuito cerrado)	Sí (circuito cerrado)	Sí (circuito cerrado)

Flujo de la transacción

A continuación, tienes un diagrama que ilustra el flujo que sigue una transacción de autorización PayByBank. Más abajo, tienes una explicación detallada de cada punto.

Este es el flujo que sigue una transacción de pago realizada con PayByBank:

1. El cliente rellena los datos de pago.

2. El comercio crea la petición.

3. El comercio encripta, cifra y firma la petición.

4. El comercio envía la petición a Addon Payments.

5. Si la petición está correctamente formada, Addon Payments devuelve al comercio una notificación con la URL de PayByBank y el estado de la transacción pasa a “REDIRECTED”.

6. El comercio redirige al cliente a la URL de PayByBank (Truelayer) recibida.

7. Cuando el cliente accede a la URL, Addon Payments envía una notificación indicando el estado “AWAITING_PAYSOL” de la transacción.

8. El cliente realiza la transacción en el link recibido.

9. Addon Payments procesa la transacción de la solución de pago PayByBank.

10. Si la transacción no es autorizada, Addon Payments devuelve al comercio una notificación con el estado “ERROR”, y se redirige al cliente a la URL de ERROR que se haya indicado en la petición inicial.

11a. Si la transacción es autorizada y tu comercio opera con open loop, Addon Payments devuelve al comercio una notificación con el estado “SUCCESS”, y se redirige al cliente a la URL de SUCCESS que se haya indicado en la petición inicial.

11b. Si la transacción es autorizada y tu comercio opera con close loop, Addon Payments devuelve al comercio una notificación con el estado “SUCCESS_WARNING”, y se redirige al cliente a la URL de AWAITING que se haya indicado en la transacción original.

12. Si tu comercio opera con close loop, Addon Payments liquida la transacción.

13. Si tu comercio opera con close loop, después de liquidar la transacción, Addon Payments enviará a tu comercio una notificación con el estado “SUCCESS”, y se redirige al cliente a la URL de SUCCESS que se haya indicado en la petición inicial.

Requisitos para usar PayByBank

En esta sección tienes los requisitos que deben cumplir los clientes y comercios para poder usar PayByBank en tu comercio con Addon Payments.

Requisitos para clientes

Para poder usar PayByBank, los clientes deben:

Disponer de una cuenta bancaria en alguno de los bancos disponibles en la plataforma Truelayer.
Disponer de acceso online a dicha cuenta bancaria.

Requisitos para comercios

A continuación, tienes los requisitos previos que debe cumplir tu comercio para integrar PayByBank.

Crear una cuenta y aplicación para tu comercio Truelayer

Para integrar PayByBank en Addon Payments debes crearle una cuenta a tu comercio en Truelayer.

1. Accede a esta página y crea una cuenta para tu comercio. Debes rellenar los datos de tu comercio para crear tu cuenta.

2. Cuando hayas creado la cuenta, debes crear una «aplicación» en Truelayer.

3. Introduce un nombre para la aplicación. Puedes modificar el client_id que sirve para identificar la aplicación.

4. Confirma los valores y haz clic en «Create application».

5. Se mostrará una ventana con el nombre de la aplicación creada, el identificador de cliente y la clave secreta.

6. Pulsa el botón «Get started». Ya deberías tener acceso a tu cuenta.

La cuenta recién creada está limitada al entorno de pruebas de Truelayer. Cuando las pruebas de integración de PayByBank hayan finalizado, solicita el alta a producción a Truelayer.

Si tienes dudas con el alta, acceso a la consola o cualquier otra consulta, contacta con el servicio técnico de Truelayer.

Obtener los datos de tu cuenta en Truelayer y configurar las URLs de retorno de AP

1. Accede al panel de gestión de tu comercio en Truelayer.

2. Accede a la aplicación creada pulsando en el botón «Apps» del menú izquierdo.

3. Accede a la sección de configuración de la aplicación pulsando en «Settings», en la parte superior.

4. Obtén y guarda estos datos de la sección «Identifiers».

Identificador de cliente (Client Id.).
Clave secreta (Client secret).

5. Elimina las URLs que vienen predefinidas y añade las URLs de retorno de Addon Payments como URLs de redirección autorizadas en la plataforma de Truelayer. En la sección «Allowed redirect URIs», haz clic en el botón más «+» y añade:

Entorno	URL
Staging	https://checkout.stg-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
Staging	https://checkout.stg-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
Producción	https://checkout.prd-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
	https://checkout.prd-eu-west1-d.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
	https://checkout.prd-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
	https://checkout.prd-eu-west3-c.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank

Nota: Recuerda que las URLs de entorno de producción no se podrán introducir hasta que tu comercio no esté dado de alta en el entorno de producción.

Generar una clave de cifrado para Truelayer, subirlo y configurar las URLs de notificación de AP

1. Genera un par de claves de cifrado, pública y privada, para tu comercio en Truelayer.

2. El proceso está detallado en esta guía de Truelayer. Al finalizar el proceso de la guía obtendrás una clave pública y otra privada en archivos de texto .pem.

3. Accede al panel de gestión de tu comercio en Truelayer.

4. Accede a la aplicación creada pulsando en el botón «Apps» del menú izquierdo.

5. Accede a la sección de configuración de la aplicación pulsando en «Settings», en la parte superior.

6. Localiza la sección «Payment Settings» para subir la clave de firma pública. Pulsa el botón «Upload signing key».

7. Se abrirá una ventana donde podrás subir el achivo .pem con la clave pública. Si el archivo es correcto aparecerá en el listado de claves de firmas.

8. Despliega la información de la clave para obtener el Key identificator (KID), necesario posteriormente. Guarda el KID.

9. En la sección «Webhook URI» introduce la siguiente URL:

Entorno	URL
Staging	https://checkout-stg.easypaymentgateway.com/EPGCheckout/callback/callbackPayByBank/paysol/paybybank
Producción	https://checkout.easypaymentgateway.com/EPGCheckout/callback/callbackPayByBank/paysol/paybybank

Nota: Recuerda que las URLs de entorno de producción no se podrán introducir hasta que tu comercio no esté dado de alta en el entorno de producción.

Elige entre operar por circuito abierto o cerrado

Elige la operativa: circuito abierto o circuito cerrado. Consulta los detalles en la Introducción.

Si operas en circuito abierto, no es necesaria ninguna acción más en la consola de Truelayer.
Si operas en circuito cerrado, para el entorno de producción necesitas crear una cuenta para fondos en el panel de gestión de Truelayer, en la cual se depositarán los fondos de los pagos recibidos, en espera de su retirada manual o automática.
- En el entorno de pruebas, dispones de dos cuentas para pruebas en la sección «Merchant Account» del apartado «Payments». Una cuenta está en Euros y la otra en GBP.
- Todas las cuentas de fondos tienen un identificador único que podrás consultar y que deberás facilitar a Soporte.
- Para consultar ese identificador: Pulsa «Apps» en el menú izquierdo y luego «Merchant Account». Selecciona la cuenta que quieras consultar. Luego, en la parte inferior la pestaña «Details», el campo «ID».

Solicitar configuración de la solución de pago

Como paso final antes de empezar a integrar la solución PayByBank, debes solicitar al equipo de Soporte de Addon Payments la activación y configuración de PBB en tu TPV Virtual.

Para ello necesitamos todos estos datos que puedes obtener del panel de gestión de Truelayer.

Identificador de cliente (Client Id.).
Clave secreta (Client secret).
KID (Identificador de la clave pública de cifrado).
Archivo .pem con la clave privada de cifrado.

Si operas por circuito cerrado:

Identificador de la cuenta bancaria que has creado para tu comercio en la plataforma de Truelayer.

Si operas por circuito abierto:

IBAN de la cuenta bancaria de tu comercio ajena a la plataforma de Truelayer.
Nombre completo del beneficiario de dicha cuenta bancaria.

Entornos y endpoints: Staging y Producción

Addon Payments cuenta con dos (2) entornos operativos independientes:

Entorno de Staging:

Es el primer entorno con el cual entrarás en contacto.
Puedes hacer pruebas con las credenciales de la sección anterior.
Esto te permite comprobar la correcta gestión de las diferentes casuísticas por parte de tu integración.
Las tarjetas y cuentas reales no funcionan.

Entorno de Producción:

Es el entorno en el cual las transacciones tienen efectos contables.
Únicamente se puede transaccionar con tarjetas y cuentas reales y operativas.

A continuación, tienes los endpoints según el tipo de integración:

Entorno	Hosted	Host2Host
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay
Producción	https://checkout.addonpayments.com/EPGCheckout/rest/online/tokenize	https://checkout.addonpayments.com/EPGCheckout/rest/online/pay

Petición	Entorno	URL
Petición /auth	Staging	https://epgjs-mep-stg.addonpayments.com/auth
Petición /charge	Staging	https://epgjs-mep-stg.addonpayments.com/charge/v2
Petición /auth	Producción	https://epgjs-mep.addonpayments.com/auth
Petición /charge	Producción	https://epgjs-mep.addonpayments.com/charge/v2

Datos requeridos y opcionales PayByBank

A continuación tienes una tabla con los parámetros requeridos para mandar una petición con PayByBank. Estos datos son comunes en los 3 tipos de integración: Hosted, Host2Host y JavaScript. El tipo indica que el parámetro es requerido/obligatorio (R).

Campo	Formato	Tipo	Descripción	Ejemplo
merchantId	Numérico entero 4~7 dígitos	R	Es el indicador de tu comercio en la plataforma de AP. Es facilitado por Soporte en el correo de bienvenida, es común para los dos entornos	14983
merchantTransactionId	Alfanumérico Máx. 18 caracteres Sin caracteres especiales (acentos, signos de puntuación, etc.) Sin nº duplicados	R	Es el identificador único de la transacción del comercio. Sirve para que tu plataforma enlace las notificaciones recibidas con el pedido del cliente.	pedido_91684
productId	Numérico entero Máximo 20 caracteres	R	Identificador del producto creado en tu comercio en AP. Es facilitado en el correo de bienvenida.	149830
operationType	Alfanumérico Máx. 45 caracteres	R	Especifica el tipo de operación a realizar. Valores admitidos: – debit (por defecto): Transacción de pago. Es decir, el efectivo viaja desde la cuenta del cliente al comercio. – credit: Transacción de ingreso en cuenta del cliente. Es decir, el efectivo viaja desde el comercio hasta la cuenta del cliente. Por ejemplo, en el pago de un premio. No confundir con las devoluciones. Estas tienen su propio tipo de transacción.	debit
customerId	Alfanumérico Máx. 80 caracteres	R	Id. del cliente en tu plataforma de comercio electrónico.	A34623
amount	Numérico decimal 0~1000000.00	R	Importe de la transacción. Si el importe tiene decimales, el separador es un punto (.). No se puede incluir el separador en los millares	50.5
currency	Alfabético – EUR – GBP	R	Divisa de la transacción. Limitada a EUR y GBP.	EUR
country	Alfabético 2 caracteres ISO 3166-1 alfa-2 Países de la UE y Reino Unido	R	País desde el que se envía la transacción	ES
firstName	Alfabético Máximo 50 caracteres	R	Nombre del cliente. Si tiene más de uno se separan con espacios.	Pablo
lastName	Alfabético Máximo 50 caracteres	R	Apellido(s) del cliente. Si tiene más de uno se separan con espacios.	Ferrer
telephone	Numérico Máximo 45 caracteres	R (opcional si se envía el customerEmail)	Número de teléfono. Con el prefijo del país. Es requerido «telephone» o «customerEmail», puedes elegir cuál.	+34600600600
customerEmail	Alfanumérico Máximo 100 caracteres	R (opcional si se envía el telephone)	Correo electrónico del cliente. Es requerido «telephone» o «customerEmail», puedes elegir cuál.	correo@mail.com
customerCountry	Código ISO 3166-2	R	País del cliente.	ES
addressLine1	Alfanumérico Máximo 50 caracteres	R	Dirección del cliente.	Calle canales 2
postCode	Alfanumérico Máximo 16 caracteres	R	Código postal de la dirección del cliente.	08003
city	Alfabético Máximo 50 caracteres	R	Ciudad del cliente	Barcelona
statusURL	Alfanumérico (caracteres permitidos en URL) Máx. 2048 caracteres	R	URL de tu plataforma de comercio electrónico donde AP enviará la notificación con el estado de la transacción. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.	https://www.example.com/status
successURL	Alfanumérico (caracteres permitidos en URL) Máx. 2048 caracteres	R	URL de tu plataforma a la que se redirecciona al cliente si la transacción es autorizada. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.	https://www.example.com/success
errorURL	Alfanumérico (caracteres permitidos en URL) Máx. 2048 caracteres	R	URL de tu plataforma a la que se redirecciona al cliente si la transacción es denegada. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.	https://www.example.com/error
cancelURL	Alfanumérico (caracteres permitidos en URL) Máx. 2048 caracteres	R	URL de tu plataforma a la que se redirecciona el cliente si cancela la transacción durante el proceso de pago. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.	https://www.example.com/cancel
awaitingURL	Alfanumérico (caracteres permitidos en URL) Máx. 2048 caracteres	R	URL de tu plataforma a la que se redirecciona el cliente si la transacción está pendiente de procesar. Si se envía en la petición, tendrá prioridad sobre la configurada en el Portal BackOffice de Addon Payments. Si no se envía en la petición, se redirigirá al cliente a la URL configurada en el módulo de administración.	https://www.example.com/awaiting
paymentSolution	Alfanumérico Máx. 45 caracteres	O	Nombre de la solución de pago por la cual debe procesarse la transacción. IMPORTANTE: Si quieres que se muestren todas las soluciones de pago que tengas disponibles, NO envíes este parámetro.	PayByBank
addressLine2	Alfanumérico Máx. 50 caracteres	O	Dirección del cliente. Es opcional, por si no cabe completa en el addressLine1.	Calle Ramos 23
dob	Alfanumérico Máximo 10 caracteres. AAAA-MM-DD	O	Fecha de nacimiento del cliente	1999-12-31
state	Alfanumérico Máx. 50 caracteres	O	Provincia o estado de la dirección del cliente.	Barcelona
merchantParams	Alfanumérico Máximo 500 caracteres campo1:valor1;campo2:valor2;campoN:valorN	O	Parámetro donde se envían detalles extra de la operativa, como en PayByLink. Más detalles en la sección concreta.	N/A
bankCountry	Formato ISO 3166-2 2 caracteres	O	País del banco de la cuenta bancaria del cliente. Cuando este campo esta vacío, aparecerá un desplegable con los países disponibles. Si este parámetro marca un país, se marcará por defecto el país indicado y el desplegable no se mostrará.	ES
bankHolder	Alfabético Máximo 70 caracteres	O	Nombre y apellido/s del titular de la cuenta bancaria del cliente. Se separan con espacios.	Pablo Ferrer
bankAccountType	Valores admitidos: – iban – sort_code_account_number	O	Tipo de cuenta bancaria del cliente. Depende del valor que envíes, tendrás que enviar también «bankIban» o «bankCode» y «bankAccountNum».	iban
bankIban	Alfanumérico Máximo 30 dígitos	O (enviar si «bankAccountType: iban»)	Código bancario IBAN de la cuenta del cliente.	ES1212341234121234567890
bankCode	Numérico de 6 dígitos	O (enviar si «bankAccountType: sort_code_account_number)	Código bancario de la cuenta del cliente.	123456
bankAccountNum	Numérico de 8 dígitos	O (enviar si «bankAccountType: sort_code_account_number)	Número de cuenta del cliente.	12345678

Integración Host2Host

Con Addon Payments puedes usar la solución de pago PayByBank con tu integración Host2Host. Te recomendamos que visites la documentación Host2Host para conocer más detalles sobre este tipo de integración.

Autorización

La autorización es una operación de pago del cliente al comercio. La captura del importe es automática. Envía la petición al endpoint Host2Host correspondiente.

Petición

Recuerda que las peticiones enviadas a Addon Payments deben ser cifradas. Visita nuestra sección de Cifrado, firma y envío de la petición para más información.

Estos son unos ejemplos de autorización mediante PayByBank por Host2Host. Recuerda que la petición en cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&productId=14983&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&operationType=debit&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+R+63D5+NT/FQzI0Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInomL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Parámetros de la solicitud de autorización

Consulta los parámetros a enviar en una autorización PayByBank vía Host2Host en la tabla de parámetros comunes.

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Este es un ejemplo de la respuesta recibida a una petición de autorización PayByBank:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228214</message>
    <operations>
        <operation sorted-order="1">
            <amount>10</amount>
            <currency>EUR</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"895883e0-b972-4480-a0f3-215a8db8606c","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","metadata":{"txnId":"228214","operationType":"Payin"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T06:39:32.673Z","payment_source":{"id":"671a41aa-3196-48fd-8b88-ed23fe8e978d","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"40097f84-d022-4f94-928c-d47ba5552c6a"}</details>
            <merchantTransactionId>0606001</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>9374a22a-3281-491d-8e5e-ee7c080601ef</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228214</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>8bcac545_9f4d_43f7_a28b_82e5b8ee35ca</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Anulación

En Addon Payments puedes anular (cancelar) el importe de una transacción PayByBank en favor del cliente. Para ello, la operación debe cumplir unos requisitos:

La operación NO puede ser un PayByLink.
La operación a anular debe tener el estado «REDIRECTED».

Puedes anular operaciones mediante:

El portal BackOffice.
Mediante petición, como veremos a continuación.

Estos son los endpoints donde se envían las peticiones de anulación:

Entorno	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/void
Producción	https://checkout.addonpayments.com/EPGCheckout/rest/online/void

Petición

Recuerda que las peticiones enviadas a Addon Payments deben ser cifradas. Visita nuestra sección de Cifrado, firma y envío de la petición para más información.

Estos son unos ejemplos de petición de anulación de una transacción PayByBank por Host2Host. Recuerda que la petición en cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=27258897&paymentSolution=paybybank&transactionId=7556056

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/void' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: Z7VA6TpG9B84X9x9qqXoWQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="4xUYxJxLc/ABCyqJfwcLTAURzz4IiJ26kBlQpYVnedKEVhevNJNZ88z6m50W2THtDR70pQq6qjF37NCfOeq/UDCg0RB/MPfYUJRUIsfPk=' \
--form 'integrityCheck="1c256f5b834e5db6d5f453043a8a3830859b308f297cc2cf423064510c5c9b72"'

Parámetros de la solicitud de anulación

Estos son los parámetros a enviar para una petición de anulación de una transacción PayByBank. La columna tipo indica si el elemento es Requerido/Obligatorio (R) u Opcional (O).

Campo	Formato	Tipo	Descripción	Ejemplo
merchantId	Numérico entero 4~7 dígitos	R	Es el indicador de tu comercio en la plataforma de AP. Es facilitado por Soporte en el correo de bienvenida, es común para los dos entornos	14983
transactionId	Numérico entero Máx. 100 dígitos	R	Identificador de la transacción original sobre la cual va a realizarse una operación secundaria, como captura, liberación o devolución.	76543210
paymentSolution	Alfanumérico Máx. 45 caracteres	R	Nombre de la solución de pago por la cual ha sido procesada la transacción inicial. Se indica en la respuesta de la transacción original.	paybybank
merchantTransactionId	Alfanumérico Máx. 18 caracteres Sin caracteres especiales (acentos, signos de puntuación, etc.) Sin nº duplicados	R	Identificador de la transacción en tu plataforma de comercio electrónico. Sirve para que tu plataforma enlace las notificaciones recibidas con el pedido del cliente. No puede repetirse entre transacciones.	pedido_91684
description	Máx. 1000 caracteres Página de códigos Latin-1 (ISO-8859-1)	O	Descripción de la transacción. Se guarda en los detalles de la transacción y se devuelve en la notificación. No afecta a la transacción, sirve para que puedas realizar una mejor identificación.	Anulación después de probar producto

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Este es un ejemplo de la respuesta recibida a una petición de anulación de una operación PayByBank:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228298</message>
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payment_failed","event_version":1,"event_id":"565218dd-767c-4313-a907-1c65faa2b2ef","payment_id":"4519ec74-193a-4005-8539-6ed6703337ae","metadata":{"txnId":"228297","operationType":"Payin"},"payment_method":{"type":"bank_transfer"},"failed_at":"2024-06-09T14:58:13.923Z","failure_stage":"authorizing","failure_reason":"canceled"}</details>
            <merchantTransactionId>0806105</merchantTransactionId>
            <message>Payment operation fail on stage: authorizing. Failure reason: canceled</message>
            <operationType>DEBIT</operationType>
            <paySolTransactionId>4519ec74-193a-4005-8539-6ed6703337ae</paySolTransactionId>
            <paymentDetails>
                <extraDetails/>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>CANCELLED</status>
            <transactionId>228297</transactionId>
            <respCode>
                <code>1542</code>
                <message>Transaction was manually cancelled or declined by the merchant</message>
                <uuid>67073f7b_c157_40a3_8e64_5a918133df13</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
</response>

Devoluciones

Puedes realizar devoluciones parciales o totales del importe de una operación PayByBank, siempre que al operación esté autorizada y liquidada y operes por circuito cerrado. Puedes realizar devoluciones mediante:

El portal BackOffice.
El panel de gestión de Truelayer.
Mediante petición.

Devolución mediante el panel de gestión de Truelayer

Para hacer una devolución total o parcial en el panel de gestión de Truelayer sigue estos pasos:

En el menú izquierdo clica en «Payments», después en «Payments».
Verás una lista de las operaciones de tu comercio. Encuentra y haz clic en la operación que quieras devolver.
Se abrirá un desplegable con detalles de la transacción. Haz clic en «Authenticate & refund payment», de la sección Refunds.
Tendrás que autenticarte, ya sea con un código de un solo uso u otros métodos.
Cuando te hayas autenticado, se abrirá una ventana con los detalles de la devolución.
Introduce la cantidad de la devolución, total o parcial, en el campo «Amount».
Cuando la devolución se complete con éxito, en la lista de transacciones se creará una nueva operación de devolución que se referirá al ID del pago original.

Devolución mediante petición

Estos son los endpoints donde se envían las peticiones de devolución.

Entorno	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate
Producción	https://checkout.addonpayments.com/EPGCheckout/rest/online/rebate

Petición

Recuerda que las peticiones enviadas a Addon Payments deben ser cifradas. Visita nuestra sección de Cifrado, firma y envío de la petición para más información.

Estos son unos ejemplos de petición de devolución de una transacción PayByBank por Host2Host. Recuerda que la petición en cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=61565574&amount=5&paymentSolution=paybybank&transactionId=7556056

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: Z7VA6TpG9B84X9x9qqXoWQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="4xUYxJxLc/ABCyqJfwttTalkds3YeijsJe6MlTnC6mgmbm0aXKq6qjF37NCfOeq/UDCg0RB/MPfYUJRUIsfPk=' \
--form 'integrityCheck="1c256f5b834e5db6d5f453043a8a3830859b308f297cc2cf423064510c5c9b72"'

Parámetros de la solicitud de devolución

Estos son los parámetros a enviar para una petición de devolución de una transacción PayByBank. La columna tipo indica si el elemento es Requerido/Obligatorio (R) u Opcional (O).

Campo	Formato	Tipo	Descripción	Ejemplo
merchantId	Numérico entero 4~7 dígitos	R	Es el indicador de tu comercio en la plataforma de AP. Es facilitado por Soporte en el correo de bienvenida, es común para los dos entornos	14983
transactionId	Numérico entero Máx. 100 dígitos	R	Identificador de la transacción original sobre la cual va a realizarse una operación secundaria, como captura, liberación o devolución.	76543210
paymentSolution	Alfanumérico Máx. 45 caracteres	R	Nombre de la solución de pago por la cual ha sido procesada la transacción inicial. Se indica en la respuesta de la transacción original.	paybybank
amount	Numérico decimal 0~1000000.00	R	Importe de la devolución. Si es menor al total, la devolución será parcial. Si el importe contiene decimales, debe usar el punto (.) como separador No se puede incluir separador de millares.	10.50
merchantTransactionId	Alfanumérico Máx. 18 caracteres Sin caracteres especiales (acentos, signos de puntuación, etc.) Sin nº duplicados	R	Identificador de la transacción en tu plataforma de comercio electrónico. Sirve para que tu plataforma enlace las notificaciones recibidas con el pedido del cliente. No puede repetirse entre transacciones.	pedido_91684
description	Máx. 1000 caracteres Página de códigos Latin-1 (ISO-8859-1)	O	Descripción de la transacción. Se guarda en los detalles de la transacción y se devuelve en la notificación. No afecta a la transacción, sirve para que puedas realizar una mejor identificación.	Devolución después de retorno

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Este es un ejemplo de notificación de una devolución de una operación de PayByBank. Esta es la notificación final, que indica que ha sido exitosa. Previamente, pasa por otro estado de validación con status: «AWAITING_PAYSOL».

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228219</message>
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>GBP</currency>
            <details>{"type":"refund_executed","event_version":1,"event_id":"e3f4afba-dc64-ac52-63f8-11e21ac87790","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","executed_at":"2024-06-06T06:53:31.293Z","refund_id":"5469f084-a74e-4bb7-bd76-37c44d68c5d0"}</details>
            <merchantTransactionId>0606005</merchantTransactionId>
            <message>PayByBank refund has been successfully executed.</message>
            <operationType>REFUND</operationType>
            <payFrexTransactionId>228219</payFrexTransactionId>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>69443</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</payfrex-response>

PayByLink (enlace de pago)

PayByLink (PBL) es una operativa mediante la que se genera un enlace de pago que se envía al cliente. Con PayByBank, tu comercio puede usar estos enlaces de pago.

Este es un diagrama del flujo de una transacción de PayByLink con PayByBank. Debajo, tienes una explicación detallada de cada punto.

1. El comercio crea la petición.

2. El comercio encripta, cifra y firma la petición.

3. El comercio envía la petición a Addon Payments.

4. Addon Payments procesa la transacción.

5a. Si la petición no está correctamente formada, Addon Payments devuelve al comercio una notificación con el estado de la transacción “ERROR”.

5b Si la petición está correctamente formada, Addon Payments devuelve al comercio una notificación con la URL de pago y el estado de la transacción pasa a “PENDING_CONFIRMATION”.

6. El comercio envía al cliente el link de pago recibido.

7. El cliente abre el link.

8a. Si el link está caducado, Addon Payments envía al comercio una notificación con el estado “CANCELLED”.

8b. Si el link es correcto, Addon Payments devuelve al comercio una notificación con el estado “AWAITING_PAYSOL”, y se redirige al cliente a PayByBank (Truelayer) para que siga el proceso.

9. El cliente paga en el link.

10. Addon Payments procesa la transacción de la solución de pago PayByBank.

11. Si la transacción no es autorizada o el cliente abandona el proceso, Addon Payments devuelve al comercio una notificación con el estado “AWAITING_PAYSOL”.

12a. Si la transacción es autorizada y tu comercio opera con open loop, Addon Payments devuelve al comercio una notificación con el estado “SUCCESS”, y se redirige al cliente a la URL de SUCCESS que se haya indicado en la petición inicial.

12b. Si la transacción es autorizada y tu comercio opera con close loop, Addon Payments devuelve al comercio una notificación con el estado “SUCCESS_WARNING”, y se redirige al cliente a la URL de AWAITING que se haya indicado en la petición original.

13. Si tu comercio opera con close loop, Addon Payments liquida la transacción

14. Si tu comercio opera con close loop, después de liquidar la transacción, Addon Payments enviará a tu comercio una notificación con el estado “SUCCESS”, y se redirige al cliente a la URL de SUCCESS que se haya indicado en la petición inicial.

Petición

Recuerda que las peticiones enviadas a Addon Payments deben ser cifradas. Visita nuestra sección de Cifrado, firma y envío de la petición para más información.

Estos son unos ejemplos de petición de PayByLink en PayByBank por Host2Host. Recuerda que la petición en cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&operationType=debit&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php
&state=barcelona&merchantParams=payByLink:true

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+R+63D5+NT/FQzI0Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInomL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Parámetros de la solicitud PayByLink

A continuación, tienes una tabla con los datos requeridos para PayByLink a través de PayByBank.

Además de los datos de esta tabla, debes enviar los requeridos de la tabla general. El tipo indica si el campo es requerido/obligatorio (R) u opcional (O):

Campo	Formato	Tipo	Descripción	Ejemplo
state	Alfanumérico Máx. 50 caracteres	R	Provincia o estado de la dirección del cliente.	Barcelona
merchantParams	Alfanumérico Máximo 500 caracteres campo1:valor1;campo2:valor2;campoN:valorN	R	Parámetros extra de la petición. Para operar con PayByLink es requerido enviar lo siguiente en este campo «payByLink:true». También se pueden incluir otros parámetros, como la fecha de caducidad del enlace.	merchantParams=payByLink:true
− payByLink	Booleano – true – false	R	Indica si la operativa es PayByLink.	true
− pblExpirationUnit	Valores admitidos: – minutes – hours	O	Unidad (horas o minutos) en la que se va a medir la caducidad. Este valor se impone frente al configurado en el BackOffice. Si no se envía este valor y no está configurado por defecto, la caducidad del link de pago es de 24 horas.	minutes
− pblExpirationValue	Numérico entero positivo	O	Cantidad de unidades (horas o minutos) hasta que el enlace caduque. Este valor se impone frente al configurado en el BackOffice. Si no se envía este valor y no está configurado por defecto, la caducidad del link de pago es de 24 horas.	15
paysolExtendedData	Formato JSON sin tamaño máximo	O	Objeto JSON para incluir información extra requerida por algunas soluciones de pago. En PayByLink, se puede enviar par mostrar el carrito al cliente en la pasarela de pago. En el desplegable inferior tienes los campos y cómo formar el JSON.	N/A

Algunas consideraciones a tener en cuenta en PayByLink:

La caducidad de los enlaces es de 24 horas por defecto. Se puede modificar en el BackOffice o en las peticiones. La caducidad indicada en la petición tiene prioridad frente a la configurada en el BackOffice.
Puedes solicitar a Soporte el cambio de la caducidad por defecto en todos los enlaces en el BackOffice.
No hay caducidad máxima de enlaces, la mínima es de 1 minuto.
A continuación, tienes un ejemplo de como formar el JSON del paysolExtendedData y sus campos:

JSON del paysolExtendedData

				
					{
    "product_items": [
        {
            "name": "Producto 1", //nombre del producto
            "price": 5, //precio del producto
            "quantity": 1, //cantidad de producto
            "url": "https://micomercio.com/producto1" //url de tu comercio del producto
        },
        {
            "name": "Producto 2",
            "price": 2.5,
            "quantity": 2,
            "url": "https://micomercio.com/producto2"
        }
    ]
}

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Estos son unos ejemplos de las notificaciones recibidas a una petición de PayByLink. En primer lugar, recibirás una notificación con el enlace de pago que debes enviar al cliente. Cuando el cliente haga clic, recibirás otra notificación. Por último, recibirás una notificación con el estado de la operación.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228284</message>
    <operations>
        <operation sorted-order="1">
            <amount>5</amount>
            <currency>GBP</currency>
            <details>{"id":"jTfUD3fguG8","uri":"https://payment.truelayer-sandbox.com/links/jTfUD3fguG8"}</details>
            <merchantTransactionId>0606306</merchantTransactionId>
            <message>PayByBank PayByLink uri successfully created.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>jTfUD3fguG8</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>uri</key>
                        <value>https://payment.truelayer-sandbox.com/links/jTfUD3fguG8lt;</value>
                    </entry>
                    <entry>
                        <key>id</key>
                        <value>jTfUD3fguG8</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>PENDING_CONFIRMATION</status>
            <transactionId>228284</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>3eb6e394_21a2_49c7_a124_113d3d3ce77c</uuid>
            </respCode>
        </operation>
    </operations>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228284</message>
    <operations>
        <operation sorted-order="1">
            <amount>5.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payment_link_payment_created","event_version":1,"event_id":"986ab71a-847f-4fa3-b417-4f88c2aed9b2","payment_link_id":"jTfUD3fguG8","payment":{"id":"4fd99d1c-845b-450b-99fc-783e5e73e676","created_at":"2024-06-06T17:30:13.732Z"}}</details>
            <merchantTransactionId>0606306</merchantTransactionId>
            <message>PayByBank PayByLink payment successfully initiated. Waiting for Truelayer's response.</message>
            <operationType>DEBIT</operationType>
            <paymentSolution>paybybank</paymentSolution>
            <status>AWAITING_PAYSOL</status>
            <transactionId>228284</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>354d82bc_61b7_4b89_af82_24b1ea3f0529</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>AWAITING_PAYSOL</status>
    <workFlowResponse>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228284</message>
    <operations>
        <operation sorted-order="1">
            <amount>5.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"da83166d-caa8-4d40-bae9-f97ad01fe342","payment_id":"4fd99d1c-845b-450b-99fc-783e5e73e676","metadata":{"txnId":"228284","operationType":"payByLink"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T17:30:35.45Z","payment_source":{"id":"b277e24b-7b18-4e22-9d98-c47a43bd5faa","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"16de2aa3-ec88-4f09-bd35-7b7d2794a289"}</details>
            <merchantTransactionId>0606306</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228284</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>354d82bc_61b7_4b89_af82_24b1ea3f0529</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Payout

Los Payouts son una operativa de pagos del comercio a la cuenta del cliente. No confundir con devoluciones. El objetivo de esta operativa es el pago de premios, por ejemplo. Debes solicitar esta operativa a Soporte para su activación.

Puedes operar con Payouts en PayByBank en cualquiera de las 3 integraciones por CIRCUITO CERRADO con los mismos parámetros que en este ejemplo, que será con Host2Host. La petición es muy parecida a la de una autorización normal, pero con «operationType: credit».

Payout según cuenta de cliente

Los parámetros a enviar en el Payout cambian según el cliente tenga cuenta en Truelayer o no:

Cliente con cuenta en Truelayer, este Payout será por circuito cerrado.
Cliente con cuenta bancaria ajena a Truelayer, este Payout será por circuito abierto y tendrás que añadir algunos parámetros.

Importante: Independientemente de que el cliente tenga la cuenta en Truelayer o ajena, el comercio debe tener la cuenta en Truelayer y operar por circuito cerrado para hacer Payouts.

Payout según flujo

El tipo de Payout también depende del flujo que tenga activo tu comercio, no se puede elegir el tipo de Payout (directo o en 2 pasos) con los parámetros de la petición. Existen 2 tipos de Payouts:

Payout directo: El cliente recibe el importe cuando la petición se completa con éxito.
Payout en 2 fases: El cliente inicia el proceso del Payout pero este queda pendiente de ser aprobado o rechazado por el comercio.

Además, por seguridad, para realizar un Payout debe existir un pago autorizado previo (del cliente al comercio). El Payout se realizará con la misma solución de pago y a la misma tarjeta con la que se hizo el pago previo. Sin embargo, hay excepciones donde se puede realizar un Payout sin depósito previo, según la naturaleza del comercio.

Debes solicitar la operativa de Payout a Soporte para su activación.

Requisitos para los Payouts en PayByBank

Debes añadir las URLs del servicio AIS a las URLs de retorno autorizadas en la plataforma de Truelayer. Sigue este proceso y añade las siguientes URLs:

Entorno	URL
Staging	https://checkout.stg-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
Staging	https://checkout.stg-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
Producción	https://checkout.prd-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
	https://checkout.prd-eu-west1-d.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
	https://checkout.prd-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
	https://checkout.prd-eu-west3-c.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais

Petición

Recuerda que las peticiones enviadas a Addon Payments deben ser cifradas. Visita nuestra sección de Cifrado, firma y envío de la petición para más información.

Estos son unos ejemplos de petición de Payout en PayByBank por circuito cerrado vía Host2Host. Recuerda que la petición en cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10&currency
=EUR&country=ES&customerId=000001&productId=123450001&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php
&successURL=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko.php
&cancelURL=https://micomercio.com/url-cancelacion.php&awaitingURL=https://micomercio.com/url-espera.php
&operationType=credit&dob=1990-01-01

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+R+63D5+NT/FQzI0Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInomL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Parámetros de la solicitud de Payout Paybybank

Los parámetros requeridos (R) para una petición de Payout en PayByBank son los de esta tabla.

Dependiendo de si operas por circuito cerrado o abierto, deberás añadir/modificar algunos datos, como ves en las siguientes secciones:

Circuito cerrado

Estos son los parámetros a añadir/modificar para peticiones de Payout por circuito cerrado:

Campo	Formato	Tipo	Descripción	Ejemplo
operationType	Alfanumérico Máx. 45 caracteres	R	Especifica el tipo de operación a realizar. Valores admitidos: – debit. – credit: Transacción de ingreso en cuenta del cliente. Es decir, el efectivo viaja desde el comercio hasta la cuenta del cliente. Por ejemplo, en el pago de un premio. No confundir con las devoluciones. Estas tienen su propio tipo de transacción.	credit
dob	Alfanumérico Máximo 10 caracteres. AAAA-MM-DD	R	Fecha de nacimiento del cliente.	1999-12-31

Circuito abierto

Estos son los parámetros a añadir/modificar para peticiones de Payout por circuito abierto:

Campo	Formato	Tipo	Descripción	Ejemplo
operationType	Alfanumérico Máx. 45 caracteres	R	Especifica el tipo de operación a realizar. Valores admitidos: – debit. – credit: Transacción de ingreso en cuenta del cliente. Es decir, el efectivo viaja desde el comercio hasta la cuenta del cliente. Por ejemplo, en el pago de un premio. No confundir con las devoluciones. Estas tienen su propio tipo de transacción.	credit
dob	Alfanumérico Máximo 10 caracteres. AAAA-MM-DD	R	Fecha de nacimiento del cliente.	1999-12-31
bankCountry	Formato ISO 3166-2 2 caracteres	R	País del banco de la cuenta bancaria del cliente. Cuando este campo esta vacío, aparecerá un desplegable con los países disponibles. Si este parámetro marca un país, se marcará por defecto el país indicado y el desplegable no se mostrará.	ES
bankHolder	Alfabético Máximo 70 caracteres	R	Nombre y apellido/s del titular de la cuenta bancaria del cliente. Se separan con espacios.	Pablo Ferrer
bankAccountType	Valores admitidos: – iban – sort_code_account_number	R	Tipo de cuenta bancaria del cliente. Depende del valor que envíes, tendrás que enviar también «bankIban» o «bankCode» y «bankAccountNum».	iban
bankIban	Alfanumérico Máximo 30 dígitos	R (si «bankAccountType: iban»)	Código bancario IBAN de la cuenta del cliente.	ES1212341234121234567890
bankCode	Numérico de 6 dígitos	R (si «bankAccountType: sort_code_account_number)	Código bancario de la cuenta del cliente.	123456
bankAccountNum	Numérico de 8 dígitos	R (si «bankAccountType: sort_code_account_number)	Número de cuenta del cliente.	12345678

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Este es un ejemplo de la notificación que obtienes de una transacción Payout:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228220</message>
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payout_executed","event_version":1,"event_id":"b4a6b795-c03d-e52b-405b-c895832fd743","metadata":{"operationType":"Payout","txnId":"228220"},"executed_at":"2024-06-06T07:30:34.107Z","payout_id":"19b3eb94-5837-4340-bd50-fa42bf259647","beneficiary":{"type":"external_account"}}</details>
            <merchantTransactionId>0606006</merchantTransactionId>
            <message>PayByBank payout has been successfully executed.</message>
            <operationType>CREDIT</operationType>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228220</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>b1cc4210_b008_4ed9_8ce7_19bc4bb22033</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Payouts pendientes de aprobar o rechazar

Si el Workflow que tiene tu comercio configurado para los Payouts así lo indica, la operación quedará en «pending» to «credit» y deberás aprobar o rechazar el payout. Sigue los pasos de esta guía para ello.

Consultar el estado de transacción

Puedes consultar el estado de una transacción de PayByBank que no se encuentre en estado final (SUCCESS, ERROR o CANCELLED). Esta petición nos permite recuperar el último estado de la transacción.

Estos son los endpoints donde se envía la petición de consulta de estado:

Entorno	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/checkTxn
Producción	https://checkout.addonpayments.com/EPGCheckout/rest/online/checkTxn

Petición

Recuerda que las peticiones enviadas a Addon Payments deben ser cifradas. Visita nuestra sección de Cifrado, firma y envío de la petición para más información.

Estos son unos ejemplos de petición de consulta de estado de una transacción PayByBank por H2H. Recuerda que la petición en cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&paymentSolution=paybybank&transactionId=12345

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/checkTxn' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInom”' \
--form 'integrityCheck="28531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Parámetros de la solicitud de consulta de estado

Estos son los parámetros que debes enviar para una consulta de estado en PayByBank. La columna tipo indica si el elemento es requerido/obligatorio (R):

Campo	Formato	Tipo	Descripción	Ejemplo
merchantId	Numérico entero 4~7 dígitos	R	Es el indicador de tu comercio en la plataforma de AP. Es facilitado por Soporte en el correo de bienvenida, es común para los dos entornos	14983
transactionId	Numérico entero Máx. 100 dígitos	R	Identificador de la transacción original sobre la cual va a realizarse una consulta.	76543210
paymentSolution	Alfanumérico Máx. 45 caracteres	R	Nombre de la solución de pago por la cual ha sido procesada la transacción inicial. Se indica en la respuesta de la transacción original.	paybybank
merchantTransactionId	Alfanumérico Máx. 18 caracteres Sin caracteres especiales (acentos, signos de puntuación, etc.) Sin nº duplicados	R	Identificador de la transacción en tu plataforma de comercio electrónico. Sirve para que tu plataforma enlace las notificaciones recibidas con el pedido del cliente. No puede repetirse entre transacciones.	pedido_91684

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Este es un ejemplo de una notificación a una consulta de estado de una transacción de PayByBank.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>EUR</currency>
            <details>{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","amount_in_minor":1000,"currency":"EUR","user":{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"payment_method":{"type":"bank_transfer","beneficiary":{"type":"merchant_account","reference":"xxxxxxx","merchant_account_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"provider_selection":{"type":"user_selected","filter":{},"provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"}},"created_at":"2024-01-01T00:00:00.000000Z","status":"settled","authorization_flow":{"configuration":{"provider_selection":{},"redirect":{"return_uri":"https://payment.truelayer-sandbox.com/payments/completed"},"form":{"input_types":["text","select","text_with_image"]},"consent":{"action_type":"adjacent","requirements":{"pis":{},"ais":{"scopes":["accounts","balance"]}}},"user_account_selection":{},"scheme_selection":{}}},"executed_at":"2024-01-01T00:00:00.000000Z","payment_source":{"account_identifiers":[{"type":"sort_code_account_number","sort_code":"123456","account_number":"12345678"},{"type":"iban","iban":"GB75CLRB04066800000871"}],"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","account_holder_name":"Nombre Apellido"},"settled_at":"2024-01-01T00:00:00.00Z","metadata":{"txnId":"xxxxxx","operationType":"Payin"},"creditable_at":"2024-01-01T00:00:00.000000Z"}</details>
            <merchantTransactionId>123456789</merchantTransactionId>
            <message>Check Transaction operation Success. Transaction status on Truelayer: settled</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</paySolTransactionId>
            <paymentDetails>
                <extraDetails/>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>xxxxxx</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</uuid>
            </respCode>
        </operation>
    </operations>
</response>

Integración Hosted

La solución de pago de PayByBank está disponible en integraciones Hosted. Puedes elegir si mostrar el cajero completo con todas las soluciones de pago que tu comercio tiene activas, o únicamente PayByBank. Te recomendamos que visites la documentación Hosted para conocer más detalles sobre este tipo de integración.

Autorización

La autorización es una operación de pago del cliente al comercio. La captura del importe es automática. Envía la petición al endpoint Hosted correspondiente.

Petición

Recuerda que las peticiones enviadas a Addon Payments deben ser cifradas. Visita nuestra sección de Cifrado, firma y envío de la petición para más información.

Estos son unos ejemplos de autorización mediante PayByBank por Hosted. Recuerda que la petición en cadena debe pasar el proceso de cifrado.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&operationType=debit&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 0Pn6pDEm73YvekNKUJcvwg==' \
--form 'merchantId="12345"' \
--form 'encrypted="jULXEtDfSVYIgfV29GBTcibe+ED+IvnfI2ssayrpqoJRzmI+SVst1SV3LRjt7DHlU5+0FoBPZy8K1wiPaTPYrMvCuxRAMYF+sk6ZPENAipntbetAbXHDVs6KKbjyCjDLRwGX7rrIlPi0TTIH9nGfPTq4DL1CDxivnjd1eOGOnHzQRr”' \
--form 'integrityCheck="0bc22b4408a6a2bf135fd2eb3832775f44b02f96d7e10d940b81c5069763685f"'

Recibirás una respuesta a esta petición con el enlace al cajero Hosted al que debes redirigir al cliente.

Parámetros de la solicitud de autorización

Puedes ver en la tabla común los parámetros requeridos para enviar para una petición de autorización PayByBank vía Hosted.

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Este es un ejemplo de respuesta recibida a una petición de autorización de una operación PayByBank:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228214</message>
    <operations>
        <operation sorted-order="1">
            <amount>10</amount>
            <currency>EUR</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"895883e0-b972-4480-a0f3-215a8db8606c","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","metadata":{"txnId":"228214","operationType":"Payin"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T06:39:32.673Z","payment_source":{"id":"671a41aa-3196-48fd-8b88-ed23fe8e978d","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"40097f84-d022-4f94-928c-d47ba5552c6a"}</details>
            <merchantTransactionId>0606001</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>9374a22a-3281-491d-8e5e-ee7c080601ef</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228214</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>8bcac545_9f4d_43f7_a28b_82e5b8ee35ca</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Integración JavaScript

Con Addon Payments puedes usar la solución de pago PayByBank con tu integración JavaScript. Esta integración tiene algunos pasos extra diferentes al resto de integraciones, por lo que te recomendamos que visites la documentación JavaScript para conocer más detalles.

Autorización

La autorización es una operación de pago del cliente al comercio. La captura del importe es automática. Envía la petición al endpoint JavaScript correspondiente.

Obtención del authToken y renderizado del cajero

El primer paso es solicitar el authToken y renderizar el cajero. Este paso es igual independientemente de la integración JavaScript. Consulta la documentación:

Charge

Con la obtención del «prepayToken», podrás enviar la petición de pago/charge. A continuación, te mostramos un ejemplo de petición PayByBank vía JavaScript.

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "10.00",
    "currency": "EUR",
    "country": "ES",
    "firstName": "Pablo",
    "lastName": "Ferrer",
    "telephone": "+34600600600",
    "customerCountry": "ES",
    "addressLine1": "calle canales 2",
    "postCode": "08003",
    "city": "Barcelona",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php",
    "successURL": "https:// micomercio.com/url-ok.php",
    "errorURL": "https:// micomercio.com/url-ko.php",
    "cancelURL": "https:// micomercio.com/url-cancelacion.php",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "operationType"= "debit"
}

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 8862abf9-ca5a-49da-9527-1e3163e64954' \
--data-raw '{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "10.00",
    "currency": "EUR",
    "country": "ES",
    "firstName": "Pablo",
    "lastName": "Ferrer",
    "telephone": "+34600600600",
    "customerCountry": "ES",
    "addressLine1": "calle canales 2",
    "postCode": "08003",
    "city": "Barcelona",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php?tipo=redireccion",
    "successURL": "https:// micomercio.com/url-ok.php",
    "errorURL": "https:// micomercio.com/url-ko.php",
    "cancelURL": "https:// micomercio.com/url-cancelacion.php",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "operationType"= "debit"
}'

Parámetros de la solicitud charge

Puedes ver en la tabla común los parámetros requeridos para enviar para una petición charge de autorización PayByBank vía JavaScript. Además, deberás enviar este parámetro que habrás obtenido previamente:

prepayToken: Se envía en la cabecera de la petición. AP devuelve esta referencia después de que el cliente introduzca sus datos en el formulario de pago de JS. Es la referencia que enlaza con los datos de la tarjeta o cuenta del cliente para integración JavaScript.

Respuesta

Visita nuestra sección de Recepción y gestión de las notificaciones para conocer su estructura.

Este es un ejemplo de notificación a una transacción PayByBank con el resultado de la transacción:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228214</message>
    <operations>
        <operation sorted-order="1">
            <amount>10</amount>
            <currency>EUR</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"895883e0-b972-4480-a0f3-215a8db8606c","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","metadata":{"txnId":"228214","operationType":"Payin"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T06:39:32.673Z","payment_source":{"id":"671a41aa-3196-48fd-8b88-ed23fe8e978d","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"40097f84-d022-4f94-928c-d47ba5552c6a"}</details>
            <merchantTransactionId>0606001</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>9374a22a-3281-491d-8e5e-ee7c080601ef</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228214</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>8bcac545_9f4d_43f7_a28b_82e5b8ee35ca</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Códigos de error

Estos son los códigos de error que puedes recibir en las notificaciones de transacciones de PayByBank. Los puedes encontrar en las líneas «code», «paymentCode», «paymentMessage».

< code > Código Addon Payments	Mensaje Addon Payments	< paymentCode >Código solución pago	< paymentMessage >Mensaje solución pago
1502	Insufficient funds	insufficient_funds	The PSU did not have the required balance in their account to complete this payment.
1508	A parameter on the payment call is invalid, check the Payment Solution Response	HttpStatus.BAD_REQUEST	INVALID_PARAMETERS
1509	The transaction was blocked by the Payment Solution.	blocked	The payment has been blocked due to a regulatory requirement. This may happen if the PSU fails a sanctions check.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_beneficiary_account	The payment failed because an invalid beneficiary account reference was provided.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_credentials	The banking credentials provided by the PSU to log into their bank were incorrect.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_iban	The IBAN that your user provided at the creation of the pay-in this closed-loop payout is for was invalid.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_mandate_state	The mandate was not in a valid status to create a recurring payment.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_otp	The PSU submitted an incorrect one-time password during the authorisation of the payment.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_remitter_account	The account details of the remitter bank account provided during the payment flow were incorrect.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_request	The payment failed due to invalid data in the request.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_scan	We could not convert the beneficiary’s sort code and account number to an IBAN.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_sort_code	The payment failed due to an invalid sort code being provided.
1509	The transaction could not be processed. Check the Payment Solution Response	mandate_revoked	The mandate for a recurring payment is revoked.
1509	The transaction could not be processed. Check the Payment Solution Response	server_error	TrueLayer encountered an error while processing the payment.
1511	The refund was unable to be processed. Check Payment Solution Response	returned	The payout was blocked or rejected by the beneficiary bank after it had entered the executed status.
1524	The provided transaction reference has already been used for another transaction. You must provide a unique value for each request	HttpStatus.CONFLICT	IDEMPOTENCY_KEY_CONCURRENCY_CONFLICT
1524	The provided transaction reference has already been used for another transaction. You must provide a unique value for each request	HttpStatus.UNPROCESSABLE_ENTITY	IDEMPOTENCY_KEY_REUSE
1526	The specified accountId or email is invalid	invalid_account_details	The payment failed because either the creditor’s or debtor’s account details were invalid.
1526	The specified accountId or email is invalid	invalid_account_holder_name	The payment failed because the account holder’s name details were invalid.
1540	The transaction exceeds allowed account limits	constraint_violation	The constraints set up for the mandate were breached by this recurring payment.
1542	Transaction was manually cancelled or declined by the merchant	canceled	The PSU cancelled the payment on the hosted payment page or the payment was cancelled using Cancel Payment API.
1542	Transaction was manually cancelled or declined by the merchant	user_canceled_at_provider	The payment failed because the user cancelled the authorisation during the payment flow.
1548	The third party processor has declined the transaction	provider_rejected	The payment was rejected by the provider for an unspecified reason.
1548	The third party processor has declined the transaction	rejected	The payment was rejected for an unspecified reason.
1600	Payment solution general input error, please check payment solution respond	provider_error	The provider has unexpectedly failed when creating the payment.
1605	The amount specified for this operation is incorrect please check the Payment Solution Respons	payment_limit_exceeded	The PSU’s payment limit amount with their bank was breached.
1607	Unknown error by the Payment Solution.	unknown	The payout failed for an unknown reason that does not belong to any of the other reasons.
1607	Unknown error by the Payment Solution.	unknown_error	The payment failed for an unknown reason.
1613	Unable to process this operation please check the Payment Solution Response	verification_declined	The payment did not satisfy the requested verification check.
1617	Payment Stopped by the Scheme	scheme_error	There was an issue with the selected payment provider or payment scheme.
1619	Not Authorized please check the Payment Solution Response	authorization_failed	The PSU failed to authorise the payment successfully.
1631	Token Error, please check payment solution respond	expired	The token of the payment expired before the payment got authorised, thus it won’t be possible to execute the payment.
1631	Token Error, please check payment solution respond	provider_expired	The payment failed because the token or exchange code used to communicate with the bank expired.
1632	Unknown payment solution error code	HttpStatus.INTERNAL_SERVER_ERROR	UNKOWN_ERROR
1658	Unable to auth	not_authorized	The PSU cancelled the payment or wasn’t able to successfully authenticate on the provider’s UI.
1663	Unsupported card scheme	scheme_unavailable	There is no scheme available given the provider selection configuration.
1692	No payment details were provided	HttpStatus.NOT_FOUND	PAYMENT_NOT_FOUND
2002	Unauthorized communication error	HttpStatus.UNAUTHORIZED	UNAUTHENTICATED
3099	Unidentified error	HttpStatus.NOT_IMPLEMENTED	NA
5042	The payment solution is not available	HttpStatus.FORBIDDEN	FORBIDDEN
8013	Exceed limits. Check Service Response	HttpStatus.TOO_MANY_REQUESTS	RATE_LIMIT_EXCEED
8025	Connection Error.Check Service Response	internal_server_error	An error has occurred within TrueLayer when processing the payment.

PayByBank

Introducción

Operativas admitidas

Flujo de la transacción

Requisitos para usar PayByBank

Requisitos para clientes

Requisitos para comercios

Crear una cuenta y aplicación para tu comercio Truelayer

Obtener los datos de tu cuenta en Truelayer y configurar las URLs de retorno de AP

Generar una clave de cifrado para Truelayer, subirlo y configurar las URLs de notificación de AP

Elige entre operar por circuito abierto o cerrado

Solicitar configuración de la solución de pago

Entornos y endpoints: Staging y Producción

Datos requeridos y opcionales PayByBank

Integración Host2Host

Autorización

Petición

Parámetros de la solicitud de autorización

Respuesta

Anulación

Petición

Parámetros de la solicitud de anulación

Respuesta

Devoluciones

Devolución mediante el panel de gestión de Truelayer

Devolución mediante petición

Petición

Parámetros de la solicitud de devolución

Respuesta

PayByLink (enlace de pago)

Petición

Parámetros de la solicitud PayByLink

Respuesta

Payout

Requisitos para los Payouts en PayByBank

Petición

Parámetros de la solicitud de Payout Paybybank

Circuito cerrado

Circuito abierto

Respuesta

Payouts pendientes de aprobar o rechazar

Consultar el estado de transacción

Petición

Parámetros de la solicitud de consulta de estado

Respuesta

Integración Hosted

Autorización

Petición

Parámetros de la solicitud de autorización

Respuesta

Integración JavaScript

Autorización

Obtención del authToken y renderizado del cajero

Charge

Parámetros de la solicitud charge

Respuesta

Códigos de error

Tabla de Contenidos

Productos

Ventas

Soporte técnico

Socios

SmartWiki, Impulsada por IA

Cyberpac

Consulta la documentación de las distintas secciones de integraciones:

Addon Payments

Pagos integrados en TPV