Pasarela de Pagos Online Autopay - DocumentaciónPobierz

Autopay Online Payments es una solución integral para aceptar pagos de clientes de tiendas online, compatible con diversos métodos de pago disponibles en el mercado, como transferencias, Pay by link, BLIK, Google Pay, Apple Pay.
En esta documentación encontrará todo lo necesario para implementar rápidamente la pasarela de pago en su tienda online.
La documentación de Autopay Online Payments incluye secciones como Gestión de transacciones y liquidación, Extensiones adicionales.

Definiciones

Aplicación - Aplicación móvil del socio, comunicándose con el SDK del sistema de pago en línea Autopay para registrar Transacciones.

AP - Autopay S.A. Sociedad, con sede en Sopot, en Powstańców Warszawy 6, registrada en el Tribunal de Distrito Gdańsk-Norte en Gdańsk, División Comercial VIII del Registro Nacional de Tribunales con el número KRS 0000320590, con NIF (NIP) 585-13-51-185, REGON 191781561, con un capital social de 2 205 500 PLN (totalmente desembolsado), supervisada por la Comisión de Supervisión Financiera y registrada como entidad de pago nacional con el IP17/2013, propietaria del Sistema.

BalancePoint (Punto de liquidación) - una entidad dentro del Sistema de Pagos que representa a una Tienda integrada en la Plataforma Marketplace y registrada en el Sistema de Pagos mediante un formulario facilitado por AP al Socio.

ClientHash - un parámetro en los mensajes; permite asignar un instrumento de pago (por ejemplo, Tarjeta) a un Cliente de forma anónima. Basándose en esto, el Socio puede iniciar cargos posteriores en el modelo de pago automático.

ComisiónModelo - un modelo de comisión establecido con el Integrador. Describe los valores de comisión de las transacciones transferidas a AP y al Integrador.

Día laborable - al día, de lunes a viernes, excepto los días festivos polacos.

Formulario de integración - una página web en la que está disponible un formulario que permite al Cliente registrarse, editar o añadir un nuevo Servicio.

Instrumento de pago (Canal de pagos) - un conjunto de procedimientos o un dispositivo individualizado acordado por el Cliente y su proveedor, utilizado por el Cliente para iniciar una orden de pago, por ejemplo, Tarjeta, PBL.

Herramienta de transferencia electrónica - un conjunto de procedimientos o un dispositivo individualizado acordado entre el Socio y AP, utilizado por el Socio para iniciar una orden de pago que permita la retirada de fondos del saldo a la cuenta bancaria del Socio o Cliente y otro instrumento de pago propiedad del Socio o Cliente. La disponibilidad de la funcionalidad depende de los acuerdos individuales entre el Socio y AP.

Integrador - Se denomina integradores a los socios que han implementado Autopay Online Payments en sus sistemas y permiten su activación desde dentro de sus propias soluciones. Entre los integradores se encuentran entidades como Shoper, Sky-Shop, Gymsteer, Selly verifications, FaniMani, AtomStore, Ebexo, Selly Azymut, PayNow, Comarch.

IPN (Notificación instantánea del producto) - notificación inmediata enviada desde el Sistema de Pago en Línea al Servicio Asociado comunicando un cambio en el estado del producto. La estructura de la IPN es similar a la de la ITN (ampliada únicamente por el nodo producto).

ITN (Notificación instantánea de transacciones)- notificación inmediata enviada desde el Sistema de Pago en Línea al Servicio Asociado transmitiendo un cambio en el estado de la transacción.

ISTN (Notificación Instantánea de Transacciones de Liquidación) - notificación inmediata del cambio de estado de una operación de liquidación. El sistema transmitirá inmediatamente notificaciones del hecho de que se ha ordenado una operación de liquidación (retiradas/devoluciones, en su caso) y de un cambio en su estado.

ICN (Notificación instantánea de configuración) - notificación inmediata de la configuración de una tienda recién registrada, comunicando información sobre un cambio en el estado de la tarjeta de la tienda (por ejemplo, en caso de activación de la tarjeta). Los mensajes ICN también pueden enviarse en caso de un cambio en la configuración de la tienda, un cambio en sus datos AML, la habilitación/deshabilitación de un canal de pago. La provisión de funcionalidad está sujeta a acuerdos individuales entre el Socio y AP.

Tarjeta - Tarjeta de pago emitida en el marco de los sistemas VISA y Mastercard, autorizada por la normativa de dichos sistemas a ejecutar Transacciones sin su presencia física.

Cliente (pagador) - una persona que realiza un pago en el Sitio Web por servicios o productos de un Socio utilizando el Sistema.

Cesta de productos - Se trata de la información sobre los componentes del pago, transferida (en el enlace de pago) al Sistema para su posterior procesamiento. Cada producto de la cesta de la compra se describe mediante dos campos obligatorios: el importe constitutivo y un campo que permite transferir parámetros específicos del producto.

Enlace de pago - solicitud que permite el inicio de una Transacción de Entrada (descrita en la parte Inicio de la transacción). Puede utilizarse directamente en el sitio web (método POST), mientras que en los correos electrónicos a los clientes debe utilizarse Antes de la transacción para obtener un enlace corto al pago (método GET).

Enlace de verificación - URL que dirige a la transferencia de verificación.

Mercado - una solución de pago que opera en el marco del sistema de pago en línea Autopay. Permite al Socio operar una plataforma de ventas donde los productos o servicios son ofrecidos a los clientes por los Contratistas del Socio. Los modelos avanzados de liquidación de Transacciones y Transacciones de Liquidación permiten que los pagos se realicen directamente del Cliente al Contratista del Socio, teniendo en cuenta la Cesta de productos. La provisión de la funcionalidad está sujeta a acuerdos individuales entre el Partner y AP.

Modelo de pagador - un modelo en el que la comisión por la transacción realizada la paga el cliente a AP (coste añadido al importe de la transacción). En este caso, el cliente también acepta las condiciones de AP durante el pago.

Modelo de comerciante - un modelo en el que la comisión se liquida entre Autopay y el socio y no se añade al importe de la transacción pagado por el cliente.

Socio - la entidad receptora de fondos procedentes de la venta de productos o servicios distribuidos por el afiliado en el sitio.
Un socio, en el caso del modelo Marketplace, es una entidad, que no es un consumidor, interesada en gestionar la aceptación por parte de AP de los pagos debidos al socio por productos o servicios distribuidos por el socio.

Pago por enlace (PBL) - una herramienta para realizar pagos mediante transferencia interbancaria de la cuenta del cliente a la cuenta de AP. Tras conectarse a la banca en línea, los datos necesarios para ejecutar la transferencia (datos del destinatario, número de su cuenta bancaria, importe y fecha de ejecución de la transferencia) se rellenan automáticamente gracias al sistema de intercambio de datos entre el banco y AP.

Agente técnico - la entidad con derecho a acceder a la Cuenta de Pago del Socio, que autoriza este acceso (consentimiento o acuerdo). En el sistema, el apoderamiento está representado por la configuración del campo PlenipotenciarioIDuna entidad puede tener varios proxies para diferentes Socios.

Plataforma de mercado - plataforma en la que se ofrece la posibilidad de registrar Puntos de Liquidación.

Pago automático - pago efectuado sin necesidad de introducir cada vez los datos de la tarjeta o los datos para autorizar la transferencia.

Pago con un clic - es un pago automático ordenado por el cliente.

Pago cíclico - es un pago automático ordenado sin la participación del cliente (por el Servicio Asociado).

Antes de la transacción - enlace de pago de pedido específico (realizado en segundo plano).

Transferencia de verificación - La parte del proceso relacionada con el registro y la edición del/de los Servicio(s) del Socio en el Sistema. Consiste en que el Socio realice una transferencia de fondos para verificar los datos y la cuenta bancaria para el desembolso de fondos al Socio. La verificación de datos es una obligación de la PA derivada, entre otras cosas, de la Ley de 16/11/2000 sobre la prevención del blanqueo de capitales y la financiación del terrorismo. Cada transferencia verificada debe recibir el estado de verificación final (positivo o negativo) en un plazo de 30 días a partir del pago de la transacción. Si el estado de verificación final no se da en el plazo especificado anteriormente, el sistema le dará automáticamente un estado negativo. Este proceso se aplica a la verificación en la que Autopay dirige una solicitud para completar los datos al cliente y no recibe la información de retorno necesaria para llevar a cabo esta verificación.

Cuenta de pago (saldo) - cuenta de pago mantenida por AP para el Socio, en la que se recaudan los fondos depositados por los Clientes. La prestación de la funcionalidad está sujeta a acuerdos individuales entre el Socio y AP.

RPAN (Notificación de activación de pago periódico) - mensaje sobre la activación del servicio de pago automático.

RPDN (Notificación de desactivación de pagos periódicos) - mensaje sobre la desactivación del servicio de pago automático.

Servicio - el sitio web del Socio o los sitios web integrados con el Sistema, donde el Cliente puede adquirir productos o servicios del Socio (o de la Contraparte del Socio en el caso del Mercado).
En el caso de un Mercado, un objeto en el Sistema de Pago que representa el Mercado del Socio. Todas las transacciones iniciadas por dicho Mercado se adjuntan a él.

Especificación - documentación que describa la comunicación entre el Servicio y el Sistema.

Sistema de pago en línea AP (Sistema) - una solución informática y funcional por la que el PA proporciona al Socio una aplicación para procesar los pagos de los clientes realizados con el uso de Instrumentos de Pago, así como para verificar el estado de los pagos y recibir pagos.

Transferencia rápida - ejecución de pagos mediante transferencia intrabancaria de la cuenta del Cliente a la cuenta de AP. El pago realizado a través de PBL se diferencia de los pagos realizados a través de PBL en que el Cliente debe rellenar él mismo todos los datos necesarios para realizar la transferencia.

Transacción - una operación de pago en el sentido de la Ley polaca de 19 de agosto de 2011 sobre servicios de pago.

Transacción de entrada - parte del proceso de tramitación del pago relativo al pago efectuado por el cliente a AP.

Operación de liquidación - parte del proceso de procesamiento de pagos, relativa a la transferencia realizada por AP a la cuenta del Socio. Para que se cree una Transacción de Liquidación, la Transacción de Entrada debe ser pagada por el Cliente. Una Transacción de Liquidación puede referirse a una única Transacción de Entrada (pago), o agregar múltiples de ellas.

Actuar - Ley polaca de 19 de agosto de 2011 sobre servicios de pago.

Validez del enlace - parámetro que especifica el momento a partir del cual el Enlace de Pago deja de estar activo. Debe ser fijado por el LinkValidityTime en el enlace de pago.

Validez de las transacciones - parámetro que especifica el momento a partir del cual el Enlace de Pago deja de estar activo. Debe establecerse mediante el parámetro LinkValidityTime del Enlace de Pago.

Widget de pago automático - un mecanismo que permite el pago con Tarjeta de los productos/servicios ofrecidos por el Socio, en el que los datos de la Tarjeta son introducidos por el Cliente en el mecanismo incrustado directamente en el Sitio Web del Socio. La invocación del formato de widget de tarjeta requiere la implementación de código JavaScript utilizando una biblioteca AP dedicada.

Widget de incorporación - una solución que permite al Integrador incrustar el Formulario de Integrador (preparado por Autopay) directamente en el sitio Web del Integrador, de modo que el Socio no sea redirigido al dominio de Autopay al registrar su tienda - todo el proceso se lleva a cabo en el sitio Web del Socio.

Marca blanca - modelo de integración, en el que el cliente que ya está en el Servicio selecciona el canal de pago y acepta las normas y reglamentos (siempre que la necesidad de su aceptación se derive de acuerdos individuales entre el Socio y el PA), y el inicio de la transacción incluye una transacción completada GatewayID (y en algunos casos DefaultRegulationAcceptanceID o RecurringAcceptanceID).

Inicio de una orden de pago - el momento en que el usuario de la pasarela de pago selecciona un canal de pago y es redirigido a la página correspondiente al canal de pago seleccionado o (para pagos automáticos, monederos electrónicos o BLIK) se intenta realizar un cargo en la tarjeta o cuenta del proveedor del canal de pago.

Direcciones de medio ambiente

PRUEBA

• gate_host: https://testpay.autopay.eu

• tarjetas_gate_host: https://testcards.autopay.eu

PRODUCCIÓN

• gate_host: https://pay.autopay.eu

• tarjetas_gate_host: https://cards.autopay.eu

Procesamiento de transacciones y liquidaciones

Organigrama del servicio de transacciones y compensación

En la Página Web del Socio, tras completar el pedido, se presenta al Cliente la opción de realizar un pago utilizando el Sistema. Al hacer clic en el enlace correspondiente, se inicia la transacción y se abre una nueva ventana:

a) una página específica del Sistema preparada por AP, en la que se presenta al Cliente una lista de los Canales de Pago disponibles y un resumen de la transacción registrada o

b) directamente desde un Canal de Pago (Banco, BLIK o para pago con Tarjeta).

Por parte del Sistema, se validan los parámetros transmitidos y se guarda la transacción con un periodo de validez fijo. Si, en el momento de la validación, ya se ha superado el periodo de validez del enlace, el Cliente recibirá un mensaje apropiado (la verificación de la validez de la transacción también tiene lugar cuando se cambia el estado del pago). Tras la verificación positiva de los parámetros de la transacción (y tras la selección del Canal de Pago), el Cliente autoriza la transacción. En su título, además de los identificadores asignados por el Sistema, también puede haber una descripción fija, acordada de antemano entre el PA y el Socio, o un valor dinámico proporcionado por el Socio al inicio de la transacción.

El modelo de integración recomendado es transmitir un mensaje para iniciar una transacción de
en segundo plano, es decir, sin redirigir al usuario al Sistema (véase Antes de la transacción). En este modelo, es posible utilizar formas avanzadas de autorización de transacciones (WhiteLabel, pagos automáticos, SDK móvil), diagnóstico de la corrección de los parámetros transmitidos y muchas otras extensiones.

Una vez autorizada la transacción (en la página del Canal de Pago), el Cliente vuelve desde ella al Sistema, donde se le redirige automáticamente al Servicio Asociado.

TIP: Una descripción detallada de la estructura del enlace de retorno se puede encontrar en
parte de la Redirección al sitio asociado.

El estado de autorización (pago) recibido del Canal de Pago se transmite desde el Sistema al Servicio Asociado a través de un mensaje ITN. El Sistema continuará enviando mensajes hasta que el Servicio Asociado acuse recibo o expire el período de validez de la notificación. Las transacciones que se pagan después de la expiración del período de validez de la transacción - se devolverán al Cliente (remitente de la transferencia).

Opcionalmente, el Sistema puede notificar el hecho de que se ha emitido una Operación de Liquidación
. Para ello se utiliza un mensaje ISTN convenientemente modificado.

Pasos para integrar la gestión de transacciones y liquidaciones

Datos necesarios para la integración del procesamiento de transacciones y liquidaciones

Los datos necesarios intercambiados durante la integración difieren para los entornos de prueba y de producción. A continuación se muestra una lista de parámetros que se pasan de AP a Partner y en sentido inverso.

También se proporciona información general, es decir, canales de pago activos con gráficos (como resultado de la consulta de la lista de canales de pago disponibles).

Opcionalmente, puede haber datos adicionales transmitidos por el Socio al PA, por ejemplo: información sobre el contenido requerido de la cesta de la compra y la forma en que se procesa (en informes, facturación, panel de administración), requisitos adicionales (para recarga de saldo prepago). Para
pagos automáticos BLIK también la duración por defecto de los pagos automáticos activados y la etiqueta por defecto de los pagos automáticos activados.

Datos intercambiados en el entorno de prueba

Datos facilitados por el socio a AP:

• Dirección para los mensajes ITN
• Dirección para los mensajes RPAN (puede ser la misma que para los mensajes ITN) [para pagos automáticos].
• Dirección para los mensajes RPDN (puede ser la misma que para los mensajes ITN) [para pagos automáticos].
• Dirección del remitente del pago (sin parámetros)

Datos transferidos de AP a Partner:

• Dirección del sistema de pago en línea
• ServiceID
• AcceptorID [para carteras en el modelo WhiteLabel].
• Llave compartida
• Resultado del hashing
• Dirección del formulario de prueba
• Dirección IP desde la que se envían los ITN
• Dirección del panel de administración
• Inicio de sesión
• Contraseña

Datos transferidos en un entorno de producción

Por Socio a AP:

• Dirección para los mensajes ITN
• Dirección para los mensajes RPAN (puede ser la misma que para los mensajes ITN) [para pagos automáticos].
• Dirección para los mensajes RPDN (puede ser la misma que para los mensajes ITN) [para pagos automáticos].
• Dirección del remitente del pago (sin parámetros)
• Direcciones de correo electrónico para los informes de transacciones
• Direcciones de correo electrónico para facturas e informes de facturación
• Direcciones de correo electrónico para reclamaciones (enviadas en mensajes a los pagadores)

Por AP a Socio:

• Dirección del sistema de pago en línea
• ServiceID
• AcceptorID [para carteras en el modelo WhiteLabel].
• Llave compartida
• Resultado del hashing
• Dirección del formulario de prueba
• Dirección IP desde la que se envían los ITN
• Dirección del panel de administración
• Inicio de sesión
• Contraseña

Implantación de interfaces y procesos por parte del socio

En la versión mínima de la integración, debe implementarse el soporte para iniciar una transacción, volver de ella y el soporte para la comunicación ITN.

TIP: Es aconsejable familiarizarse con el esquema de funcionamiento. Si es necesario, también es aconsejable familiarizarse con los parámetros o servicios adicionales.

Pruebas de integración y migración al entorno de producción

Durante las pruebas, los campos en blanco de la hoja deben completarse y enviarse de vuelta al PA para confirmar la correcta integración antes de la migración al entorno de producción.

TIP: Antes de la implantación en producción, se recomienda realizar pruebas de acuerdo con el escenarios de prueba en la versión básica y, para integraciones más avanzadas, también según escenarios adicionales.

Inicio de la transacción

Descripción del inicio de la transacción

El servicio asociado que inicia la transacción transmite al Sistema de Pago en Línea los parámetros necesarios para completar la transacción y la posterior transmisión del estado del pago.

Todos los parámetros se pasan a través del método POST (Content-Type: application/x-www-form-urlencoded).

El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros transmitidos deben codificarse en UTF-8 (y protocolo de transporte - codificar antes de enviar, a menos que la herramienta utilizada para enviar el mensaje no lo haga por sí misma, ejemplo de codificación: URLEncode).

Lista de parámetros de inicio de transacción

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración
.

Método para iniciar una transacción

La transacción se inicia mediante el envío de una llamada HTTPS una combinación de los parámetros anteriores a la dirección del sistema de pago en línea establecido durante el registro del servicio.

IMPORTANTE: El número de transacciones lanzadas por el Socio en un minuto puede ser de un máximo de 100, a menos que el Socio y AP acuerden un límite superior como parte del acuerdo concluido.

Ejemplo de inicio de una transacción:

Dirección:

• https://{gate_host}/ruta

Parámetros:

• ServicioID=2

• OrderID=100

• Importe=1,50

    Hash=2ab52e6918c6ad3b69a8228a2ab815f11ad58533eeed963dd990df8d8c3709d1
  

Enviar un mensaje sin todos obligatorio parámetros (ServiceID, OrderID, Importe y Hash) o que contengan valores incorrectos de sus
, provocarán que el proceso de pago se detenga con un código de error de transacción y un breve mensaje de error (sin retorno a la
página de Servicio al Socio).

IMPORTANTE El parámetro ServiceID y OrderID identifica de forma única
la transacción. No es admisible que el valor del parámetro OrderID parámetro que debe repetirse durante todo el periodo de servicio prestado por el Sistema a un único Servicio Asociado (ServiceID).

El parámetro opcional GatewayID se utiliza para especificar el Canal de Pago a través del cual debe efectuarse el pago. Esto permite transferir al Servicio la pantalla de selección de Canales de Pago. La lista actual de identificadores de Canales de Pago, incluidos los logotipos, está disponible a través de la opción gatewayList método.

El mensaje de inicio de la transacción puede transmitirse en segundo plano, es decir, sin redirigir al usuario al Sistema de Pago en Línea. En este modelo, la selección del propio Canal de Pago también la realiza el Cliente en el Servicio Asociado.

Redirección al sitio asociado

Descripción de la redirección al sitio asociado

Inmediatamente después de completar la autorización de la transacción por parte del Cliente, éste es redirigido desde el sitio del Canal de Pago al sitio en línea del Sistema de Pago, donde el Cliente es redirigido automáticamente al Servicio Asociado. La redirección se realiza mediante el envío de una solicitud HTTPS (utilizando el método GET) a una dirección de retorno predeterminada en el Servicio Asociado. El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros.

Lista de parámetros de redirección para el sitio asociado

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

Ejemplo de mensaje que redirige al Cliente desde el sistema de pago en línea al Sitio Asociado

https://shop_name/return_page?ServiceID=123458&OrderID=123402816&Hash=5432d69a66d721b2f5f785432bf5a1fc1b913bdb3bba465856a5c228fe95c1f8

Notificaciones instantáneas (ITN)

Descripción de las notificaciones instantáneas

El Sistema transmite notificaciones de cambios en el estado de una operación tan pronto como recibe dicha información del Canal de Pago, y el mensaje siempre se refiere a una única operación.

NOTA: El dominio debe ser público y accesible a través del Sistema. El dominio debe estar protegido por un certificado válido emitido por una autoridad de certificación pública (Certificate authority) El servidor debe presentar una cadena de certificados completa (Chain of Trust) La comunicación debe basarse en el protocolo TLS versión 1.2 o 1.3 *Otras formas de seguridad de la conexión, por ejemplo VPN, mTLS deben acordarse individualmente con la persona responsable de la implementación.

Ejemplo:

https://shop_name/status_receive

La notificación de un cambio en el estado de una transacción de entrada consiste en el envío por parte del Sistema de un documento XML que contiene los nuevos estados de la transacción.

El documento se envía a través de HTTPS (puerto 443 por defecto) - utilizando el método POST, como un parámetro HTTP con el nombre transacciones. Este parámetro se almacena utilizando el mecanismo de cifrado de transporte Base64.

Formato de documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
		<serviceID>ServiceID</serviceID>
		<transactions>
			<transaction>
				<orderID>OrderID</orderID>
				<remoteID>RemoteID</remoteID>
				<amount>999999.99</amount>
				<currency>PLN</currency>
				<gatewayID>GatewayID</gatewayID>
				<paymentDate>YYYYMMDDhhmmss</paymentDate>
				<paymentStatus>PaymentStatus</paymentStatus>
				<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
			</transaction>
		</transactions>
		<hash>Hash</hash>
	</transactionList>

NOTA: A transacciones sólo puede contener un nodo transacción (por lo que la notificación es siempre para una transacción). Los valores de orderID y importe relativos a cada transacción son idénticos a los valores de los campos correspondientes proporcionados por el Servicio asociado al inicio de la transacción respectiva. La excepción son los modelos en los que la comisión se añade al importe de la transacción. En tales casos, el valor de la cantidad en el ITN se incrementa en esta comisión. La validación de los importes puede entonces llevarse a cabo sobre la base del campo opcional ITN startAmount. No obstante, este campo debe solicitarse durante la integración.

Lista de parámetros devueltos para las notificaciones instantáneas

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

TIP: Elemento hash (mensaje) se utiliza para autenticar
el documento. Para una descripción de cómo se calcula el hash, véase la sección Seguridad de las transacciones.

Respuesta a la notificación instantánea

En respuesta a la notificación, se espera un estado HTTP de 200 (OK) y
un texto en formato XML (Base64 sin codificar), devuelto por la función
Partner Service en la misma sesión HTTP, que contiene un acuse de recibo
del estado de la transacción.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<transactionsConfirmations>
			<transactionConfirmed>
				<orderID>OrderID</orderID>
				<confirmation>Confirmation</confirmation>
			</transactionConfirmed>
		</transactionsConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Descripción de los campos de confirmación para notificaciones inmediatas

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

En ausencia de una respuesta correcta a las notificaciones enviadas, el Sistema realizará nuevos intentos de comunicar el último estado de la transacción una vez transcurrido el tiempo especificado. El Servicio Asociado debe realizar su propia lógica de negocio (por ejemplo, correo electrónico de confirmación), sólo después del primer <mensaje sobre un determinado estado de pago.

TIP: Merece la pena echar un vistazo a Esquema de retransmisión de mensajes ITN/ISTN/IPN/RPAN/RPDN.

Descripción detallada del comportamiento y cambio de los estados de pago (paymentStatus)

El método de pago elegido por el cliente enviará un estado de PENDIENTE cada vez. En el mensaje ITN posterior, el sistema proporcionará el estado ÉXITO o FALLO.

NOTA En PENDIENTE no se enviará si:

• el Cliente abandona o vuelve de la pantalla de la lista de métodos de pago sin seleccionar un método específico. En este caso, el FALLO se enviará inmediatamente. El estado PENDIENTE no aparecerá ya que el cliente no ha iniciado el proceso de pago.
• El estado final (ÉXITO o FALLO) se entregará antes de que se envíe el ITN con el estado PENDIENTE.

Para una transacción única (con parámetros únicos OrderID y RemoteID), no puede haber cambio de estatus de ÉXITO es PENDIENTE o ÉXITO es FALLO.

En cualquier caso, puede haber un cambio de estado de detalle - paymentStatusDetails (los mensajes posteriores sobre un cambio de estado de detalle son sólo informativos y no deben llevar a repetir el servicio pagado/envío de producto, etc.).

En casos especiales de uso, puede haber un cambio de estado:

a) FALLO es ÉXITO (por ejemplo, después de que un consultor AP haya aprobado una transacción pagada con un importe incorrecto. Este comportamiento requiere acuerdos comerciales especiales y no está habilitado por defecto),

b) ÉXITO es FALLO (por ejemplo, después de activar varias transacciones con el mismo OrderID pero diferente RemoteID). Tal caso se produce cuando un Cliente inicia múltiples pagos con el mismo OrderID (por ejemplo, el Cliente cambia su decisión sobre el Canal de Pago con el que desea pagar la operación). Cada uno de los pagos iniciados por él genera ITN y las operaciones individuales deben distinguirse por el RemoteID parámetro. Como la hora de recepción del FALLO puede variar mucho, puede ocurrir que dicho estado se reciba después de ÉXITO se ha recibido (por supuesto con un RemoteID). En tal caso, deberá acusarse recibo del mensaje ITN, pero no deberá implicar la cancelación del estado de la transacción en el sistema del Socio.

Gestión de los estados de las transacciones desde ITN - Modelo simplificado

En un modelo en el que no es necesario notificar al Cliente por correo electrónico/sms los estados de no ÉXITO, la cantidad de información
almacenados en la base de datos del Servicio y se puede reducir el seguimiento de los cambios de RemoteID.

Todo lo que necesitas es:

• para estados distintos de ÉXITOconfirme cada vez el ITN con la estructura de respuesta correcta, CONFIRMADO estado y contabilizado correctamente el valor del campo Hash,

• en caso de recepción de En primer lugar estado ÉXITO, también se añade la actualización del estado, su hora y RemoteID en la base de datos del Servicio y la ejecución de procesos de negocio (notificaciones al Cliente de cambios de estado, ejecución de envío de servicios/productos pagados, etc.),

• en caso de ÉXITO confirmar cada vez el ITN con una estructura de respuesta correcta, CONFIRMADO estado y contabilizado correctamente el valor del campo Hash, sin actualizar la base de datos del Servicio y sin procesos de negocio.

Gestión de los estados de las transacciones desde ITN - modelo completo

En un modelo en el que todo el historial de cambios de estado de las transacciones y/o la notificación al cliente de cambios de estado importantes
de transacciones, debe utilizarse una lógica que se aproxime a la siguiente descripción.

Seguridad de las transacciones

Descripción de la seguridad de la transacción

El sistema de pago en línea utiliza varios mecanismos para aumentar
la seguridad de las transacciones realizadas a través de él. La transmisión entre todas las partes de una transacción se realiza utilizando un
conexión segura basada en el protocolo TLS con una clave de 2048 bits.

Además, la comunicación se asegura mediante una función hash calculada a partir de los valores de los campos del mensaje y la clave compartida (la propia clave compartida se almacena en el Sistema de forma cifrada mediante el algoritmo AES-ECB).

Como función hash se utiliza el algoritmo SHA256 o SHA512 (método determinado en la fase de configuración del respectivo Servicio Asociado en el sistema de pago en línea). La función por defecto es SHA256.

Cálculo del valor de una función hash

Descripción de cómo calcular el valor de la función hash y ejemplos de cálculos para mensajes básicos.

NOTA: Los ejemplos no tienen en cuenta todos los campos opcionales posibles, por lo que si tales campos están presentes en un mensaje concreto, deben incluirse en la función abreviada en un orden coherente con el número que aparece junto al campo.

Cálculo del valor de la función hash - Campo hash

El valor de la función hash, utilizada para autenticar el mensaje, se calcula a partir de una cadena que contiene los campos concatenados del mensaje (concatenación de campos). Los valores de los campos se concatenan, sin los nombres de los parámetros, y se inserta un separador (en forma del carácter |) entre
valores consecutivos (no vacíos). El orden en que se pegan los campos sigue el orden en que aparecen en la lista de parámetros de la documentación.

IMPORTANTE Si no hay ningún parámetro opcional en el mensaje o en el caso de un valor de parámetro vacío, ¡no utilice el separador!

A la cadena creada de este modo se le añade una clave al final, compartida entre el Servicio asociado y el sistema de pago en línea. A partir de la cadena creada de este modo, se calcula el valor de la función hash, que constituye
el valor del campo Hash del mensaje.

Hash = function(campo_valor_1_mensaje + "|" + campo_valor_2_mensaje + "|" + ... + "|" + field_value_n_message + "|" + shared_key);

Ejemplo de cálculo del valor de la función hash al inicio de una transacción

Datos del Servicio de Atención al Socio:
ServiceID = 2

clave_compartida = 2prueba2

Dirección de la pasarela https://{gate_host}/pathway

a. Inicio de la transacción

Llamada POST sin cesta, con parámetros:

ServicioID=2
OrderID=100
Importe=1,50

Hash=2ab52e6918c6ad3b69a8228a2ab815f11ad58533eeed963dd990df8d8c3709d1

donde

Hash=SHA256(“2|100|1.50|2test2”)

b. Inicio de la transacción. Llamada POST con el carrito de la compra.

TIP: Opción tratada en detalle en la sección Cesta de productos.

ServiceID = 2

OrderID = 100

Importe = 1,50

Producto (descrito a continuación)

clave_compartida = 2prueba2

Cesta de productos (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<productList>
	   <product>
		  <subAmount>1.00</subAmount>
		  <params>
			 <param name="productName" value="Nazwa produktu 1" />
		  </params>
	   </product>
	   <product>
		  <subAmount>0.50</subAmount>
		  <params>
			 <param name="productType" value="ABCD" />
			 <param name="ID" value="EFGH" />
		  </params>
	   </product>
	</productList>

Tras codificar con la función base64, obtenemos el valor del parámetro Product:

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cHJvZHVjdExpc3Q+PHByb2R1Y3Q+PHN1YkFtb3VudD4xLjAwPC9zdWJBbW91bnQ+PHBhcmFtcz48cGFyYW0gbmFtZT0icHJvZHVjdE5hbWUiIHZhbHVlPSJOYXp3YSBwcm9kdWt0dSAxIiAvPjwvcGFyYW1zPjwvcHJvZHVjdD48cHJvZHVjdD48c3ViQW1vdW50PjAuNTA8L3N1YkFtb3VudD48cGFyYW1zPjxwYXJhbSBuYW1lPSJwcm9kdWN0VHlwZSIgdmFsdWU9IkFCQ0QiIC8+PHBhcmFtIG5hbWU9IklEIiB2YWx1ZT0iRUZHSCIgLz48L3BhcmFtcz48L3Byb2R1Y3Q+PC9wcm9kdWN0TGlzdD4=

El valor Hash se calcula del siguiente modo:

Hash=SHA256(“2|100|1.50|PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cHJvZHVjdExpc3Q+PHByb2R1Y3Q+PHN1YkFtb3VudD4xLjAwPC9zdWJBbW91bnQ+PHBhcmFtcz48cGFyYW0gbmFtZT0icHJvZHVjdE5hbWUiIHZhbHVlPSJOYXp3YSBwcm9kdWt0dSAxIiAvPjwvcGFyYW1zPjwvcHJvZHVjdD48cHJvZHVjdD48c3ViQW1vdW50PjAuNTA8L3N1YkFtb3VudD48cGFyYW1zPjxwYXJhbSBuYW1lPSJwcm9kdWN0VHlwZSIgdmFsdWU9IkFCQ0QiIC8+PHBhcmFtIG5hbWU9IklEIiB2YWx1ZT0iRUZHSCIgLz48L3BhcmFtcz48L3Byb2R1Y3Q+PC9wcm9kdWN0TGlzdD4=|2test2”)

Ejemplo de cálculo del valor de una función hash al devolver un cliente al sitio asociado

Datos del Servicio de Atención al Socio:

ServiceID = 2

clave_compartida = 2prueba2

<https://shop_name/strona_powrotu?ServiceID=2>&OrderID=100&Hash=254eac9980db56f425acf8a9df715cbd6f56de3c410b05f05016630f7d30a4ed

donde

Hash=SHA256("2|100|2test2")

Ejemplo de cálculo del valor de una función hash en un mensaje ITN

Datos del Servicio de Atención al Socio:

serviceID = 1

clave_compartida = 1prueba1

ITN (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
	   <serviceID>1</serviceID>
	   <transactions>
		  <transaction>
			 <orderID>11</orderID>
			 <remoteID>91</remoteID>
			 <amount>11.11</amount>
			 <currency>PLN</currency>
			 <gatewayID>1</gatewayID>
			 <paymentDate>20010101111111</paymentDate>
			 <paymentStatus>SUCCESS</paymentStatus>
			 <paymentStatusDetails>AUTHORIZED</paymentStatusDetails>
		  </transaction>
	   </transactions>
	   <hash>a103bfe581a938e9ad78238cfc674ffafdd6ec70cb6825e7ed5c41787671efe4</hash>
	</transactionList>

donde

Hash=SHA256(“1|11|91|11.11|PLN|1|20010101111111|SUCCESS|AUTHORIZED|1test1”)

Ejemplo de respuesta (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
	   <serviceID>1</serviceID>
	   <transactionsConfirmations>
		  <transactionConfirmed>
			 <orderID>11</orderID>
			 <confirmation>CONFIRMED</confirmation>
		  </transactionConfirmed>
	   </transactionsConfirmations>
	   <hash>c1e9888b7d9fb988a4aae0dfbff6d8092fc9581e22e02f335367dd01058f9618</hash>
	</confirmationList>

donde valor

Hash=SHA256("1|11|CONFIRMED|1test1");

Ejemplo de cálculo del valor de la función hash en la consulta de la lista de Canales de Pago

Datos del Servicio de Atención al Socio:

ServiceID = 100

MessageID = 11111111111111111111111111111111

Divisas = PLN,EUR

Idioma = EN

clave_compartida = 1prueba1

donde el valor

Hash=SHA256('100|11111111111111111111111111111111|PLN,EUR|PL|1test1')

La respuesta a la llamada anterior puede ser la siguiente (nota: no hay campo hash en la respuesta):

{
    "result": "OK",
    "errorStatus": null,
    "description": null,
    "gatewayGroups": [
        {
            "type": "PBL",
            "title": "Przelew internetowy",
            "shortDescription": "Select the bank from which you want to order the payment",
            "description": null,
            "order": 1,
            "iconUrl": null
        },
        {
            "type": "BNPL",
            "title": "Buy now, pay later",
            "shortDescription": "Buy now, pay later",
            "description": null,
            "order": 2,
            "iconUrl": null
        }
    ],
    "serviceID": "10000",
    "messageID": "2ca19ceb5258ce0aa3bc815e80240000",
    "gatewayList": [
        {
            "gatewayID": 106,
            "name": "PBL test payment",
            "groupType": "PBL",
            "bankName": "NONE",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/106.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:01",
            "description": "Test payment",
            "shortDescription": null,
            "descriptionUrl": null,
            "availableFor": "BOTH",
            "requiredParams": ["Nip"],
            "mcc": {
                "allowed": [1234, 9876],
                "disallowed": [1111]
            },
            "inBalanceAllowed": true,
            "minValidityTime": null,
            "order": 1,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 0.01,
                    "maxAmount": 5000.00
                }
            ],
            "buttonTitle": "Pay"
        },
		{
            "gatewayID": 701,
            "name": "Pay later with Payka",
            "groupType": "BNPL",
            "bankName": "NONE",
            "iconUrl": "https://testimages.autopay.eu/pomoc/grafika/701.png",
            "state": "OK",
            "stateDate": "2023-10-03 14:37:10",
            "description": "<div class=\"payway_desc\"><h1>Cost details</h1><p>Pay later - one-off up to 45 days (...). Offer details at: <a href="?r="https://payka.pl\" target=\"_blank\">Payka.pl</a></p></div>",
            "shortDescription": "Pay later - in one go up to 45 days or in several equal instalments",
            "descriptionUrl": null,
            "availableFor": "B2C",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": false,
            "minValidityTime": 60,
            "order": 2,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 49.99,
                    "maxAmount": 7000.00
                }
            ],
            "buttonTitle": "Pay"
        }
    ]
}

Ampliaciones adicionales

Modelos alternativos de iniciación de transacciones

Preautorización de la tarjeta

Descripción general del funcionamiento del servicio de preautorización de tarjetas

El apoyo a la preautorización de tarjetas ofrece la funcionalidad de bloquear fondos en la tarjeta del cliente durante un determinado periodo de tiempo (por ejemplo, predeterminado durante el establecimiento del bloqueo) y, a continuación, realizar un cargo. Un caso especial es cuando el bloqueo se elimina sin que se haya deducido ningún importe (por ejemplo, no se ha prestado el servicio al cliente).

Todas estas operaciones (bloqueo de fondos, adeudo, retirada del bloqueo) deben ordenarse a través de la API del Sistema de Pago Autopay. Si no hay ninguna orden de adeudo en la tarjeta durante el periodo de validez de la operación que establece el bloqueo, el Sistema liberará los fondos, notificándoselo con un mensaje estándar de Cambio de Estado de la Transacción (ITN).

Otras operaciones (cargo con éxito, colocación de un bloqueo en la tarjeta y cargo posterior) también dan lugar al envío de un mensaje ITN. Este mensaje es la única información vinculante sobre un cambio en el estado de una transacción y (utilizado junto con el servicio transactionStatus; véase la sección Consulta sobre el estado de una transacción), ayuda a gestionar la transacción sin romper la sesión con el usuario (incluso en caso de diversos problemas de red). Acuses de recibo de operaciones síncronas (nodo confirmaciónsólo sirven para presentar información preliminar sobre la orden).

Pasos de una transacción de preautorización de tarjeta

Bloqueo a petición del socio

Es posible distinguir 3 formas básicas de colocar un candado en una tarjeta:

a) Establecimiento de un bloqueo durante la autorización de un pago único (Véase Régimen A de autorización previa). El cliente rellena el formato de la tarjeta, una vez iniciada la transacción, que el Socio indica en los parámetros de inicio:

- canal de pago con tarjeta (GatewayID=1500) y

- el deseo de asegurar fondos en lugar de gravar (Mantener=verdadero)

b) Asunción de un bloqueo al iniciar un pago automático (inscripción de la tarjeta en el Servicio o la Aplicación móvil) (Véase Régimen B de autorización previa)).

TIP: todo el ciclo y todos los eventos de pago automático de acuerdo con la documentación, modificada por el momento en que la tarjeta se carga realmente y se establece el pago automático - en el modelo de preautorización, es el transactionClear operación que provoca estos eventos.

El cliente rellena el formato de la tarjeta, una vez iniciada la transacción, que el Socio indica en los parámetros de inicio:

- canal de pago con tarjeta (GatewayID=1503),

- el hecho de aceptar las normas del servicio de pago automático
proporcionada por AP (RecurringAcceptanceState=ACCEPTEDo después de la
o después de los acuerdos comerciales. PROMPT/FORCE)

- la opción de inicializar un pago automático con un posible
cargo en la tarjeta (RecurringAction=INIT_WITH_PAYMENT)

- el deseo de asegurar fondos en lugar de gravar (Mantener=verdadero)

c) Establecer un bloqueo utilizando una tarjeta previamente guardada (véase Régimen C de autorización previa).

TIP: El ciclo completo y todos los eventos de pago automático de acuerdo con la documentación, modificada por el momento en que la tarjeta se carga realmente y se establece el pago automático - en el modelo de preautorización, es el transactionClear operación que provoca estos eventos.

El cliente no rellena el formulario de la tarjeta, sino que se produce una pretransacción backend (sin redirección) en la que el socio indica en los parámetros de inicio:

- canal de pago con tarjeta (GatewayID=1503)

- indicación de una tarjeta añadida previamente (ClientHash de RPAN)

- elección del método de pago automático (RecurringAction=MANUAL)

- el deseo de asegurar fondos en lugar de gravar (Mantener=verdadero)

Cada uno de estos métodos para establecer un bloqueo da lugar a un mensaje ITN, cuyo estado indica el resultado de la autorización de la transacción. Además de la norma
estados, en caso de bloqueo de fondos, el Sistema podrá proporcionar en el estado ITN paymentStatus=ON_HOLDque confirma la creación de un bloque de fondos en la tarjeta del cliente. Además, el ITN, como norma,
contienen un identificador de transacción global (remoteID), que será necesario para la posterior carga del bloqueo establecido.

Débito en tarjeta a petición del socio

Descripción del cargo en la tarjeta a petición del socio

Una vez colocado el candado, el socio puede cursar una orden de adeudo
en una tarjeta previamente autorizada (Véase Régimen D de autorización previaPara
para ello, es necesario llamar al servicio dedicado: transactionClear (https://{gate_host}/webapi/transactionClear) con los parámetros correspondientes. Todos los parámetros se pasan a través del método POST (Content-Type: application/x-www-form-urlencoded). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. La dirección
de los parámetros pasados deben estar codificados en UTF-8.

Descripción de los parámetros disponibles para el cargo en tarjeta a petición del Socio

Confirmación de la transacción de cargo en tarjeta a petición del socio

Para que la consulta sea correcta, debe haber un encabezado HTTP definido con el contenido adecuado
enviado junto con los parámetros pasados. El archivo adjunto
debe llamarse 'BmHeader' y tener lo siguiente
valor 'pay-bm, en su totalidad debe tener el siguiente aspecto 'BmHeader: pay-bm'. En caso de que el mensaje sea válido, se devuelve (en la misma sesión HTTP) un texto con formato XML que contiene la confirmación de la operación o una descripción del error.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
	<serviceID>ServiceID</serviceID>
	<messageID>MessageID</messageID>
	<remoteOutID>RemoteOutID</remoteOutID>
	<hash>Hash</hash>
	</balancePayoff>

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
	<balancePointID>BalancePointID</balancePointID>
	<messageID>MessageID</messageID>
	<remoteOutID>RemoteOutID</remoteOutID>
	<hash>Hash</hash>
	</balancePayoff>

Descripción de los parámetros que deben devolverse para el cargo en tarjeta a petición del socio

Liberación del bloqueo a petición del socio

Una vez establecido el bloqueo, el socio puede ordenar que se libere sin deducción de fondos (Véase Régimen E de autorización previa)). Para esta operación, utilice el servicio releaseHold (Véase Anulación de una operación impagada). Al iniciarse con éxito una liberación de bloqueo (respuesta correcta a una cancelación
transacción), el Sistema proporcionará de forma asíncrona un ITN con el paymentStatus=FALLO y paymentStatusDetails=CANCELADO.

Liberación del bloqueo tras operaciones vencidas

En caso de inactividad del Socio (después de que se haya configurado el bloqueo) durante un tiempo predeterminado
período de validez, la transacción es liberada por el Sistema (sin
deduciendo los fondos) (Véase Régimen F de autorización previa). El sistema cancelará la transacción, eliminará el bloqueo y proporcionará al ITN el paymentStatus=FALLO y paymentStatusDetails=CANCELADO.

Sistemas de autorización previa

Régimen A de autorización previa: establecimiento de un bloqueo durante la autorización de un pago único

Régimen B de autorización previa: asunción de un bloqueo durante el inicio de un pago automático (inscripción de la tarjeta)LÉAME.md

Esquema C para la autorización previa: establecer un bloqueo utilizando una tarjeta previamente almacenada

Régimen D de preautorización: orden del socio de efectuar un cargo en una tarjeta previamente autorizada

Esquema E de autorización previa: Orden del socio de liberar el bloqueo (sin deducción de fondos)

Régimen F de autorización previa: liberación del bloqueo por el régimen (sin retención de fondos)

Antes de la transacción

Descripción previa a la transacción

La pretransacción amplía el modelo estándar de iniciación de transacciones gestionando necesidades específicas:

• ordenar un enlace de pago en función de los parámetros enviados

• adeudo del cliente (si no se requiere autorización adicional por parte del cliente)

• verificar la corrección del enlace de pago antes de que el Cliente sea redirigido al Sistema - la llamada da lugar a la validación de los parámetros y la configuración del Sistema

• acortar el enlace de pago - en lugar de varios/varios parámetros,
  enlace se acorta a dos identificadores.

• ocultar los datos de los parámetros sensibles del enlace de la transacción - la pre-transacción tiene lugar en el backend, y el enlace para continuar la transacción no contiene datos sensibles, sino sólo identificadores de la continuación de

• uso del SDK móvil en una variante mixta - el inicio de la transacción lo realiza el backend de la aplicación móvil, en lugar del propio SDK utilizando el token de transacción

Los casos de uso específicos de Pre-transacción, son cargas:

• BLIK 0Para utilizar este servicio, debe proporcionar GatewayID=509 y pasar el código de autorización de la transacción en el parámetro AuthorizationCode.

• BLIK 0 OneClick

• Gastos de "Pago automático
  Para utilizar este servicio, debe proporcionar uno de los siguientes datos GatewayID=509 i gatewayType="Pago automático". y los parámetros necesarios.

• Autorizaciones a través de los monederos Visa
  Para utilizar este servicio, debe proporcionar GatewayID=1511 y pasar el token codificado en el parámetro PaymentToken. A falta de token, la autorización tendrá lugar en el sitio web del Sistema.

• Autorizaciones a través de monederos Google Pay

NOTA: El servicio permite cargar la tarjeta almacenada en el monedero del cliente sin redirigirla al Sistema. A menudo, se aplica una autorización adicional en forma de 3DS (comportamiento por defecto del entorno de prueba, que puede reconfigurarse).

En el Marca blanca modelo, integrar como se describe y, a continuación, proporcionar GatewayID=1512 y el token codificado en PaymentToken parámetro. Si no hay ningún token (o un modelo distinto de Marca blanca), basta con introducir GatewayID=1512 - La autorización tendrá lugar en el sitio web del Sistema.

• Autorizaciones a través de los monederos de Apple Pay
  Para utilizar este servicio, deberá introducir GatewayID=1513. La autorización tendrá lugar en el sitio web del Sistema.

• Autorización a través del formato nativo del SDK móvil

NOTA: El servicio permite realizar el cargo en la tarjeta, cuyos datos se facilitan en el formato de tarjeta segura del SDK, y el inicio de la transacción propiamente dicha lo realiza el backend de la aplicación móvil.

Además del GatewayID correspondiente - 1500 para un pago único o 1503 para la activación de un pago automático (y otros parámetros) - el PaymentToken obtenido del SDK y el parámetro Tipo de cartera=SDK_NATIVE (descripción en la sección Iniciar una transacción con parámetros adicionales)

Llamada a una transacción previa

Un elemento necesario en el caso de una transacción previa es enviar al backend (utilizando, por ejemplo, cURL) el mensaje de inicio estándar de la transacción (véase Inicio de la transacción), con un 'BmHeader' de valor: 'pay-bm-continue-transaction-url':

Ejemplo de cabecera

'BmHeader: pay-bm-continue-transaction-url'.)

Además, se recomienda que el parámetro ClienteIP (a efectos de reclamaciones e informes).

Ejemplo de puesta en marcha previa a la transacción (PHP)

	$data = array(
	 'ServiceID' => '100047',
	 'OrderID' => ‘20161017143213’,
	 'Amount' => '1.00',
	 'Description' => 'test bramki',
	 'GatewayID' => '0',
	 'Currency' => 'PLN',
	 'CustomerEmail' => 'test@bramka.pl',
	 'CustomerIP' => '127.0.0.0',
	 'Title' => 'Test title',
	'Hash' => 0c5ca136e8833e40efbf42a4da7c148c50bf99f8af26f5c9400681702bd72056
	);

	$fields = (is_array($data)) ? http_build_query($data) : $data;

	$curl = curl_init('https://{gate_host}/test_ecommerce');
	curl_setopt($curl, CURLOPT_HTTPHEADER, array('BmHeader: pay-bm-continue-transaction-url'));
	curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
	curl_setopt($curl, CURLOPT_POST, 1);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
	$curlResponse = curl_exec($curl);
	$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	$response = curl_getinfo($curl);
	curl_close($curl);

	echo htmlspecialchars_decode($curlResponse);

Respuesta a la transacción previa - enlace para el seguimiento de la transacción

En caso de validación correcta de los parámetros (y configuración) y
la necesidad de que el cliente realice una acción adicional (seleccionar un
canal de pago - si se especifica GatewayID=0ejecución/transferencia de confirmación, introducción de código CVC/CVV, ejecución de 3DS) - se devolverá un XML con un enlace para continuar la transacción.

Ejemplo de fichero de enlace de continuación de transacción (XML)

	<?xml version="1.0" encoding="UTF-8"?>
		<transaction>
		<status>PENDING</status>
		<redirecturl>
		https://{gate_host}/payment/continue/96VSD39Z6E/L6CGP5BH
		</redirecturl>
		<orderID>20180824105435</orderID>
		<remoteID>96VSD39Z6E</remoteID>
		<hash>
		1c6eae2127f0c3f81fbed3b6372f128040729a4d4e562fb696c22e0db68dbbe1
		</hash>
	</transaction>

Objeto previo a la transacción

En transacción objeto representa la recepción o retirada de fondos de un AP, como una compra o reembolso completado.

Atributos del objeto de transacción para la pretransacción

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

Respuesta a Pre-transacción - no continuación de la transacción

En caso de validación inválida o carga fallida no se genera ningún enlace de continuación. Se devuelve un texto en formato XML (en la misma sesión HTTP) indicando el estado de procesamiento de la solicitud.

Ejemplo de estado de tramitación de una solicitud (XML)

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
	<orderID>OrderID</orderID>
	<remoteID>RemoteID</remoteID>
	<confirmation>ConfStatus</confirmation>
	<reason>Reason</reason>
	<blikAMList>
		<blikAM>
			<blikAMKey>Klucz1</blikAMKey>
			<blikAMLabel>Etykieta1</blikAMLabel>
		</blikAM>
		<blikAM>
			<blikAMKey>Klucz2</blikAMKey>
			<blikAMLabel>Etykieta2</blikAMLabel>
		</blikAM>
	</blikAMList>
	<paymentStatus>PaymentStatus</paymentStatus>
	<hash>Hash</hash>
</transaction>

Resultado previo a la transacción

Parámetros devueltos para el resultado de la transacción previa.

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

	<blikAM>
	<blikAMKey>Key1</blikAMKey>
	<blikAMLabel>Label1</blikAMLabel>
	</blikAM>
	…
	<blikAM>
	<blikAMKey>KeyN</blikAMKey>
	<blikAMLabel>LabelN</blikAMLabel>
	</blikAM>

Validación correcta de los parámetros

Si los parámetros (y la configuración) se validan correctamente y no es necesario que el cliente realice ninguna acción adicional, se devuelve una confirmación de la orden de carga.

Este es el caso cuando los datos son suficientes para efectuar un adeudo en el canal de pago en cuestión, por ejemplo: BLIK 0 sin
el código BLIK requerido (ni indicación del alias de la aplicación móvil del banco), pago recurrente, pago con tarjeta OneClick sin el CVC/CVV/3DS requerido.

Resultado

confirmation=CONFIRMADO

Validación incorrecta de los parámetros

En caso de validación incorrecta de los parámetros (y de la configuración) - se devuelve un error.

Resultado

confirmation=NO CONFIRMADO

También puede devolverse un error en caso de respuesta sincrónica del Canal de Pago (por ejemplo, un error específico de un intento de inicializar un pago automático BLIK, es decir, reason= RECURRENCY_NOT_SUPPORTED).

NOTA: También puede devolverse un error en caso de respuesta sincrónica de un Canal de Pago (por ejemplo, un error específico de un intento de inicializar un pago automático BLIK, es decir reason=RECURENCY_NOT_SUPPORTED). Otro caso conocido es también el error de validación de la dirección indicada en el parámetro de inicio CustomerEmail (INVALID_EMAIL).

Tratamiento de las respuestas para las transacciones

Solicitar los datos de una transferencia rápida

Descripción del pedido de datos de transferencia en una transacción de transferencia rápida

La Transferencia Rápida es una forma de pago que requiere que el Cliente reescriba de forma independiente los datos de transferencia proporcionados por el Sistema. El parámetro gatewayType indica de qué tipo es un determinado Canal de Pago en respuesta a la llamada al servicio "Consulta de la lista de canales disponibles actualmente".
Canales de pago". Los datos de la transferencia pueden mostrarse al Cliente:

• en el sitio web de AP (ejecución de la transacción basada en el modelo estándar de inicio de transacción descrito en la parte Inicio de la transacción)

• en el sitio del socio (a continuación se describe el procesamiento de transacciones sin redirigir al cliente al sitio AP)

Llamando a

Para la correcta transmisión del mensaje, debe enviarse un mensaje estándar de inicio de transacción al backend (p. ej.
cURL), con una cabecera 'BmHeader' de valor: pay-bm (En su totalidad, el encabezamiento debe tener el siguiente aspecto 'BmHeader: pay-bm'.). Si la cabecera está mal definida o falta, el mensaje se leerá mal. Además, se recomienda pasar el parámetro CustomerIP tal y como se describe en IP de usuario (necesario para los procesos de reclamación, notificación) y obligatorio para pasar un GatewayID (con gatewayType "Transferencia rápida"`").

Implementación del inicio de transacciones en segundo plano (PHP)

	$data = array(
	 'ServiceID' => '100047',
	 'OrderID' => '20150723144517',
	 'Amount' => '1.00',
	 'Description' => 'test bramki',
	 'GatewayID' => '71',
	 'Currency' => 'PLN',
	 'CustomerEmail' => 'test@bramka.pl',
	 'CustomerIP' => '127.0.0.0',
	 'Title' => 'Test title',
	 'ValidityTime' => '2016-12-19 09:40:32',
	 'LinkValidityTime' => '2016-07-20 10:43:50',
	 'Hash' => 'e627d0b17a14d2faee669cad64e3ef11a6da77332cb022bb4b8e4a376076daaa'
	);

	$fields = (is_array($data)) ? http_build_query($data) : $data;

	$curl = curl_init('https://{gate_host}/test_ecommerce');
	curl_setopt($curl, CURLOPT_HTTPHEADER, array('BmHeader: pay-bm'));
	curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
	curl_setopt($curl, CURLOPT_POST, 1);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
	$curlResponse = curl_exec($curl);
	$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	$response = curl_getinfo($curl);
	curl_close($curl);

	echo htmlspecialchars_decode($curlResponse);

Respuesta - detalles de la transferencia

En el caso de pagos de este tipo, el Sistema genera un conjunto de datos
necesarios para realizar una transferencia intrabancaria (y por tanto rápida) a la cuenta bancaria AP. Estos datos se colocan en la respuesta al inicio de la transacción, en un documento xml.

Respuesta del sistema de pago al inicio de la transacción (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transaction>
		<receiverNRB>47 1050 1764 1000 0023 2741 0516</receiverNRB>
		<receiverName>Autopay</receiverName>
		<receiverAddress>81-718 Sopot, ul. Powstancow Warszawy 6</receiverAddress>
		<orderID>9IMYEH2AV3</orderID>
		<amount>1.00</amount>
		<currency>PLN</currency>
		<title>9IMYEH2AV3  - weryfikacja rachunku</title>
		<remoteID>9IMYEH2AV3</remoteID>
		<bankHref>https://ssl.bsk.com.pl/bskonl/login.html</bankHref>
		<hash> fe685d5e1ce904d059eb9b7532f9e06a64c34c1ea9fcf29b62afefdb7aad7b75 </hash>
	</transaction>

Lista de parámetros devueltos para la respuesta

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración
.

NOTA: La información anterior debe utilizarse para mostrar los datos de la transferencia y redirigir al usuario a la página de acceso del banco.

BLIK 0 Pago con un clic

Descripción de los pagos BLIK 0 OneClick

Se trata de una solución dedicada a los pagos BLIK, lo que le permite pago sin necesidad de introducir su código BLIK (y sin tener que salir de la Página Web). Su iniciación con éxito en el Sistema provoca la activación/despertar automático de la aplicación móvil del banco y la presentación de la transacción al Usuario para su confirmación.

Beneficios potenciales:

• poner a disposición el primer método de pago cómodo y seguro en mCommerce que no requiere un número de tarjeta abre este segmento a nuevos clientes,

• mejor experiencia de compra para el cliente: paga más rápido y con mayor comodidad,

• frecuencia de compra y valor para el cliente a lo largo del tiempo: los clientes están más dispuestos a y compran más a menudo en aquellas tiendas en las que el proceso de compra es más cómodo,

• tasa de conversión - el servicio tiene un mayor control sobre el proceso de
  compra y proceso de pago (el cliente no lo abandona), el riesgo de
  pérdida de la cesta,

• decisión rápida de la transacción - en poco tiempo la transacción está sujeta a
  autorización, denegación o cancelación,

• El servicio tiene la posibilidad de analizar la propia fase de realización del
  pago.

La condición para que BLIK 0 OneClick se ponga a disposición del Cliente es haber sido autorizado en el
Servicio (tener una cuenta y haber iniciado sesión previamente en ella). Si, durante un pago BLIK previamente ejecutado, junto con otra
información de pago, el Servicio ha enviado un UID Alias dedicado (descripción de los
parámetros. BlikUIDKey y BlikUIDLabel en otra parte del documento
), y el Cliente, al confirmar el pago en la aplicación móvil indicó que deseaba recordar la tienda, esto dio lugar a una asociación permanente (normalmente por un período de 2 años) del Cliente del Servicio con su aplicación, es decir, registro de UID Alias. Su uso posterior dará lugar a la autorización de la transacción sin necesidad de introducir el código.

Llamar a pagos BLIK 0 OneClick

Al seleccionar un canal de pago BLIK, se recomienda no obligar al usuario a introducir un código
BLIK. En su lugar, se aconseja mostrar el hipervínculo 'Quiero introducir mi código BLIK
BLIK' bajo el botón 'Comprar y pagar' para permitir introducir el código en el primer intento (en caso de que el Cliente desee realizar un pago BLIK desde una aplicación móvil diferente a aquella en la que ha guardado previamente un Servicio determinado).

El Servicio debe realizar la transacción previa, prestando especial atención a los siguientes
on:

• especificando el parámetro GatewayID = 509 - que indica el canal de pago BLIK,

• proporcionando BlikUIDKey y BlikUIDLabel parámetros - indicando BLIK 0 OneClick Alias UID (ID de usuario) requerido por BLIK 0 OneClick. usuario)

• proporcionando la AuthorizationCode parámetro - si el cliente proporcionó el código BLIK,

• proporcionando BlikAMKey parámetro - si el Cliente especificó una etiqueta de la
  de la aplicación móvil del banco de la lista presentada en el Sitio Web,

• manejo de posibles respuestas a la pre-transacción, incluyendo el manejo de 'Respuesta - sin continuación' y errores específicos BLIK 0 OneClick:

a) error de muchas aplicaciones móviles del banco (confirmation=NO CONFIRMADO y reason=ALIAS_NONUNICA) - que muestra la lista de etiquetas devuelta en la lista de alias anteriores a la transacción (pares clave + etiqueta contenidos en la etiqueta BlikAMList ), con el fin de recuperar la clave seleccionada y proporcionarla en la estructura BlikAMKey parámetro del siguiente intento de pretransacción

(b) errores de autorización (confirmation=NO CONFIRMADO y motivo con uno de los valores: ALIAS_RECHAZADO, ALIAS_NO_ENCONTRADO, BILLETE_ERRÓNEO, BILLETE_VENCIDO, BILLETE_UTILIZADO) - mostrar el campo Código Blik, para recuperarlo y proporcionarlo en el campo AuthorizationCode parámetro del siguiente intento de pretransacción

Google Pay

Descripción

Google Pay es un sistema de pago instantáneo e intuitivo de Google. Permite al usuario completar el proceso de pago sin rellenar un formulario de tarjeta, ya que los datos de la tarjeta se almacenan de forma segura en los servidores de la empresa.

Google Pay es un producto que permite obtener datos encriptados
de la tarjeta de pago del cliente permitiendo su cargo en cuenta.

Para pagar a través de Google Pay, es necesario guardar su
tarjeta de pago en su cuenta de Google, utilizando cualquier
plataforma de Google (por ejemplo, comprando apps en Google Play) o directamente en la página web de Google Pay.

NOTA: El servicio requiere la firma previa de un contrato con el operador de la tarjeta. Para más detalles, póngase en contacto con el Departamento Comercial de Autopay.

Sistema de comunicación

Tras hacer clic en "Pagar con Google Pay", aparece un formulario de Google Pay en la página de la tienda. En él, el cliente confirma su cuenta de Google y la tarjeta con la que pretende pagar (también puede cambiar a otra tarjeta o añadir una nueva en este momento). El script transmite los datos codificados de la tarjeta en segundo plano a través de la aplicación postMessage luego la tienda tiene que aceptarlo y codificarlo mediante la función base64 y finalmente enviarlo en el archivo PaymentToken junto con los demás parámetros (datos de la transacción).

En su sitio web, la tienda debe llamar al script proporcionado por Google con los datos del procesador de pagos modificados.

TIP: Detalles en Documentación para desarrolladores de Google.

Esquema detallado de comunicación e intercambio de datos

Registro de transacciones de Google Pay

1. La tienda en su sitio web debe enviar una solicitud al sistema de pago en línea AP para recuperar los datos necesarios para procesar Google Pay (paybmApiResponse).

TIP: Un ejemplo de cómo enviar una solicitud está disponible en Pago automático de GitHub.

2. A continuación, la tienda debe llamar a la secuencia de comandos proporcionada en el archivo partes del tutorial de documentación para desarrolladores de Googleque contiene:

(a) Modificación de los datos del procesador de pagos:

const tokenizationSpecification = {
	type: 'PAYMENT_GATEWAY',
	parameters: {
		'gateway': 'bluemedia',
		'gatewayMerchantId': paybmApiResponse.acceptorId
	}
};

b) Datos devueltos por el sistema de pago en línea AP transferidos en el objeto PaymentDataRequest.merchantInfo:

PaymentDataRequest.merchantInfo = {
	merchantId: paybmApiResponse.merchantId,
	merchantOrigin: paybmApiResponse.merchantOrigin,
	merchantName: paybmApiResponse.merchantName,
	authJwt: paybmApiResponse.authJwt,
};

3. Tras hacer clic en "Pagar con Google Pay" en la página de la tienda, aparece un formulario de Google Pay en la página de la tienda. En él, el cliente confirma su cuenta de Google y la tarjeta con la que tiene la intención de pagar (también puede cambiar a otra tarjeta o añadir una nueva en esta etapa). Un script en segundo plano transmite los datos codificados de la tarjeta, que la tienda tiene que aceptar y luego codificar con la función Base64 y enviar en el archivo PaymentToken junto con el resto de parámetros de inicio de la operación (es decir, los datos de la operación del sistema de pago en línea AP - los detalles se describen en la sección Iniciar una transacción con parámetros adicionales).

TIP: Un ejemplo completo de integración con Google Pay está disponible en Pago automático de GitHub.

Información complementaria

Con el fin de mantener la integridad estética del diseño utilizado en el sitio web y la aplicación móvil, siga las orientaciones proporcionadas en la página partes de las directrices de marca de la documentación de desarrollo Google. para descripciones de estilo y botones de páginas web, y para Tutorial de documentación para desarrolladores de piezas Googledonde encontrará la información necesaria para el desarrollo de la aplicación móvil.

Apple Pay

Implementación de Apple Pay en el sitio web de la tienda.

Solicitud para ponerse en contacto con el producto de infraestructura de pagos: se necesita apoyo informático.

1. Creación de una cuenta por el Socio y obtención de un certificado de procesamiento de pagos de conformidad con el documento Configurar Apple Pay (iOS, watchOS)

- certificado de comunicación - para la llamada presentación - identificador de comerciante

- certificado de débito - certificado de procesamiento de pagos

2. Implantación de la web de acuerdo con documento Apple Pay en la Web

3. Preparación de 2 puntos finales por parte del socio, en un dominio registrado con Apple (utilizando 2 certificados de Apple):

- para iniciar la sesión

- cobrar al cliente en función del token de Apple

SUGERENCIA: El Safari (el navegador del cliente) solicita la sesión al endpoint (mencionado anteriormente) ellos entonces van a nosotros - nosotros devolvemos la sesión.

4. Procesamiento de Apple Pay

• Como parte de su registro de servicios con Apple, genere su certificado identidad comercial.
• Generar un procesamiento de pagos basado en el certificado proporcionado por el CSR AP

NOTA: Los certificados CSR de AP para aceptación y para producción difieren).

• Después de utilizarlo en el proceso de registro de Apple, proporcione al PA un certificado firmado por Apple y envíelo a través de Formulario de autopago

  CONSEJO: El cliente debe facilitar el país, la ciudad, el dominio del sitio web y el correo electrónico de la persona de contacto.

• Como parte del procesamiento de pagos en el sitio del socio, inicie una sesión API de Apple.

• A continuación, devuelva el token Autopay en el parámetro PaymentToken start.

NOTA: El descifrado del token es responsabilidad del PA.

Formato del token de pago: una porción de un objeto en formato json que devuelve la api de ApplePay:

  EncryptedPaymentData {
	  String version;
	  String data;
	  String signature;
	  Header header;
  }
  Header {
	  String ephemeralPublicKey;
	  String publicKeyHash;
	  String transactionId;
	  String applicationData;
  }
  

NOTA: Al enviar una solicitud ApplePayPaymentRequest, debe rellenar el campo applicationData con el valor orderId codificado en Base64, como se describe en la sección documento applicationData.

Widget de pago automático (modelo Marca Blanca)

Los socios que deseen incrustar algunos de los inicios de transacción directamente en su sitio / en su carrito de la compra (en el llamado modelo WhiteLabel) pueden hacerlo integrando el Widget Autopay. Actualmente, el Widget Autopay soporta la recogida de datos de la tarjeta (dentro del PaywayId 1500/1503) o Visa Mobile empieza (PaywayId PaywayId 1523)

IMPORTANTE El Socio no tiene derecho a almacenar datos de la Tarjeta (en particular, número de tarjeta, código de seguridad CVC, CVV2), con la excepción de los parámetros transferidos al procesar pagos automáticos por el PA, como se describe en esta sección.

IMPORTANTE El sitio web asociado en el que se utiliza la funcionalidad del widget Autopay debe estar cifrado y el IFRAME HTML con el widget debe estar incrustado en una dirección HTTPS con el uso de TLS.

IMPORTANTE El socio se compromete a presentar a AP, en formato electrónico,
los siguientes documentos:
a) de una sola vez (antes de la celebración del Contrato): un cuestionario SAQ-A PCI cumplimentado (Sección 2); El documento será proporcionado por AP o está disponible para su descarga en el sitio web: https://www.pcisecuritystandards.org
b) Trimestralmente: el resultado de la auditoría trimestral PCI ASV, incluido un escaneado de direcciones/redes/dominios IP externos (públicos) - IPv4 y/o IPv6. Dicha auditoría deberá ser realizada por uno de los contratistas autorizados que figuran en: https://www.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors

WidgetJS SDK de autopago

Necesitará utilizar el SDK Autopay WidgetJS para incrustar y comunicarse con el widget Autopay. En pocas palabras, todo se reducirá a incrustar el IFRAME HTML con el widget y configurar el SDK JS para manejar los mensajes (eventos) producidos cuando el Titular de la tarjeta interactúa con el widget. El mensaje final es un evento con un estado de ÉXITO_DEL_FORMULARIO incluyendo paymentToken necesario para el inicio backend de las transacciones en la API del sistema de pago en línea AP.

Incorporación del SDK

A continuación se muestran ejemplos de cómo incrustar y sindicar fácilmente un widget, utilizando el SDK Autopay WidgetJS, tanto para los canales de tarjeta como para VisaMobile.

El SDK de Autopay WidgetJS está disponible en widget-nuevo/widget-comunicacion.min.js una vez colocado en el <head>

<script src="?r=quot;https://testcards.autopay.eu/widget-new/widget-communication.min.js"></script>

Accede al objeto WidgetConnection

var widgetConfigObject = { ... };
var widget = new WidgetConnection(widgetConfigObject)

que, cuando se complementa con una configuración en forma de objeto JSON, permitirá la comunicación completa con la API de Autopay y, como resultado, garantizará que reciba un evento con un estado de ÉXITO_DEL_FORMULARIO de paymentToken.

Ejemplos de configuraciones

Ejemplo de configuración de los datos de la tarjeta

Configuración:

{ language: 'pl', amount: 1.23, currency: 'PLN', serviceId: 123456 }

PaymentToken devuelto:

{status: 'FORM_SUCCESS', message: 'ey...9', id: 'OGFlZTYyYTMtN2U2OS00MTU1LTgyNDctNmMwMGI2NjE5ZDQy'}

Ejemplo de configuración para datos VisaMobile

Configuración:

{ language: 'pl', amount: 1.23, currency: 'PLN', serviceId: 123456, merchantName: 'ShopName' }

PaymentToken devuelto:

{status: 'FORM_SUCCESS', message: 'ey...9', prefix: '48', phoneNumber: '666666666', id: 'OGFlZTYyYTMtN2U2OS00MTU1LTgyNDctNmMwMGI2NjE5ZDQy'}

Discusión detallada de la configuración del objeto WidgetConnection

Idioma

Determina la versión de idioma en la que se presentará el widget.

Nombre del campo: idioma Formato cadena Valores: por defecto enActualmente se admiten los siguientes idiomas: cs, de, el, en, es, fr, hr, hu, it, en, ro, Se, sk, sl, uk

Importe de la transacción

Importe de la transacción

Nombre del campo: importe Formato float Valores: una cantidad escrita en formato flotante, p. ej: "1,23 PLN" debería ser 1.23

importe: 1,23, divisa: "PLN", serviceId: 123456, merchantName: "ShopName".

Moneda de la transacción

Moneda de la transacción

Nombre del campo: divisa Formato cadena Valores: por defecto PLNotras divisas en un formato compatible con la configuración actual del servicio

Número de servicio

Número de servicio recibido de Autopay (depende del entorno de desarrollo)

Nombre del campo: serviceId Formato entero Valores: normalmente seis dígitos

Tipo de recurrencia (sólo para tarjetas)

Indicación del tipo de inicio de la recidiva (Sólo para el canal 1503 relacionado con el inicio de la recidiva)

Nombre del campo: recurringAction Formato cadena Valores: "INIT_WITH_REFUND", "INIT_WITH_PAYMENT".

Nombre de la tienda (sólo para VisaMobile)

Nombre mostrado al usuario en la notificación VisaMobile de la aplicación móvil del banco (Sólo para el canal VisaMobile 1523)

Nombre del campo: merchantName Formato cadena Valores: Nombre de la tienda

Widget de tarjeta - Ejemplo de aplicación en un sitio web asociado

IMPORTANTE El siguiente ejemplo de código HTML se ha creado con fines ilustrativos. Para ejecutarlo realmente en su ordenador local, el siguiente archivo HTML debe colocarse bajo algún dominio local (cualquiera, puede ser prueba.local).
Este HTML no puede ser disparado en el navegador como un archivo local porque los eventosJS intercambiados entre el IFRAME y la página son verificados para consistencia de dominio (y por lo tanto algún dominio debe estar presente).

La siguiente página pretende imitar a Front Merchant, mostrando qué elementos necesitan ser implementados para integrarse con el Widget Autopay.

En el navegador, la siguiente página de ejemplo consta de tres secciones:

• la sección superior contiene una selección de canales de pago específicos
• la sección central contiene el lugar donde se incrustará el IFRAME HTML, en el que se colocará la dirección del widget (visamobile o tarjeta estándar si es necesario)
• la sección inferior contiene un botón (inactivo por defecto) PayButon incluido con el SDK de JS para controlar el inicio del proceso en el widget (en este ejemplo, el botón sólo se activa cuando recibe un mensaje de que la validación es correcta y se han completado los datos necesarios para iniciar el proceso)

Cuando se selecciona un canal de tarjeta (payway: 1500 o 1503), se carga un formulario de tarjeta específico (basado en HTML IFRAME). Cuando se introduzcan los datos completos y válidos de la tarjeta en el widget (gracias a los eventos de validación), se activará el botón "Pagar" en el front-end del comercio.

TIP: Como puede ver en el ejemplo, también es posible soportar el canal VisaMobile en el modelo WhiteLabel. La implementación/disposición es análoga a la del widget de tarjeta, por lo que el código siguiente ya contiene ambos casos.

Validación y cumplimentación de datos

El SDK de Autopay Widget JS recibe eventos del widget cuando introduce los datos de la tarjeta ESTADO_VALIDEZ con valor válido: false

Una vez que tengamos los datos completos de la tarjeta, el último evento será ESTADO_VALIDEZ con valor válido: true

{status: 'VALIDITY_STATUS', message: null, valid: true, id: 'M2Zl...mU2'}

La activación del botón puede basarse en este evento PayButton

TIP: En el entorno de prueba, los pagos con tarjeta se basan en un simulacro de 3ds y un simulacro de autorización. Los números de las tarjetas de prueba corresponden a los distintos escenarios. La lista completa de casos de prueba figura en un apéndice aparte.

Pantalla DCC

Si el escenario y la tarjeta cumplen las condiciones para obtener una oferta DCC, aparecerá una pantalla adicional con una propuesta de conversión de divisas para el titular de la tarjeta

El titular de la tarjeta puede elegir utilizar el débito de la tarjeta en su divisa nativa o dejar la divisa original. La validación también se produce en esta pantalla.

La selección de la moneda del Titular no afectará al Comerciante ni al importe original de la transacción en sí, pero sí al importe que se cargará en la tarjeta. Si el Titular no desea beneficiarse de la oferta de conversión de divisas DCC, selecciona la divisa original (que en este caso es PLN).

Obtener una ficha

El botón debe estar vinculado al SDK de JS del widget de pago automático para que al hacer clic en él se active una llamada a la función widget.sendForm(); en el método WidgetConnection que, en última instancia, dará lugar a un ÉXITO_DEL_FORMULARIO es decir, obtener el valor de paymentToken (en el evento mensaje campo).

{status: 'FORM_SUCCESS', message: 'eyJ...n19', id: 'M2Z...ZmU2'}

Card Widget - Esquema detallado de comunicación e intercambio de datos

A continuación se muestra un diagrama detallado de la comunicación entre el comerciante, el titular de la tarjeta y los sistemas de pago Autopay en el caso de la denominada integración WhiteLabel (es decir, utilizando un widget de tarjeta)

Transferencia segura de los datos de la tarjeta al sistema Autopay y flujo completo de transacciones:

• (0) Transferencia de datos de configuración que inicia la incrustación del widget en el frontend.
• (1) Visualización del formato de tarjeta del widget incrustado en el frontend del comerciante (los datos de la tarjeta no se proporcionan en el frontend del comerciante, sino en el frontend del widget Autopay)
• (2) El titular introduce los datos de la tarjeta.
• (3) Transmisión de datos de la tarjeta utilizando una conexión TLS asegurado con un certificado de Validación Extendida al backend CardsAutopay. ** Solo aplicable si se puede ofrecer DCC ** (3a) Devolución de los datos de la propuesta de conversión a DCC ** (3b) El titular de la tarjeta decide si utiliza DCC ** (3c) Transmisión de los datos de la tarjeta introducidos previamente por el titular de la tarjeta y decisión de DCC siguiente.
• (4) WidgetJS recibe el valor `paymentToken' de CardsAutopay y lo envía al Merchant Front (vía JS).
• (5) El frente comercial recibe el token de pago del widget a través de un evento JavaScript.
• (6) El Merchant Front pasa el token de pago al Merchant Backend.
• (7) Hay un inicio de backend de Pre-transacción con paymentToken recibido anteriormente del frontend.
• (8) Autopay API devuelve el continuar-transacción URL que se utilizará para redirigir al inicio de la transacción con el usuario.
• (9) El backend del comerciante reenvía la URL de redirección al frontend del comerciante.
• (10) Redirección del titular de la tarjeta desde el sitio web del comerciante a PayAutopay para la autenticación 3DS.
• A continuación se procede a la verificación 3DS (dependiendo de la decisión del banco, puede tratarse de una verificación completa o simplificada)
• (11) Cuando el titular de la tarjeta "regresa" de la 3DS, el resultado de la autenticación se completa/recoge y autoriza.
• (12) Autopago recibe el resultado del adeudo.
• (13) El estado de la transacción se transmite al sistema de pago en línea (en segundo plano).
• (14) Redirección del titular de la tarjeta desde el sitio web de PayAutopay (tras la autenticación 3DS) de vuelta al sitio web del comerciante ocurre.
• (15) Asíncronamente al backend del Comerciante llega el mensaje ITN con el estado de la transacción ** ( en el caso de una transacción que inicie una recurrencia, el Backend del Comerciante también recibirá un mensaje adicional RPAN )

Notificación del lanzamiento de un pago automático (RPAN)

A continuación se muestra un ejemplo de una sencilla implementación HTML/JS utilizando el widget VisaMobile (y el widget de tarjeta)

{ 'status': 'FORM_SUCCESS', 'message': 'eyJrZ...', ... }

Crucial para esta integración es el lugar en el código JS que es responsable de recibir eventos, especialmente el evento con estado ÉXITO_DEL_FORMULARIOya que contiene en el mensaje campo el valor del paymentToken que el comerciante necesita pasar a su backend para completar los parámetros de la API de Autopay para permitir que el pago se inicie en Autopay.

Página de ejemplo

En el navegador, la siguiente página de ejemplo consta de tres secciones:

• la sección superior contiene iconos/botones para canales de pago específicos (utilizando representaciones gráficas de Autopay)
• la sección central contiene el marcador de posición para el IFRAME HTML, en el que se insertará la dirección del widget (visamobile o tarjeta estándar, según se requiera) en caso necesario.
• la parte inferior contiene la sección (inactiva por defecto) PayButon botón, incluido con el SDK de JS, que controla el inicio del proceso en el widget (en este ejemplo, el botón sólo se activa cuando recibe un mensaje sobre la validación correcta y la obtención de todos los datos necesarios para iniciar el proceso)

Cuando se selecciona un canal dedicado a VisaMobile, se muestra una vista dedicada (basada en HTML IFRAME), en la que la introducción del número de teléfono completo (gracias a los mensajes de validación) da lugar a la activación del botón "Pagar".

Validación y cumplimentación de datos

Al introducir un número de teléfono, el Widget JS SDK de Autopay recibe un ESTADO_VALIDEZ del widget con el valor válido: false Cuando se obtenga el número de teléfono completo, el último evento será ESTADO_VALIDEZ con el valor válido: true.

{status: 'VALIDITY_STATUS', message: null, valid: true, id: 'M2Zl...mU2'}

La activación del botón puede basarse en este evento PayButton

Obtener una ficha

El botón debe estar vinculado al SDK de JS del widget de pago automático para que al hacer clic en él se active una llamada a la función widget.sendForm(); en el método WidgetConnection que, en última instancia, dará lugar a un ÉXITO_DEL_FORMULARIO es decir, obtener el valor de paymentToken.

{status: 'FORM_SUCCESS', message: 'eyJ...n19', prefix: '48', phoneNumber: '666666666', id: 'M2Z...ZmU2'}

Widget Visa Mobile - Esquema detallado de comunicación e intercambio de datos

Iniciar transacción:

• (1) Comience introduciendo su número de teléfono en el widget VisaMobile.
• (2) Iniciar transacción en VisaMobile
• (3) Devolución desde VisaMóvil
• (4) Volver del widget a Comerciante (usando JS) el generado paymentToken.
• (5) La interfaz del vendedor transmite el código de pago a la interfaz del vendedor.
• (6) Inicio del backend Pre-transacción con paymentToken con paymentToken recibido antes.
• (7) La devolución recibe inmediatamente una respuesta XML PENDIENTE (porque se procesa en segundo plano).
• (8) El front end de Merchant presenta una pantalla esperando el resultado.

Posible cancelación de la transacción (desde el paywall de PayAutopay ):

• (9 bis) Si el usuario no recibe la notificación en la aplicación móvil o cambia de opinión, tiene la opción de cancelar la transacción desde el muro de pago.
• (9b) El sistema CardsAutopay envía una solicitud de cancelación a Visa.
• (9c) El sistema CardsAutopay recibe el resultado de la cancelación de Visa.
• (9d) El resultado de la cancelación es recibido por el sistema PayAutopay y presentado al usuario en el paywall de PayAutopay.
• (9e) En paralelo, un ITN se envía (con estado negativo) a Comerciante

Carga y devuelve el resultado:

• (10) Esperar los datos del token de pago de Visa (si el cliente de VisaMobile confirma en la aplicación móvil que desea pagar con una tarjeta específica para un pedido concreto)
• (11) A continuación figura una orden de adeudo.
• (12) Se recibe un resultado de débito positivo o negativo
• (13) El estado de la transacción se envía a la pasarela PayAutopay.
• (14) La pasarela Autopay envía el resultado de la transacción al Comerciante en forma de ITN

Descripción del código HTML JS de ejemplo (Widget de tarjeta y VisaMobile)

El siguiente código se utilizó para generar las integraciones de ejemplo mencionadas anteriormente en las secciones con ejemplos de la implementación del widget de tarjeta, así como del widget Visa Mobile

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Autopay Widget Integration Example</title>
    <script src="?r=quot;https://testcards.autopay.eu/widget-new/widget-communication.min.js"></script>
    <style>/* omitted from the example */</style>
</head>
<body>
<div>
  <form onsubmit="submitForm(event)" novalidate>
   <div class="form-group"><p>Transaction amount:</p><span>1,23 PLN</span></div>

    <!-- example implementation of a merchant-side payment channel selection mechanism -->
    <p>Choose payment method:</p>
    <ul>
      <li onclick="setPayway(event, 1500)">One time payment with card</li>
      <li onclick="setPayway(event, 1503)">Remember your card</li>
      <li onclick="setPayway(event, 1523)">Pay with VisaMobile</li>
    </ul>

    <!-- the place where the HTML IFRAME with the widget will be injected -->
    <div class="form-group" id="iframe-wrapper">
      <iframe id="iframe"></iframe>
    </div>

    <!-- call to action button in the widget -->
    <button type="submit" id="button" disabled="disabled">PayButton</button>
  </form>
</div>
<script type="text/javascript">
window.addEventListener("load', () => {
    // auxiliary variables (only for the purpose of the example)
    var currentPayway = null;
    var widget = null;

    // example configurations depending on the devlopers' environment (only for the purpose of the example)
	var AUTOPAY_CARDS_DOMAIN_ENV_PROD = 'https://cards.autopay.eu';
	var AUTOPAY_CARDS_DOMAIN_ENV_TEST = 'https://testcards.autopay.eu';

	var MERCHANTS_SERVICE_ID_ENV_PROD = 903555;
	var MERCHANTS_SERVICE_ID_ENV_TEST = 903555;

    // auxiliary method to support payment channel selection and widget embedding
    function setPayway (event, paywayId) {
        if (currentPayway === paywayId) {
            return;
        }
        currentPayway = paywayId
        removeWidget();
        disableSubmitButton();
        markActiveIcon(event);

        if (paywayId === 1500) {
            startWidget('/widget-new/partner'   , { language: 'en', amount: 1.23, currency: 'PLN', serviceId: MERCHANTS_SERVICE_ID_ENV_TEST });
            return
        }
        if (paywayId === 1503) {
            startWidget('/widget-new/partner'   , { language: 'en', amount: 1.23, currency: 'PLN', serviceId: MERCHANTS_SERVICE_ID_ENV_TEST, recurringAction: 'INIT_WITH_REFUND' });
            return
        }
        if (paywayId === 1523) {
            startWidget('/widget-new/visamobile', { language: 'en', amount: 1.23, currency: 'PLN', serviceId: MERCHANTS_SERVICE_ID_ENV_TEST,  merchantName: 'ShopName' });
			return
        }
    }

    // auxiliary method (only for the purpose of the example) setting the border on the selected payment channel
    function markActiveIcon (event) {
        var currentActive = document.querySelector('ul li.active');
        if (currentActive) {
            currentActive.classList.remove('active');
        }
        var newActive = event.target;
        if (newActive.nodeName.toLowerCase() === 'img') {
            newActive = newActive.parentNode;
        }
        newActive.classList.add('active');
    }

    // the main method responsible for embedding the IFRAME with the widget and setting up communication between it and its object representation WidgetConnection
    function startWidget (widgetVariantUrl, widgetConfig) {
        if (!widgetEvents || !WidgetConnection) {
            return;
        }
        var iframeEl = document.getElementById('iframe');
        iframeEl.src = AUTOPAY_CARDS_DOMAIN_ENV_TEST + widgetVariantUrl;
        widget = new WidgetConnection(widgetConfig)

        widget.startConnection(iframeEl).then(() => {

            // handling the main, final event containing the PaymentToken value
            widget.on(widgetEvents.formSuccess, function (message, eventData) {
                console.log('payment token event =>', eventData);
                console.log('payment token value:', message);
                // here should be a merchant API call to pass the paymentToken (message) to the merchant backend;    <<<<<<<<<<<<<<<<<
            })

            // handling validation events during user/cardholder input in the widget
            widget.on(widgetEvents.validityStatus, function (message, eventData) {
                console.log('form validation status =>', eventData);
                if (eventData.valid) {
                    enableSubmitButton();
                } else {
                    disableSubmitButton();
                }
            })

            // handling the validation event when the user/cardholder enters data in the widget
            widget.on(widgetEvents.validationResult, function (message, eventData) {
                console.log('form validation result =>', eventData);
                if (eventData.valid) {
                    enableSubmitButton();
                } else {
                    disableSubmitButton();
                }
            })

            // handling the showModal event
            widget.on(widgetEvents.showModal, function () {
                console.log('show modal');
            })
        })
    }

    // an auxiliary method (only for the purpose of the example) setting the removal of the widget for payment channels other than cards (in the example, there is a 106 PBL channel)
    function removeWidget () {
        if (!widget) {
            return;
        }
        widget.stopConnection();
    }

    // auxiliary method (only for the purpose of the example)
    function enableSubmitButton () {
        document.getElementById('button').removeAttribute('disabled');
    }

    // auxiliary method (only for the purpose of the example)
    function disableSubmitButton () {
        document.getElementById('button').setAttribute('disabled', 'disabled');
    }

    // an auxiliary method (for the purpose of the example only) that binds the call of the active pay button to the sendForm() call in the widget object
    function submitForm (event) {
        event.preventDefault();
        if (!widget || widget.invalid) {
            return;
        }
        disableSubmitButton();
        widget.sendForm();
    }

    window.setPayway = setPayway;
    window.submitForm = submitForm
});
</script>
</body>
</html>

Pago automático

Descripción del pago automático

Los pagos automáticos son una forma extremadamente cómoda y segura de realizar transacciones recurrentes. Consiste en el cobro automático de los créditos del cliente en sus fechas de pago. Primero hay que activar el servicio. En el caso de las tarjetas, esto se hace redirigiendo al cliente al formulario de activación del servicio. En el caso de BLIK mientras que mediante la aceptación de un pago automático en la Aplicación Móvil. Una vez autorizada con éxito dicha transacción de activación, la AP transmite al Partner un mensaje estándar sobre el cambio de estado de la transacción (ITN) y un mensaje sobre la activación del servicio de pago automático (RPAN). El mensaje RPAN contiene el campo clientHashcon el que el socio identificará el pago automático específico durante los cargos posteriores y la desactivación del servicio.

NOTA: Antes de iniciar transacciones recurrentes, el Socio debe familiarizarse con los requisitos de las organizaciones de pago VISA y Mastercard, así como con las normas de Autopay. Estos requisitos están destinados a reducir el riesgo de devoluciones de cargo y garantizar el cumplimiento de las regulaciones de la industria. Encontrará información detallada en el artículo: Requisitos para los pagos automáticos.

Todas las transacciones dentro del ciclo de vida de un pago automatizado
(activación y débito) se llevan a cabo dentro de unos
Canales de pago (BLIK - GatewayID=522, Tarjetas de pago - GatewayID = 1503) i gatewayType="Pago automático".. En el caso de integrar
pagos automáticos BLIK, es posible especificar (en los datos facilitados antes de
integración) la duración de los pagos automáticos activados
(ilimitado por defecto) o especificarlo en la operación de inicialización
(parámetro RecurringValidityTime).

Activación del pago automático

La activación del pago automático consta de una transacción de activación de autorización, comunicación ITN y RPAN. Una vez recibido el RPAN, el Socio está preparado para realizar adeudos periódicos (o con un solo clic).

Se trata de la activación del servicio de pago automático durante
pago por un servicio/bien (por tanto RecurringAction=INIT_WITH_PAYMENT y liquidación de la operación al Socio).

Proceso de activación del servicio de pago automático

El mensaje ITN enviado tras un pago automático es similar a los recibidos tras pagos únicos (sólo se amplía por el RecurringData y, para los pagos con tarjeta CardData). Los otros dos elementos del proceso de activación del servicio son el inicio de la transacción y el RPAN.

Mensaje automático de inicio de transacción

El proceso de activación del servicio se inicia desde el Partner Site iniciando la transacción con el parámetro RecurringAction le permite controlar el comportamiento del Sistema:

(a) valor INIT_CON_PAGO - corresponde a la activación del servicio de pago automático al pagar un servicio/mercancía (se carga en la tarjeta o cuenta el importe adeudado, y los fondos del pago se transfieren al Socio); en la lista de canales de pago disponibles, el Sistema presenta sólo los pagos automáticos (a menos que se haya seleccionado un canal de pago en el Servicio),

(b) valor INIT_WITH_REFUND - corresponde a la activación del servicio de pago automático fuera del proceso de pago del servicio/mercancía (se carga en la tarjeta o cuenta el importe de 1 PLN, seguido del reembolso automático de los fondos a la cuenta del Cliente); en la lista de canales de pago disponibles, el Sistema presenta sólo los pagos automáticos (a menos que se haya seleccionado un canal de pago en el Sitio),

c) sin parámetro (o vacío) - a menos que se seleccione un canal de pago en el Sitio, el Sistema mostrará todos los canales de pago disponibles para el Sitio (incluidos los automáticos) y dejará que el Cliente decida: pago único o inicio del pago automático. Si el Cliente elige el pago automático, la transacción se facturará al Socio de la forma estándar (y el RecurringAction=INIT_WITH_PAYMENT en RPAN).

NOTA: No se permite iniciar transacciones de activación con el canal de pago automático seleccionado pero sin la RecurringAction seleccionada.

En algunos casos (si se deduce de la respuesta del método legalData) también es necesario especificar los parámetros RecurringAcceptanceState (con el valor ACEPTADOlo que significa que el cliente ha leído y aceptado las condiciones del pago automático en el Servicio asociado) y RecurringAcceptanceID.

La activación del servicio de tarjeta de pago automático se realiza en los formatos facilitados por AP. El cliente debe introducir los datos de la tarjeta: nombre, apellidos, número de tarjeta, fecha de caducidad y código CVV. En el caso del pago automático desde una cuenta bancaria (BLIK), la autorización se realiza sin introducir los datos de la tarjeta: por ejemplo, con el código BLIK (transportado en los parámetros de inicio en AuthorisationCode), o a través de BLIK OneClick Alias (transportado en los parámetros de inicio en BlikUIDKey/BlikUIDLabel).

Una vez autorizada la transacción, el Sistema AP transmite al Servicio Asociado un mensaje de cambio de estado de la transacción (ITN) y un mensaje sobre la activación del servicio de pago automático (RPAN). El mensaje RPAN está dedicado a los eventos de activación del pago automático y contiene su identificador (ClientHash), que el Servicio Asociado utilizará durante los adeudos posteriores y la desactivación del servicio. El RPAN también contiene información sobre una acción en el proceso de pago automático (RecurringAction, descrita anteriormente).

Notificación del lanzamiento de un pago automático (RPAN)

Tras la recepción de un estado de pago positivo para la activación del pago automático, se envía un mensaje específico al Servicio. Esta notificación consiste en el envío por parte del Sistema AP de un documento XML que contiene datos sobre el pago automático activado. El documento se envía a través del protocolo HTTPS (puerto 443 por defecto), utilizando el método POST, como un parámetro HTTP llamado recurring. Este parámetro se almacena utilizando el mecanismo de encriptación de transporte Base64.

Formato de documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<recurringActivation>
		<serviceID>ServiceID</serviceID>
		<transaction>
			<orderID>OrderID</orderID>
			<remoteID>RemoteID</remoteID>
			<amount>999999.99</amount>
			<currency>PLN</currency>
			<gatewayID>GatewayID</gatewayID>
			<paymentDate>YYYYMMDDhhmmss</paymentDate>
			<paymentStatus>PaymentStatus</paymentStatus>                 
			<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
			<startAmount>999998.99</startAmount>
			<invoiceNumber>InvoiceNumber</invoiceNumber>
			<customerNumber>CustomerNumber</customerNumber>
			<customerEmail>CustomerEmail</customerEmail>
			<customerPhone>CustomerPhone</customerPhone>
		</transaction>
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<expirationDate>YYYYMMDDhhmmss</expirationDate>
		</recurringData>
		<cardData>
			<index>Index</index>
			<validityYear>ValidityYear</validityYear>
			<validityMonth>ValidityMonth</validityMonth>
			<issuer>Issuer</issuer>
			<bin>BIN</bin>
			<mask>Mask</mask>
		</cardData>
		<hash>Hash</hash>
	</recurringActivation>

Valores de los elementos: orderID, serviceID, importe pertenecientes a cada pago automático activado son idénticos a los valores de los campos correspondientes proporcionados por el Servicio al iniciar el pago de inicialización respectivo.

Descripción de los parámetros devueltos para activar el pago automático

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

TIP: Elemento hash (mensaje) se utiliza para autenticar
el documento. Para una descripción de cómo se calcula el hash, véase la sección Seguridad de las transacciones.

Respuesta a la notificación

En respuesta a la notificación, se espera un estado HTTP de 200 (OK) y un texto en formato XML (no codificado en Base64), devuelto por el Servicio Asociado en la misma sesión HTTP, que contenga un acuse de recibo del mensaje.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Elemento de confirmación del pago automático

En confirmación se utiliza para transmitir el estado de la verificación de la autenticidad de la transacción por parte del Servicio asociado. El valor del elemento se determina comprobando la exactitud del valor del elemento serviceID comparando los valores del parámetro orderID y importe en el mensaje de notificación y en el mensaje que inicia la transacción, y verificar la coherencia del hash calculado a partir de los parámetros del mensaje con el valor pasado en el campo hash del mensaje.

Se proporcionan dos valores para el elemento confirmación:

a) CONFIRMADO - los valores de los parámetros en ambos mensajes y el parámetro hash coinciden: la transacción es auténtica;

b) NO CONFIRMADO - los valores de los dos mensajes son diferentes o un hash no coincide - transacción no auténtica;

TIP: En hash (en el mensaje de respuesta) se utiliza para autenticar la respuesta y se calcula a partir de los valores de los parámetros de respuesta. Para obtener una descripción de cómo se calcula el hash, consulte la sección Seguridad de las transacciones.

Si no hay una respuesta correcta a las notificaciones enviadas, el sistema de pago en línea hará otro intento de transmisión una vez transcurrido un tiempo especificado. El servicio del Socio debe realizar su propia lógica de negocio (por ejemplo, lanzar un servicio de pago automático, envío de correo, etc.) sólo después de que el primer mensaje de un determinado ClientHash.

Esquema de reintentos de mensajes ITN/ISTN/IPN/RPAN/RPDN

A continuación figura un diagrama que describe la renovación programada de los mensajes (nos reservamos, no obstante, la posibilidad de renovar cualquiera de ellos en cualquier momento).

NOTA: La repetición continua de un mensaje idéntico por parte del Sistema indica una falta de respuesta o una respuesta incorrecta por parte del Servicio, y requiere que el Socio diagnostique urgentemente la causa.

Cargo por pago automático

Recepción correcta del identificador de servicio (ClientHash), hace que el Socio esté preparado para cobrar automáticamente al Cliente los bienes/servicios adquiridos en el Servicio. El proceso consta de transacciones y comunicación ITN.

A continuación se muestra el proceso de cobro automático al cliente por el servicio/mercancía (así RecurringAction=MANUAL/AUTO y liquidación de la operación al Socio).

El mensaje ITN enviado tras un pago automático es similar a los recibidos tras pagos puntuales. Sólo se amplía con el nodo RecurringData y (para pagos con tarjeta) CardData.

Mensaje de inicio de operación de pago automatizada

Para ejecutar un cargo automático, el Servicio asociado debe ejecutar una transacción previa con un ClientHash parámetro, coherente con el servicio de pago automático activado previamente (procedente del RPAN), con un RecurringAcceptanceState parámetro de NOT_APPLICABLE y el valor correspondiente del RecurringAction parámetro:

a) AUTO - pago periódico (débito sin participación del cliente),

b) MANUAL - pago en un clic (débito ordenado por
el cliente, llamado OneClick).

NOTA: La participación del cliente en la opción MANUAL, suele limitarse a llamar a un mensaje (seleccionando en el Servicio la opción de pagar con la tarjeta almacenada). En la gran mayoría de los casos, se requiere una autorización adicional en el banco (en forma de código 3DS o CVC). Entonces, en lugar de un cargo (y el estado del pedido en respuesta a la pretransacción), el Sistema devolverá un enlace para continuar - este es el comportamiento por defecto del sistema en el entorno de prueba. Para probar el escenario de carga sin necesidad de autorización adicional, debe declararse la necesidad de cambiar la configuración del Sistema durante la duración de la prueba.

NOTA: Opción no disponible para los pagos automáticos BLIK (BLIK
OneClick).

Desactivación del servicio

El socio puede desactivar el servicio de pago automático en cualquier momento. El proceso puede consistir en un mensaje ordenando la desactivación y un mensaje RPDN (dedicado a eventos de cancelación del servicio de pago automático).

También puede ocurrir que la cancelación del servicio se inicie desde el lado del PA (por ejemplo, a petición del Cliente, banco u organización de tarjetas). En tal situación, el Sistema también proporcionará un mensaje RPDN.

Mensaje de desactivación del pago automático

El servicio puede desactivarse mediante un mensaje específico. Todos los parámetros se transmiten mediante el método POST (a la dirección https://{gate_host}/desactivar_recurrente). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros para desactivar el pago automático

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

NOTA: El elemento Hash (mensaje) se utiliza para autenticar el documento. El valor de este elemento se calcula como el valor de una función hash a partir de una cadena que contiene los valores concatenados de todos los campos del documento y la clave compartida adjunta.

Respuesta

En respuesta a la notificación, se devuelve un texto con formato XML en la misma sesión HTTP, que contiene un acuse de recibo.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
				<reason>Reason</reason>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Confirmación de elementos

En confirmación se utiliza para transmitir el estado de verificación de la autenticidad de la operación por parte del Servicio. El valor del elemento se determina comprobando la corrección de los valores de los parámetros serviceID y clientHash con los proporcionados en el mensaje RPAN al inicio de un determinado pago de activación, así como verificar la coherencia del hash calculado a partir de los parámetros del mensaje con el valor proporcionado en el campo Hash.

Se proporcionan dos valores para el elemento confirmación:

a) CONFIRMADO - los valores de los parámetros son correctos y el parámetro Hash es coherente: la operación es auténtica;

b) NO CONFIRMADO - los valores de ambos mensajes son incorrectos o Hash no coincide - operación no auténtica;

NOTA: El elemento hash (en el mensaje de respuesta) se utiliza para autenticar la respuesta y se calcula a partir del valor de los parámetros de respuesta. El valor de este elemento se calcula como el valor de una función hash a partir de una cadena que contiene los valores concatenados de todos los campos del documento (sin etiquetas) y la clave compartida adjunta. Para una descripción de la función Seguridad de las transacciones.

Notificación de desactivación del pago automático (RPDN)

Cuando se desactiva el pago automático para un determinado ClientHash, se envía un mensaje dedicado en forma de documento XML, es a través del protocolo HTTPS (puerto 443 por defecto), utilizando el método POST, con un parámetro denominado recurrente. Este parámetro se almacena utilizando el mecanismo de codificación de transporte Base64.

Formato de documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<recurringDeactivation>
		<serviceID>ServiceID</serviceID>
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<deactivationSource>DeactivationSource</deactivationSource>
			<deactivationDate>DeactivationDate</deactivationDate>
		<recurringData>
		<hash>Hash</hash>
	</recurringDeactivation>

Los valores de los elementos: serviceID, clientHash relativos a cada pago cíclico desactivado, son idénticos a los valores de los campos correspondientes, dados en el mensaje RPAN al inicio del respectivo pago de inicialización.

Descripción de los parámetros devueltos

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

NOTA: El elemento hash (mensaje) se utiliza para autenticar el documento. El valor de este elemento se calcula como el valor de una función hash a partir de una cadena que contiene los valores concatenados de todos los campos del documento y una clave compartida adjunta.

Acuse de recibo del mensaje

En respuesta a la notificación, se espera un estado HTTP 200 (OK) y un texto en formato XML (no codificado en Base64), devuelto por el Servicio en la misma sesión HTTP, que contenga un acuse de recibo del mensaje.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Confirmación de elementos

En confirmación se utiliza para transmitir el estado de verificación de la autenticidad de la operación por parte del Servicio. El valor del elemento se determina comprobando la corrección de los valores de los parámetros serviceID y clientHash con los proporcionados en el mensaje RPAN al inicio de un determinado pago de inicialización, y verificar la coherencia del hash calculado a partir de los parámetros del mensaje con el valor proporcionado en el campo hash.

Se proporcionan dos valores para el elemento confirmación:

a) CONFIRMADO - los valores de los parámetros son correctos y los parámetros hash son coherentes - operación auténtica

b) NO CONFIRMADO - los valores de ambos mensajes no son válidos o el hash no coincide - operación no auténtica

NOTA: El elemento hash (en el mensaje de respuesta) se utiliza para autenticar la respuesta y se calcula a partir de los valores de los parámetros de respuesta. Para una descripción de cómo se calcula el hash, consulte la sección Seguridad de las transacciones.

En ausencia de una respuesta correcta a las notificaciones enviadas, el Sistema realizará nuevos intentos de comunicar el último estado de la transacción una vez transcurrido el tiempo especificado. El Servicio Asociado debe realizar su propia lógica de negocio (por ejemplo, correo electrónico de confirmación), sólo después del primer mensaje sobre un determinado estado de pago.

TIP: Le recomendamos que lea también las secciones Supervisión de las comunicaciones
ITN/ISTN/IPN/RPAN/RPDN y Esquema de reintentos de mensajes ITN/ISTN/IPN/RPAN/RPDN.

Iniciar una transacción con parámetros adicionales

El inicio de las transacciones puede realizarse con los parámetros adicionales que se indican en los apartados siguientes.

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

Cesta de productos

Descripción de la cesta de productos

La cesta de productos se envía como un parámetro (método POST) llamado Productos. Su valor se codifica con el protocolo de transporte Base64.

Formato antes de la codificación (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<productList>
		<product>
			<subAmount>SubAmount1</subAmount>
			<params>Params1</params>
		</product>
		<product>
			<subAmount>SubAmount2</subAmount>
			<params>Params2</params>
		</product>
		…
		<product>
			<subAmount>SubAmountN</subAmount>
			<params>ParamsN</params>
		</product>
	</productList>

En productList debe contener al menos 1 producto cada elemento producto debe contener un nodo subImporte y parámetros elemento cada uno.

En subImporte debe contener un importe de producto positivo (el separador decimal es un punto seguido de dos cifras de céntimo). La suma de los importes de los productos subsiguientes debe ser igual al importe especificado en el elemento Importe (importe de la transacción).

Si no se cumplen las condiciones anteriores, el Sistema devolverá un error.

Parámetros de los elementos

En parámetros puede utilizarse para transmitir información específica del producto. Los nombres de los parámetros y su significado están sujetos a un acuerdo en forma de trabajo cada vez durante la integración.

Ejemplos de parámetros de productos y su significado a continuación.

• En este caso, el nodo contiene el nombre del producto:

		<params>
			<param name="productName" value="Product name 1" />
		</params>

• En este caso, el nodo contiene dos valores asignados al producto, que pueden denotar, por ejemplo, el tipo de producto y su nombre:

		<params>
			<param name="productType" value="ABCD" />
			<param name="productName" value="Product name 1" />
		</params>

• En caso de que el Servicio tenga saldo en el Sistema, y prevea realizar devoluciones al Cliente de todo o parte del importe pagado por el producto designado, está obligado a transferir en el producto su único identificador (parámetro denominado productID con tipo string{1,36} (caracteres alfanuméricos latinos y caracteres permitidos: _ y -)):

		<params>
			<param name="productID" value="12456" />
		</params>

• Si el Socio utiliza una estructura ampliada (múltiples puntos de liquidación), está obligado a transmitir en cada producto el identificador del punto de liquidación (parámetro denominado idBalancePoint con tipo integer{1,10}):

		<params>
			<param name="idBalancePoint" value="12456" />
		</params>

• En caso de que el Socio utilice la facturación TRANSFERENCIA_MASIVAes decir

  • cada transacción se liquida inmediatamente después del depósito y

  • las liquidaciones se realizan a nivel de producto/punto de facturación (es decir, después del ingreso se realizan tantas transferencias de liquidación como productos haya en la cesta), y

  • no se han establecido datos de facturación fijos (o no todos los datos de facturación están establecidos rígidamente en la configuración de facturación),

El socio debe proporcionar en cada producto los datos que faltan para la facturación de ese producto. Los parámetros disponibles que constituyen los datos son:

• clienteNRB - número de cuenta de destino para la facturación.
  Formato NRB (26 dígitos con suma de comprobación). Si durante la integración se establece el uso de cuentas no polacas, entonces el campo transfiere IBAN y el rango de datos esperado del campo cambia a: caracteres alfanuméricos latinos (mín. 15, máx. 32 caracteres). La especificación de valores en el formato IBAN dará lugar a la necesidad de especificar en el producto también los parámetros swiftCode, foreignTransferMode.

• título - El título de la transferencia de liquidación del producto. En determinados casos, independientemente de AP, el título de la transferencia de liquidación puede ser modificado independientemente por el Banco desde el que se produjo la liquidación.
  Caracteres alfanuméricos latinos aceptables y caracteres de la gama:

• receiverName - el nombre del destinatario de la transferencia que liquida el producto.
  Caracteres alfanuméricos latinos aceptables y caracteres de la gama:

Ejemplo de aplicación de parámetros a un producto:

	<params>
		<param name="customerNRB" value="83109010980000000107285707" />
		<param name="title" value="Settlement of product X" />
		<param name="receiverName" value="John Smith" />
	</params>

• En el modelo Marketplace, el Socio está obligado a proporcionar un identificador del punto de facturación (parámetro denominado idBalancePoint de tipo entero{1,10}). Esto también se aplica al abono de saldo del punto de liquidación.

Ejemplo de parámetros de la cesta:

	<params>
		<param name="idBalancePoint" value="12456" />
		<param name="productName" value="Balance transfer for Autopay" />
	</params>

Visualización de la cesta de productos en la pantalla de selección del canal de pago

Si durante las conversaciones relativas a la cesta de productos se ha establecido que su resumen se mostrará en la página del Sistema (pantalla de selección del Canal de Pago), se pueden especificar las etiquetas de cada parámetro utilizado en la cesta. El Sistema puede utilizar la etiqueta por defecto del parámetro o puede adoptarla al inicio de la transacción.

El valor del título se mostrará antes del valor del parámetro del producto.

Ejemplo de atributo title

	<params>
		<param name="productName" value="Product name 1" title="Name"/>
		<param name="productType" value="ABCD" title="Type"/>
	</params>

Opciones adicionales de comunicación en línea para el socio

Campos adicionales en el mensaje ITN/IPN de la transacción entrante

Descripción

Las notificaciones instantáneas de un cambio en el estado de una transacción pueden incluir campos adicionales (véase Sistemas de autorización previa). Su aparición es una
cuestión de configuración, determinada durante la integración (por defecto sólo se envía el nodo customerData).

El hecho de que se trate de un mensaje ITN o IPN viene determinado únicamente por la presencia de un nodo producto.

Lista completa de campos adicionales del mensaje NIT/NIP

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

NOTA: Para contar los valores Hash, el valor atributos del parámetros.producto se toman los nodos.

Ejemplo de mensaje ITN/IPN con parámetros adicionales (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
	  <serviceID>ServiceID</serviceID>
	  <transactions>
	  <transaction>
		<orderID>OrderID</orderID>
		<remoteID>RemoteID</remoteID>
		<amount>999999.99</amount>
		<currency>PLN</currency>
		<gatewayID>GatewayID</gatewayID>
		<paymentDate>YYYYMMDDhhmmss</paymentDate>
		<paymentStatus>PaymentStatus</paymentStatus>                 
		<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
		<addressIP>127.0.0.1</addressIP>
		<customerNumber>1111111</customerNumber>
		<title>title</title>
		<customerData>
		  <fName>fName</fName>
		  <lName>lName</lName>
		  <streetName>streetName</streetName>
		  <streetHouseNo>streetHouseNo</streetHouseNo>
		  <streetStaircaseNo>streetStaircaseNo</streetStaircaseNo>
		  <streetPremiseNo>streetPremiseNo</streetPremiseNo>
		  <postalCode>postalCode</postalCode>
		  <city>city</city>
		  <nrb>nrb</nrb>
		  <senderData>senderData</senderData>    
		</customerData>
		<verificationStatus>verificationStatus</verificationStatus>
		<verificationStatusReasons>
		   <verificationStatusReason>reason1</verificationStatusReason>
		   <verificationStatusReason>reason2</verificationStatusReason>
		   <verificationStatusReason>reason3</verificationStatusReason>
		</verificationStatusReasons>
		<startAmount>999998.99</startAmount>    
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<expirationDate>YYYYMMDDhhmmss</expirationDate>
		</recurringData>
		<cardData>
			<index>Index</index>
			<validityYear>ValidityYear</validityYear>
			<validityMonth>ValidityMonth</validityMonth>
			<issuer>Issuer</issuer>
			<bin>BIN</bin>
		</cardData>
		<product>
			<subAmount>SubAmount</subAmount>
			<params>
				<param name="idBalancePoint" value="idBalancePoint"/>
				<param name="invoiceNumber" value="invoiceNumber"/>
				<param name="customerNumber" value="customerNumber"/>
				<param name="subAmount" value="SubAmount"/>
			</params>
		</product>
	  </transaction>
	  </transactions>
	  <hash>Hash</hash>
	</transactionList>

Descripción detallada del cambio en el estado de verificación - para una transacción completada con éxito (resultado positivo o negativo)

Descripción detallada del cambio de estado de verificación - para una transacción no completada correctamente

Estados detallados de las transacciones

El mensaje ITN para una transacción entrante contiene, además del estado del pago (campo paymentStatus), una descripción detallada de este estado (campo paymentStatusDetails). Esta descripción debe ser tratada como informativa, la lista de sus valores permitidos crece constantemente y la aparición de nuevos valores no puede implicar la no aceptación del mensaje ITN.

Valores de estado de la transacción - Estados generales (independientes del canal de pago)

Valores de estado de las transacciones - Estados de las tarjetas

Valores de estado de la transacción - Estados específicos de la transacción BLIK

Notificación inmediata de un cambio en el estado del producto (IPN)

En el caso de un socio que utilice estructura extendida (Cesta de productos con múltiples puntos de facturación), el Sistema proporciona notificaciones independientes de los cambios de estado de cada producto. Este servicio tiene sentido si los puntos de facturación individuales deben recibir sus propias notificaciones. En este caso, la configuración de la IPN (dirección para las notificaciones, campos a incluir en el mensaje, etc.) se almacena precisamente en el nivel de configuración del punto de facturación. La estructura de la IPN es similar a la de la ITN (ampliada únicamente por un producto similar al descrito en la sección Campos adicionales en el mensaje ITN/transacción de entrada IPNcompletado únicamente por la repetición del subImporte en los parámetros). Ejemplo de IPN en la subsección Campos adicionales en el mensaje ITN/IPN de una transacción de entrada).

Notificación inmediata de un cambio en el estado de una operación de liquidación (ISTN)

Es posible proporcionar mensajes sobre todos los desembolsos (liquidaciones, desembolsos de saldos y reembolsos) realizados por el Sistema como parte del servicio de pago. Dado que el servicio no está habilitado por defecto, la necesidad de este servicio, junto con la dirección de correo ISTN, debe ser solicitada por el Socio durante la determinación de los requisitos.

En caso de iniciarse con éxito la comunicación ISTN, el Sistema transmite inmediatamente notificaciones del hecho de la ordenación de la operación de liquidación (reintegros/devoluciones, en su caso) y del cambio de su estado. Las confirmaciones se envían, a la dirección en el servidor de servicio del Socio establecida durante la configuración de adición del Servicio del Socio:

https://shop_name/receipt_of_settlement_information

Esta notificación consiste en el envío por parte del Sistema de un documento XML que contiene los nuevos estados de las transacciones. El documento se envía a través del protocolo HTTPS (puerto 443 por defecto). El documento se envía mediante el método POST, como un parámetro HTTP denominado transacciones. Este parámetro se almacena utilizando el mecanismo de codificación de transporte Base64.

Formato de documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
		<serviceID>ServiceID</serviceID>
		<transactions>
			<transaction>
				<isRefund>true/false</isRefund>
				<productID>ProductID</productID>
				<orderID>OrderID</orderID>
				<orderOutID>OrderOutID</orderOutID>
				<remoteID>RemoteID</remoteID>
				<remoteOutID>RemoteOutID</remoteOutID>
				<amount>999999.99</amount>
				<currency>PLN</currency>
				<transferDate>YYYYMMDDhhmmss</transferDate>
				<transferStatus>TransferStatus</transferStatus>                 
				<transferStatusDetails>TranasferStatusDetails</transferStatusDetails>
				<title>Title</title>
				<receiverBank>ReceiverBank</receiverBank>      
				<receiverNRB>ReceiverNRB</receiverNRB>
				<receiverName>ReceiverName</receiverName>
				<receiverAddress>ReceiverAddress</receiverAddress>
				<senderBank>SenderBank</senderBank>
				<senderNRB>SenderNRB</senderNRB>
			</transaction>
		</transactions>
		<hash>Hash</hash>
	</transactionList>

Parámetros devueltos

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

Respuesta a la notificación

En respuesta a la notificación, se espera un texto en formato XML (no codificado en Base64), devuelto por el Servicio Asociado en la misma sesión HTTP, que contiene un acuse de recibo del estado de la transacción.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<transactionsConfirmations>
			<transactionConfirmed>
				<remoteOutID>RemoteOutID</remoteOutID>
				<confirmation>Confirmation</confirmation>
			</transactionConfirmed>
		</transactionsConfirmations>
		<hash>Hash</hash>
	</confirmationList>

En confirmación se utiliza para transmitir el estado de la verificación de la autenticidad de la transacción por parte del Servicio asociado. El valor del elemento se determina comprobando la exactitud del valor del elemento serviceID así como verificar que el hash calculado coincide con el valor pasado en el campo hash.

Se proporcionan dos valores para este elemento:

a) CONFIRMADO - el parámetro hash es consistente - la transacción auténtica;

b) NO CONFIRMADO - el parámetro hash es inconsistente - transacción no auténtica;

Si no hay una respuesta correcta a las notificaciones enviadas, el Sistema hará nuevos intentos de comunicar un nuevo estado después de un tiempo especificado. El Servicio Asociado debe realizar su propia lógica de negocio, sólo después del primer mensaje sobre un determinado estado de pago.

TIP: Merece la pena echar un vistazo a Esquema de reintentos de mensajes ITN/ISTN/IPN/RPAN/RPDN.

Descripción detallada del comportamiento y cambio de los estados de liquidación (transferStatus)

En el modelo básico, el Sistema sólo proporcionará un estado de ÉXITO, sin embargo, es posible una notificación más precisa. La opción completa debe notificarse durante la integración e implica el siguiente patrón de transiciones
estados.

ZUna orden para una operación de liquidación envía un estado de PENDIENTE. Más tarde, el sistema entregará ÉXITO o FALLO. Para una transacción en la que ÉXITO ya no debería producirse un cambio de estatus a FALLO. Sin embargo, puede haber un cambio en el estado detallado (los mensajes de cambio de estado detallado posteriores son sólo informativos y no deben implicar la reejecución de ninguna lógica de negocio).

En casos especiales (por ejemplo, un error en el banco), una transacción que inicialmente estaba confirmada puede pasar a ejecutarse de nuevo y, por tanto, cambiar su estado a PENDIENTE y de vuelta a ÉXITO.

Otro caso especial podría ser un FALLO (por ejemplo, después de un error interno del sistema), se sustituye por un estado ÉXITO estado.

Servicios adicionales

Consulta de la lista de canales de pago disponibles actualmente

Descripción

Para construir una vista de selección de medios de pago en el Sitio Web, el Sistema permite consultar a distancia la lista actual de canales de pago. Para ello, llame al método gatewayList (https://{gate_host}/gatewayList/v3) con los parámetros pertinentes (en formato JSON). Todos los parámetros se transmiten utilizando la tecnología REST. El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros disponibles

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

Ejemplo de mensaje

{
	"ServiceID": 47498,
	"MessageID": "11111111111111111111111111111111",
	"Currencies":"PLN,EUR",
	"Language": "PL",
	"Hash": "306519f632e53a5e662de0125da7ac3f8135c7e4080900f2b145d4b25ff1b55d"
}

Respuesta a la solicitud

En respuesta a una solicitud, se devuelven 2 listas de definiciones en la misma sesión HTTP:

(a) Canales de pago (nodo gatewayList)

(b) Grupos de pago (nodo gatewayGroups)

A continuación encontrará una descripción detallada del mensaje devuelto:

Ejemplo de respuesta

{
    "result": "OK",
    "errorStatus": null,
    "description": null,
    "gatewayGroups": [
        {
            "type": "PBL",
            "title": "Internet transfer",
            "shortDescription": "Select the bank from which you want to order the payment".,
            "description": null,
            "order": 1,
            "iconUrl": null
        },
        {
            "type": "FR",
            "title": "Transfer details",
            "shortDescription": "Order a transfer using the details provided",
            "description": null,
            "order": 2,
            "iconUrl": null
        },
        {
            "type": "BNPL",
            "title": "Buy now, pay later",
            "shortDescription": "Buy now, pay later",
            "description": null,
            "order": 3,
            "iconUrl": null
        }
    ],
    "serviceID": "10000",
    "messageID": "2ca19ceb5258ce0aa3bc815e80240000",
    "gatewayList": [
        {
            "gatewayID": 106,
            "name": "PBL test payment",
            "groupType": "PBL",
            "bankName": "NONE",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/106.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:01",
            "description": "Test payment",
            "shortDescription": null,
            "descriptionUrl": null,
            "availableFor": "BOTH",
            "requiredParams": ["Nip"],
            "mcc": {
                "allowed": [1234, 9876],
                "disallowed": [1111]
            },
            "inBalanceAllowed": true,
            "minValidityTime": null,
            "order": 1,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 0.01,
                    "maxAmount": 5000.00
                }
            ],
            "buttonTitle": "Pay"
        },
        {
            "gatewayID": 9,
            "name": "Transfer from another bank",
            "groupType": "FR",
            "bankName": "BANK TEST",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/9.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:02",
            "description": "<b>Fast transfer</b>",
            "shortDescription": "Fast transfer",
            "descriptionUrl": null,
            "availableFor": "BOTH",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": true,
            "minValidityTime": null,
            "order": 2,
            "currencies": [
                {
                    "currency": "PLN"
                }
            ],
            "buttonTitle": "Generate transfer details"
        },
		{
            "id": 701,
            "name": "Pay later with Payka",
            "groupType": "BNPL",
            "bankName": "NONE",
            "iconUrl": "https://testimages.autopay.eu/pomoc/grafika/701.png",
            "state": "OK",
            "stateDate": "2023-10-03 14:37:10",
            "description": "<div class=\"payway_desc\"><h1>Cost details</h1><p>Pay later - one-off up to 45 days (...). Offer details at: <a href="?r="https://payka.pl\" target=\"_blank\">Payka.pl</a></p></div>",
            "shortDescription": "Pay later - in one go up to 45 days or in several equal instalments",
            "descriptionUrl": null,
            "availableFor": "B2C",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": false,
            "minValidityTime": 60,
            "order": 3,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 49.99,
                    "maxAmount": 7000.00
                }
            ],
            "buttonTitle": "Pay"
        }
    ]
}

NOTA: El resultado de la consulta del método debe actualizarse cada minuto (llamando a gatewayList Si no hay respuesta o ésta es incorrecta, se mostrará la última configuración correcta y conocida de los Canales de Pago. Esta es la segunda razón para mantener una copia temporal de los gatewayList en el Servicio asociado. Una respuesta no válida debe considerarse como una respuesta vacía, un tiempo de espera o una lista vacía de gatewayGroups o gatewayList nodos.

Solicitar una lista de las autorizaciones formales disponibles en la actualidad

Descripción

Descripción de la integración que permite el uso de una lista de pagos integrada en el servicio (o aplicación móvil), sin pasos de transición. En algunos casos, en lugar de un paso de transición, el comportamiento estándar del sistema prevé un inicio bloqueado de la transacción.

El contenido formal pertinente (es decir, las cláusulas informativas y, si procede, los términos y condiciones) debe mostrarse ya en el momento de seleccionar el método de pago, y a continuación debe enviarse al Sistema de Pago en Línea la confirmación de su visualización y, si procede, de su aceptación (en forma de identificadores).

El sistema permite consultar a distancia la lista actual de obligaciones y el contenido formal correspondiente. Para ello, llame a la función legalData método (https://{gate_host}/legalData) con los parámetros adecuados (en formato JSON).

TIP: Todos los parámetros se transmiten utilizando la tecnología REST. El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros transmitidos deben codificarse en UTF-8.

Lista de parámetros disponibles

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

Ejemplo de mensaje

	{
		"ServiceID": 102422,
		"MessageID": "11111111111111111111111111111111",
		"GatewayID": 1500,
		"Language": "PL",
		"Hash":"61789013d932e2bc728d6206f7e9222b93e3176f7f07f6aa8cce1ccd65afaf0d"
	}

Lista de parámetros devueltos

En respuesta a la solicitud, se devuelve una lista (en la misma sesión HTTP), que contiene más contenido formal en forma de: ID, tipo y redacción del contenido, su ubicación en el Servicio, dirección a las normas y otra información adicional.

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

Ejemplo de respuesta

	{
		"serviceID": "102422",
		"messageID": "11111111111111111111111111111111",
		"gatewayID": "1500",
		"language": "PL",
		"serviceModel": "PAYER",
		"regulationList": [
			{
				"regulationID": 6288,
				"type": "RECURRING",
				"url": "https://host/path?params",
				"labelList": [
					{
						"labelID": 1,
						"inputLabel": "<ul><li>\r\nI have read and accept <a id=\"regulations_pdf\" target=\"_blank\" href=https://{gate_host}/path?params>Regulations for the payment services</a> and <a class=\"privacy-policy\" href=\"https://{gate_host}/polityka-prywatnosci.pdf\" target=\"_blank\">Privacy Policy</a></li><li>\r\nI want the service to be provided without delay and, in the event of withdrawal, I know that I will not be reimbursed for the services provided at my request until the withdrawal has taken place\r\n</li></ul>",
						"placement": "ABOVE_BUTTON",
						"showCheckbox": true,
						"checkboxRequired": true
					}
				]
			},
			{
				"regulationID": 1,
				"type": "PRIVACY",
				"labelList": [
					{
						"labelID": 1,
						"inputLabel": "Autopay uses cookies. By remaining on this website, you consent to the use of cookies in accordance with the <a class=\"privacy-policy\" href="?r="https://{gate_host}/polityka-prywatnosci.pdf\" target=\"_blank\">Autopay S.A. privacy policy.</a> You can manage cookies yourself by changing the settings of your browser or device software accordingly."
						"placement": "BOTTOM_OF_PAGE",
						"showCheckbox": false,
						"checkboxRequired": false
					}
				]
			}
		],
		"hash": "61789013d932e2bc728d6206f7e9222b93e3176f7f07f6aa8cce1ccd65afaf0d",
		"result": "OK",
		"errorStatus": null,
		"description": null
	}

Descripción de la gestión de la respuesta

Dado que los requisitos formales del contenido de las cláusulas, su distribución y el método de aceptación dependen del canal de pago utilizado, este método debe invocarse cada vez que se seleccione (de ahí que sea obligatorio el parámetro del GatewayID).

El contenido y el comportamiento pertinentes deben adaptarse dinámicamente a las respuestas del Sistema (por ejemplo, debe aparecer una casilla de verificación obligatoria con una cláusula informativa y un enlace a los términos y condiciones). Por supuesto, para que la aplicación se ejecute rápidamente, se agradece el uso de una caché que recuerde las respuestas de las llamadas recientes (por ejemplo, durante 1 minuto).

El consentimiento mostrado (y posiblemente aprobado) en el momento de la transición al pago debe confirmarse en el Sistema adjuntando al mensaje del inicio de la transacción en el parámetro de inicio de su identificador (y, por tanto, el valor correspondiente del parámetro reglamentoID).

En función del valor de tipo ámbito de la normativa:

- para la cláusula mostrada/aceptada de tipo=DEFAULT:

a. al parámetro DefaultRegulationAcceptanceID su valor de reglamentoID;

b. el DefaultRegulationAcceptanceState debe establecerse en ACEPTADO y

c. el DefaultRegulationAcceptanceTime debe establecerse en el valor correspondiente al momento en que se acepta el consentimiento marcando la casilla de verificación y haciendo clic en el botón "Iniciar pago".

- para la cláusula mostrada/aceptada de tipo=RECURRENTE:

a. al RecurringAcceptanceID debe ser su parámetro reglamentoID VALOR;

b. el RecurringAcceptanceState debe contener el valor ACEPTADO y

c. el RecurringAcceptanceTime debe establecerse en el valor correspondiente al momento en que se acepta el consentimiento marcando la casilla de verificación y haciendo clic en el botón "Iniciar pago".

NOTA: Los campos (por ejemplo serviceModel, url, labelID) y valores de campo (por ejemplo PSD2, RODO, PRIVACIDAD) del legalData no es obligatorio, pero debe preverse la posibilidad de que aparezcan en la respuesta a la solicitud.

Consulta de saldo

Descripción

Para todos los servicios, es posible consultar el saldo actual. Para ello, se utiliza el método saldoObtener https://{gate_host}/webapi/balanceGet con los parámetros pertinentes. Todos los parámetros se pasan a través del método POST (Content-Type: application/x-www-form-urlencoded). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros disponibles para la balanza actual

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

Respuesta a la solicitud de saldo actual

En respuesta a la solicitud, se devuelve un texto (en la misma sesión HTTP) en formato XML, que contiene un acuse de recibo de la operación para su ejecución o una descripción del error.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balanceGet>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<balance>Balance</balance>
		<currency>Currency</currency>
		<hash>Hash</hash>
	</balanceGet>

o

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balanceGet>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<balance>Balance</balance>
		<currency>Currency</currency>
		<hash>Hash</hash>
	</balanceGet>

Lista de campos de respuesta

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

Equilibrar la oferta

Descripción

Para los servicios que tienen saldo en el Sistema, es posible realizar una operación de recarga para futuros reembolsos. Para ello, inicie la operación con el botón TransactionSettlementMode con el valor NONE y Importe indicando el importe de recarga.

Utilizando Antes de la transacción permitirá que la transacción finalizada sea simplemente entregada al pagador (por ejemplo, proporcionando la dirección contable del socio en CustomerEmail).

NOTA: El servicio debe acordarse con el depositario de la empresa. En el modelo Marketplace, además, será necesario construir una cesta de productos indicando qué Punto de Liquidación (BalancePointID) debe alimentarse.

Retiradas de saldo

Descripción

Para los servicios que tienen saldo en el Sistema, es posible realizar
una operación para retirar todo o parte del saldo a una cuenta definida para
liquidación. Para ello, es necesario llamar al método balancePago (https://{gate_host}/settlementapi/balancePayoff) con los parámetros pertinentes.

Todos los parámetros se pasan mediante el método POST (Content-Type: application/x-www-form-urlencoded). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros disponibles para la retirada de saldo

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

NOTA: Uno de los campos ServiceID o BalancePointID es necesario. W
Si se especifican ambos, se detendrá el procesamiento de la solicitud y se producirá un error http.

Respuesta a la solicitud

Al recibir una solicitud de retirada de saldo, el Sistema realiza una verificación inicial con los campos y sus valores enviados en el mensaje y guarda la orden para su ejecución. En respuesta a la solicitud, se devuelve un texto con formato XML (en la misma sesión HTTP), que contiene una confirmación de que la orden se ha guardado en la cola para su ejecución o una descripción del error (la estructura del mensaje de error se describe en el apartado Mensajes de error.

NOTA: El acuse de recibo de una orden no equivale a su ejecución efectiva. Una retirada de saldo puede procesarse hasta 30 minutos después del envío de la solicitud de retirada y puede que no siempre tenga éxito. En caso de que surjan problemas durante el procesamiento de una retirada de saldo (por ejemplo, fondos insuficientes en el saldo), se enviará un informe al día laborable siguiente con información sobre las retiradas de saldo que no se hayan podido realizar.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</balancePayoff>

o

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</balancePayoff>

Descripción de los campos

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

NOTA: Todas las respuestas que no sean las supuestas (es decir, con campos no válidos, en particular, una respuesta vacía o no válida hash) puede considerarse un error. En el caso de que el Sistema autorice el envío de un mensaje de retorno pero la operación falle, la respuesta seguirá el patrón descrito en Mensajes de error. En caso de error de comunicación o de saldo insuficiente (por ejemplo, ON_DEMAND_ERROR), la orden puede volver a intentarse. Si el saldo está bloqueado (BALANCE_DISABLED) o la configuración no está activa (PARTNER_DISABLED), la orden no debe renovarse.

IMPORTANTE En caso de que se devuelva un error en respuesta a una solicitud de retirada de saldo, la solicitud puede volver a intentarse, pero tenga en cuenta que cualquier solicitud de retirada que no termine en error puede ejecutarse. En caso de problemas de conexión, que superen el tiempo máximo de respuesta, se puede repetir la solicitud con el mismo MessageID sin temor a duplicar la orden.
En caso de saldo bloqueado (BALANCE_DISABLED) o configuración inactiva (PARTNER_DISABLED), la solicitud no debe renovarse. 3 errores seguidos (independientemente de la causa) bloquearán el servicio de desembolso bajo demanda para la IP remitente de mensajes especificada durante 10 minutos - las llamadas durante este tiempo para esta IP finalizarán con un error TEMPORARY_DISABLED.

Reembolso de transacciones

Descripción

Para los servicios con saldo en el Sistema, es posible realizar la operación de devolución al Cliente de la totalidad o parte del importe pagado por la transacción indicada. La devolución de la totalidad de la transacción puede realizarse una sola vez (en caso de que se intente repetidamente solicitar la devolución de la misma transacción, el Sistema devuelve un error debidamente descrito). La devolución de parte del importe de una transacción puede realizarse sobre ella varias veces, siempre que su suma no supere el importe del ingreso.

Para realizar una devolución de transacción, llame al método transactionRefund (https://{gate_host}/settlementapi/transactionRefund) con los parámetros pertinentes. Todos los parámetros se pasan a través del método POST (Content-Type: application/x-www-form-urlencoded). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros disponibles

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

En respuesta a la solicitud, se devuelve un texto con formato XML (en la misma sesión HTTP), ya sea confirmando la operación o describiendo el error (descrito a continuación).

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<transactionRefund>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</transactionRefund>

Descripción de los campos

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

La opción de reembolsar las transacciones pagadas es posible hasta 12 meses atrás, a contar desde la fecha en que se inició la transacción. Una excepción son los pagos BLIK, que, debido a limitaciones de tiempo por parte del proveedor del canal de pago, pueden reembolsarse hasta 6 meses atrás.

Los plazos anteriores se aplican a la tramitación de las devoluciones a través del panel administrativo y del transactionRefundpor ejemplo, a través de sus propias herramientas administrativas. Cuando se superen, se devolverá un error (TRANSACCIÓN_DEMASIADO_ANTIGUO_PARA_DEVOLUCIÓN). El esquema de funcionamiento es análogo al de las retiradas de saldo. Es decir, el Sistema acepta la orden y la procesa de forma asíncrona en un plazo máximo de 30 minutos, y en caso de fallo, se envía información sobre las operaciones que han terminado en error en un informe al día laborable siguiente.

En caso de problemas de conexión, que superen el tiempo máximo de respuesta, se puede renovar la solicitud con el mismo MessageID sin temor a que se dupliquen las solicitudes. Todas las respuestas distintas de la supuesta (es decir, con campos incorrectos, en particular en blanco o incorrectos hash). Si el Sistema autoriza al remitente del mensaje de retorno, pero la operación falla, se devolverá un mensaje de error como respuesta.

Devoluciones de productos

Descripción

Para centros con saldo en el Sistema y especificando el productID en la cesta de productos, es posible realizar una operación para devolver al Cliente la totalidad o parte del importe pagado por el producto indicado. La devolución del importe total de un producto se puede realizar una sola vez (en caso de que se intente repetidamente ordenar la devolución del mismo producto, el Sistema devuelve un error debidamente descrito). La devolución parcial de un producto se puede realizar varias veces, siempre que su total no supere el importe pagado por el producto.

Para realizar una devolución de producto, llame al método productoReembolso(https://{gate_host}/settlementapi/productRefund) con los parámetros adecuados. Todos los parámetros se pasan utilizando el método POST (Content-Type: application/x-www-form-urlencoded). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

Respuesta a la solicitud

En respuesta a la solicitud, se devuelve un texto (en la misma sesión HTTP) en formato XML, que contiene un acuse de recibo de la operación para su ejecución o una descripción del error.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<productRefund>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</productRefund>

Descripción de los campos

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

La opción de reembolsar las transacciones pagadas es posible hasta 12 meses atrás, a contar desde la fecha en que se inició la transacción. Una excepción son los pagos BLIK, que, debido a limitaciones de tiempo por parte del proveedor del canal de pago, pueden reembolsarse hasta 6 meses atrás.

Los plazos anteriores se aplican a la tramitación de reembolsos a través del panel de administración y productoReembolsopor ejemplo, a través de sus propias herramientas de administración. Si se superan, se devolverá un error (TRANSACCIÓN_DEMASIADO_ANTIGUO_PARA_DEVOLUCIÓN).

El esquema de funcionamiento es análogo al de las retiradas de saldo. Es decir, el Sistema acepta la orden y la procesa de forma asíncrona en un plazo máximo de 30 minutos, y en caso de fallo, se envía información sobre las operaciones que han terminado en error en un informe al día hábil siguiente.

En caso de problemas de conexión que superen el tiempo máximo de respuesta, la solicitud puede renovarse con el mismo MessageID sin temor a que se dupliquen las solicitudes. Todas las respuestas distintas de la supuesta (es decir, con campos incorrectos, en particular en blanco o incorrectos hash). Si el Sistema autoriza al remitente del mensaje de retorno, pero la operación falla, se devolverá un mensaje de error como respuesta.

Consulta sobre el estado de un reembolso o una retirada de saldo

Descripción

Una vez efectuado el reembolso o la retirada de saldo, tenemos la opción de verificar el estado de la transacción de facturación y
qué identificador le ha asignado el Sistema de Pago Online. Para ello, llame al método outDetails (https://{gate_host}/settlementapi/outDetails) con los parámetros correspondientes. Todos los parámetros se pasan mediante el método POST (Content-Type: application/x-www-form-urlencoded). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros disponibles para la retirada de saldo

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

NOTA: Uno de los campos ServiceID o BalancePointID es necesario.
Si se especifican ambos, se detendrá el procesamiento de la solicitud y se producirá un error http.

Respuesta a la solicitud

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<outDetails>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
	  	<status>Status</status>
		<remoteOutId>RemoteOutId</remoteOutId>
		<hash>Hash</hash>
	</outDetails>

o

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<outDetails>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<status>Status</status>
		<remoteOutId>RemoteOutId</remoteOutId>
		<hash>Hash</hash>
	</outDetails>

Descripción de los campos

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

Página de resumen de la transacción

Descripción

El sistema permite mostrar al cliente un resumen de la transacción. Para ello, el socio puede construir enlaces de activación con el método de parámetros adecuado. confirmación (https://{gate_host}/web/confirmación/pago). Todos los parámetros se transfieren utilizando el método GET. El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros para el método de resumen de transacciones

Al redirigir a un Cliente con los parámetros correctos, se mostrará un resumen de la transacción (con contenido según su estado) o información sobre su ausencia (si el Sistema no la encuentra).

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

NOTA: El servicio debe activarse previo acuerdo con el supervisor de la empresa. Es posible cambiar el contenido de los mensajes o adaptar el diseño gráfico (estos están sujetos a acuerdo en forma de trabajo cada vez durante la integración).

Consulta sobre el estado de una transacción

Descripción

Para todos los servicios, es posible consultar el saldo actual. Para ello, se utiliza el método transactionStatus (https://{gate_host}/webapi/transactionStatus) con los parámetros pertinentes. Todos los parámetros se pasan mediante el método POST (Content-Type: application/x-www-form-urlencoded). El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros pasados deben estar codificados en UTF-8.

Lista de parámetros disponibles para el estado de las transacciones

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

Cabecera HTTP para la solicitud del estado de la transacción

Para que la consulta sea correcta, debe enviarse una cabecera HTTP definida con el contenido adecuado junto con los parámetros pasados. La cabecera adjunta debe llamarse BmHeader y tienen el siguiente valor pay-bm, en su totalidad, debe ser el siguiente 'BmHeader: pay-bm'.. En el caso de un mensaje válido, se devuelve (en la misma sesión HTTP) un texto en formato XML que contiene todas las transacciones con el OrderID indicado, junto con información básica sobre ellas.

TIP: Esta situación puede producirse, por ejemplo, cuando el Cliente cambia el Canal de Pago, vuelve a llamar al inicio de la misma transacción desde el historial del navegador, etc. El sistema permite bloquear tales casos, pero la opción no es recomendable (no sería posible pagar la transacción abandonada).

IMPORTANTE Si la consulta se refiere a un orderID que aparece en más de 50 transacciones de un servicio determinado, se devuelve una respuesta (XML) con el código de error 403.

Estructura de respuesta cuando se alcanza el límite de transacciones con el mismo orderId:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<transaction>
    <reason>LIMIT_REQUESTED_TRANSACTIONS_WITH_THE_SAME_ORDER_ID_AND_SERVICE_ID_EXCEEDED</reason>
    <description>Transaction limit 50 with the same order id {{ORDER_ID}} and service id {{SERVICE_ID}} exceeded. Requested count {{TRANSACTION_AMOUNT}}
    </description>
</transaction>

Lista de campos para una consulta sobre el estado de las transacciones

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

NOTA: Dado que el método puede devolver varias transacciones, las transacciones sucesivas se descargan en el Hash (según el orden de aparición de las transacciones en la respuesta). Dentro de una transacción determinada, se aplica el orden según el número que aparece junto al campo (excluido el parámetro ServiceID, nivel superior).

Ejemplo de cadena de función hash

		Hash = funkcja(<serviceID> + „|” +
	<orderID1> + „|” + <remoteID1> + „|” + <amount1> + „|” + <currency1> + „|” + <gatewayID1> + „|” + <paymentDate1> + „|” + <paymentStatus1> + „|” + <paymentStatusDetails1> + „|” +
	<orderID2> + „|” + <remoteID2> + „|” + <amount2> + „|” + <currency2> + „|” + <gatewayID2> + „|” + <paymentDate2> + „|” + <paymentStatus2> + „|” + <paymentStatusDetails2> + …

Tratamiento de las respuestas a las consultas sobre el estado de las transacciones - propuesta de tratamiento de múltiples transacciones en la respuesta

Anulación de una operación impagada

Descripción de la anulación de una operación impagada

Para todos los servicios es posible cancelar una transacción iniciada pero no pagada llamando al método transactionCancel (https://{gate_host}/webapi/transactionCancel) con los parámetros correspondientes. Todos los parámetros se pasan mediante el método POST (Content-Type: application/x-www-form-urlencoded).

El protocolo distingue entre mayúsculas y minúsculas tanto en los nombres como en los valores de los parámetros. Los valores de los parámetros transmitidos deben codificarse en UTF-8.

Lista de parámetros disponibles para cancelar una transacción impagada

IMPORTANTE El orden de los atributos de la enumeración Hash debe seguir su numeración.

Rúbrica para la anulación de una operación impagada

Para que la consulta sea correcta, debe enviarse una cabecera HTTP definida con el contenido adecuado junto con los parámetros pasados. La cabecera adjunta debe llamarse BmHeader y tienen el siguiente valor pay-bm. En su totalidad, debe ser como sigue 'BmHeader: pay-bm'.

En el caso de un mensaje válido, se devuelve un texto con formato XML (en la misma sesión HTTP), que contiene una confirmación de la operación o una descripción del error.

Estructura de confirmación (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transaction>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<confirmation>ConfStatus</confirmation>
		<reason>Reason</reason>
		<hash>Hash</hash>
	</transaction>

Lista de parámetros para cancelar una transacción impagada

IMPORTANTE El orden de los atributos para la enumeración Hash debe seguir su numeración.

Respuestas a las solicitudes de anulación de operaciones

Si el mensaje es sintácticamente correcto, el Sistema devolverá uno de los siguientes pares describiendo el resultado del procesamiento. Además de su interpretación, se recomienda comprobar el estado de la transacción (método transactionStatus).

Tenga en cuenta que una vez que se haya cancelado con éxito al menos una transacción, no es posible iniciar una nueva ni continuar una transacción iniciada anteriormente con el mismo OrderID.

Mensajes de error

Descripción de los mensajes de error

Todos los mensajes de error se devolverán como un documento XML, que contendrá el código de error, su nombre y su descripción. Debido a la gran variabilidad de posibles errores, no se mantiene una documentación completa de los mismos.

TIP: En descripción describe detalladamente cada error (el campo statusCode y nombre pueden ignorarse).

Ejemplo de error (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<error>
		<statusCode>55</statusCode>
		<name>BALANCE_ERROR</name>
		<description>Wrong services balance! Should be 100 but is 40</description>
	</error>

Modalidades de transacción y liquidación

Esta sección presenta modelos, escenarios de sucesos e información sobre flujos.

Modelo de muro de pago

El modelo más sencillo, en el que la elección de los canales de pago está en las páginas de Autopago (paywall).

Modelo de marca blanca

Se caracteriza por la presentación de canales de pago en el lado del Comerciante. Para ello, obtenga una lista de canales con descripciones de la sección gatewayList/v3 servicio y obtener una lista de las normas y reglamentos necesarios para cada canal de pago (/datoslegales). El resto del proceso es el mismo que en el modelo Paywall.

Estructura ampliada de servicios y puntos de facturación

La estructura de interlocutores consta de al menos 1 servicio (identificado por un identificador ServiceID) y cualquier número de cuentas de puntos (identificadas por un identificador idBalancePoint).

• Los servicios suelen ser las fuentes de los enlaces de pago (sitio web, aplicación móvil, correos electrónicos, etc.). Los servicios también distribuyen tráfico relacionado con diferentes sectores (pagos de facturas, compras de comercio electrónico, etc.). Como la transacción se identifica por un par de OrderID y ServiceIDpuede decirse que "el servicio corresponde al nivel de la transacción".

• Los puntos de liquidación se definen si es necesario distinguir de algún modo los pagos constitutivos (por ejemplo, indicándolos en los informes o en la liquidación independiente). Dado que el producto de una operación se identifica por su punto de liquidación asociado (idBalancePoint), puede decirse que el "punto de facturación corresponde al nivel del producto".

La cesta de productos (y por tanto también los puntos de facturación) puede no estar presente en la estructura que describe al Socio. La razón para añadir puntos de facturación a la estructura influye en la decisión sobre el modelo de facturación:

• La necesidad de distinguir los componentes de un depósito en la lista de transacciones (en los informes) no implica necesariamente la liquidación por separado de cada producto o punto de facturación; en esta situación, los modelos de facturación a nivel de servicio (por lotes o después de cada depósito) suelen ser suficientes.

• La necesidad de separar las liquidaciones componentes de un depósito da lugar al uso de un modelo de liquidación a nivel de punto de liquidación (agregado o después de cada depósito).

A continuación se ilustra un ejemplo de estructura (sin indicar un modelo de liquidación concreto)

Modelos de liquidación

Modelo de liquidación colectiva de operaciones (modelo por defecto)

Las liquidaciones sumarias tienen lugar el siguiente día laborable (D+1).

Modelo de liquidación de las operaciones después de cada pago

La liquidación después de cada pago puede realizarse inmediatamente después de la recepción del pago del Cliente a los datos de la transacción indicados en los parámetros del Enlace de Pago (opciones: Cuenta del destinatario, Título de la transferencia de liquidación, Nombre del destinatario de la transferencia de liquidación).

Modelo colectivo de facturación de productos

Las liquidaciones sumarias tienen lugar el siguiente día laborable (D+1).

Modelo de facturación del producto después de cada pago

La liquidación después de cada pago puede realizarse inmediatamente después de la recepción del pago del Cliente a los datos del producto indicados en los parámetros del Enlace de Pago (opciones: Cuenta del destinatario, Título de la transferencia de liquidación, Nombre del destinatario de la transferencia de liquidación).

Modelo de liquidación a la carta

Las liquidaciones pueden ser ordenadas por el Socio llamando al método: transactionSettlement.