Especificación de los plug-ins de pago
Revise la siguiente visión general sobre la especificación del plug-in de pago para comprender mejor cómo puede utilizar plug-ins de pago.
Versión: 1.0
Finalidad: esta especificación se adjunta con la información de la API de Java para el plug-in de pago de IBM. Proporciona una visión general de los plug-ins de pago y la especificación del plug-in de pago.
A quién va dirigida y conocimientos necesarios: esta información va dirigida a los desarrolladores de aplicaciones de los proveedores de servicios de pago, a las soluciones de comercio electrónico o los sistemas de pago externos.
Información relacionada: esta especificación de API de plug-in de pago está pensada para que se utilice con la siguiente información de API: com.ibm.commerce.payments.plugin.
Características: La especificación del plug-in de pago presenta las siguientes características:
- Admite las modalidades de pago siguientes:
- Tarjetas de crédito*
- Cheques electrónicos*
- Tarjetas de regalo
- Vales de regalo
- Tarjetas de valor almacenado
- Pago después de factura*
- Entrega contra reembolso (CoD)*
- Línea de crédito* (con la integración de fondo típica con sistemas de cuentas por cobrar)
- HCL Commerce da soporte a abonos dependientes e independientes cuando están permitidos por el sistema de pago de fondo.
- Da soporte a varias capturas de fondos por autorización cuando lo permite el sistema de pago de fondo.
- Permite que los desarrolladores de plug-in produzcan rápidamente un plug-in de trabajo.
* Indica que los plug-ins se proporcionan en HCL Commerce para dar soporte a estos métodos. Si crea su propio plug-in, debe seguir esta especificación.
Organización de esta especificación: Esta especificación incluye una lista de terminología que se utiliza y los detalles de la especificación que complementan la información de la API. Esta especificación también incluye ejemplos del descriptor de despliegue de plug-in y el archivo XSD relacionado y diagramas que ayudan a ilustrar conceptos importantes. También contiene información sobre el manejo de errores y las consideraciones de seguridad.
En esta especificación, se incluyen los temas siguientes:
- Terminología
- Descripción de especificación
- Descriptor de despliegue de plug-in
- Descripción de las interfaces de plug-in
- Interfaz de plug-in
- TimeOutException en la interfaz de plug-in
- Interfaz QueryablePlugin
- Interfaz PluginConfiguration
- Interfaz PluginContext
- Interfaz PaymentInstruction
- Interfaz FinancialTransaction
- Interfaz Payment
- Interfaz Credit
- Descripción de las clases de plug-in
- Clase de datos ampliados
- NamedValueObject
- PluginMessages
- Manejo de errores de plug-in de pago
- Consideraciones de seguridad para plug-ins de pago
Terminología utilizada en esta especificación
- Contenedor
- Un objeto de valor que contiene información financiera y puede agregarse a o relacionarse con otros contenedores. Los contenedores que están definidos en la especificación del plug-in son PaymentInstruction, Payment, y Credit.
- Transacción financiera
- Una transacción (objeto) que valida o autentica información de pago, reserva fondos en cuentas y transfiere fondos de una cuenta a otra. El objeto de valor ExtendedData de la transacción financiera proporciona plug-ins con un mecanismo para los datos de protocolo de la tienda que se utilizan durante las transacciones financieras.
- Protocolo de pago
- Un protocolo de pago es el convenio que controla el intercambio de datos entre un plug-in de datos y un sistema de fondo de pago (proveedor de servicios de pago o procesador de pagos). Un protocolo de pago puede incluir procesos en línea o fuera de línea para poder llevar a cabo transacciones financieras. El proceso en línea o el protocolo en línea hace referencia al proceso de transacciones financieras que no precisan ninguna intervención externa para su ejecución correcta. El proceso en línea de una transacción financiera se realiza de forma electrónica y automática y automáticamente sin necesidad de ninguna intervención externa o humana. El proceso fuera de línea o el protocolo fuera de línea hace referencia al proceso de transacciones financieras que precisan intervención externa para ejecutarse correctamente. Por ejemplo, cuando una tarjeta de crédito debe procesarse a través del teléfono o mediante un recuadro de lector, se considera que el proceso está fuera de línea. Este proceso está fuera de línea debido a que es necesaria la intervención externa de una persona para procesar la transacción.
Descripción de especificación
- El Controlador del complemento de pago delega la ejecución de transacciones financieras a los plug-ins de pago.
- Un plug-in de pago es un bean de sesión sin estado con una interfaz remota que externaliza uno o varios payment protocols utilizando una interfaz común. Un plug-in de pago puede implementar un protocolo de pago directamente o bien utilizar bibliotecas que proporcionan la implementación real de un protocolo de pago.
- Existe un acuerdo de proceso entre el Controlador del complemento de pago y los plug-ins de pago. Este acuerdo especifica la información de metadatos de plug-in, empaquetado y API.
- Los plug-in se describen a sí mismos en Controlador del complemento de pago utilizando un plug-in deployment descriptor.
- El Controlador del complemento de pago conserva todos los datos de protocolo que los plug-ins utilizan como pares de nombre-valor cifrados.
- La especificación del plug-in identifica las palabras clave predefinidas que el sistema del HCL Commerce utiliza para transferir detalles del protocolo de datos al Controlador del complemento de pago y a continuación, a los plug-ins. Estas palabras clave de datos de protocolo define un diccionario común pero no son obligatorias. La utilización de palabras clave comunes minimiza el impacto en escaparates cuando los datos de protocolo se recopilan de distintas fuentes para varias modalidades de pago. Estas palabras clave se definen en la información de la API de información de PaymentInstruction para la clase ExtendedData.
- El Controlador del complemento de pago impone o controla las cantidades máximas que se van a utilizar de los contenedores PaymentInstruction, Credit y Payment.
Descriptor de despliegue de plug-in
Un descriptor de despliegue de plug-in permite que un plug-in se integre con HCL Commerce. Es un archivo XML que contiene información sobre un plug-in y describe en el Controlador del complemento de pago cómo se va a desplegar el plug-in. Un descriptor de despliegue de plug-in contiene propiedades comunes que utiliza el Controlador del complemento de pago durante la inicialización del sistema para iniciar y enviar peticiones al plug-in. Se utiliza en los programas de instalación y configuración de HCL Commerce para habilitar el plug-in de pago dentro del Controlador del complemento de pago y la instancia de HCL Commerce.
El descriptor de plug-in de despliegue describe los requisitos de configuración específicos que deben resolverse con el fin de que el plug-in funcione correctamente. El descriptor debe contener el nombre de interfaz inicial de plug-in.
Los descriptores de despliegue de plug-in se denominan PluginDeployment.xml y residen en el directorio EAR de la instancia desplegada en WebSphere Application Server.
Deba haber un descriptor de despliegue de plug-in para cada plug-in y se puede utilizar para definir más propiedades que son específicas de un determinado plug-in. En esta especificación se incluye un XSD de descriptor de despliegue de plug-in y PluginDeployment.xml.
Descripción de las interfaces de plug-in
Para obtener más información sobre estas interfaces, consulte la información de la API relacionada.
- Interfaz Plugin
- La interfaz de plug-in es un bean de sesión sin estado con una interfaz remota que externaliza los servicios de pago para un sistema de fondo de pago, un procesador de pago o un proveedor de servicios de pago (PSP). Los plug-ins se pueden considerar proxies para los sistemas de fondo de pago y los métodos de esta interfaz se correlacionan directamente con las transacciones financieras de fondo relacionadas.
Los plug-ins de pago son extensiones del Controlador del complemento de pago, que proporciona una vista colectiva de los servicios de pago ante HCL Commerce. El Controlador del complemento de pago no proporciona una conectividad directa con un sistema de fondo de pago. Dicha conectividad es el objetivo de un plug-in de pago.
Las siguientes transacciones financieras que se pueden implementar mediante una interfaz de plug-in:
- Aprobación de pago (o autorización)
- Depósito de pago (o captura)
- Abono (o reembolso)
- Anulaciones para las transacciones anteriores
En tanto que creador de plug-in, puede decidir qué métodos de la interfaz de plug-in se implementan, basándose en el protocolo de pago y la capacidad del sistema de fondo. Puesto que algunas transacciones no se aplican para algunos plug-ins, debe determinar qué transacciones se implementan. Para las transacciones que no están implementadas por un plug-in, genere la excepción FunctionNotSupportedException.
- TimeOutException en la interfaz Plugin
Para evitar la contención de recursos, un plug-in no debe bloquear una petición durante largos periodos de tiempo. Siempre que sea posible, genere una TimeOutException cuando transcurra una cantidad de tiempo configurable. Por ejemplo, durante una solicitud approve(), un plug-in puede esperar como máximo 45 segundos. Después de ese tiempo, si el plug-in no recibe una respuesta del sistema de fondo (proveedor de servicios de pago), el plug-in genera una TimeOutException.
Convierta el periodo de espera de un plug-in en una propiedad configurable en el descriptor de despliegue de plug-in. Convierta este valor en configurable dado que un período de espera corto para algunas aplicaciones puede ser un período de espera de largo para otras.
Dado que los plug-ins son beans de sesión sin estado (SSB) (y cómo tales, no deberían crear sus propias hebras subordinadas), tal vez no sean capaces de detectar un tiempo de espera por sí mismos. En estos casos, el contenedor EJB retrotrae automáticamente la transacción EJB que contiene la solicitud de plug-in de acuerdo con un valor de tiempo de espera configurable.
Para añadir una configuración de tiempo de espera para la interfaz de conector, defina una propiedad personalizadatimeouten el archivo PluginDeployment.xml para el plug-in. El plug-in utiliza esta propiedad personalizada como la configuración de tiempo de espera. Defina la propiedad con el formato siguiente, que como ejemplo define un periodo de tiempo de espera de 30 segundos:
Donde el valor es el periodo de tiempo en segundos que el plug-in espera antes de que genere una excepción. El plug-in recibe el valor de esta propiedad del archivo PluginDeployment.xml y determina si se debe generar una excepción basándose en el valor configurado.PluginDeployment.xml Por ejemplo, en la configuración del ejemplo anterior, un plug-in genera una excepción una vez transcurridos 30 segundos sin que el plug-in reciba una respuesta.<PluginProperty name="timeout" value="30"/>
- Interfaz QueryablePlugin
La interfaz QueryablePlugin extiende la interfaz de plug-in y da soporte a consultas financieras. En calidad de creador de plug-in, debe decidir si el plug-in debe implementar esta interfaz y basar esta interfaz en la capacidad de consulta del sistema de fondo. Es responsabilidad del plug-in determinar si utiliza la información que recibe consultando el sistema de fondo.
En general, el Controlador del complemento de pago gestiona el estado de los objetos financieros para plug-ins. Sin embargo, si el sistema de fondo de pago da soporte a consultas en tiempo real, tal vez desee aprovechar esta prestación implementando esta interfaz.
Al implementar esta interfaz, puede tener estados en tiempo real y actualizados de los objetos financieros (pagos y créditos). No obstante, el uso de esta interfaz necesita mayor conectividad de red que si no hubiera ninguna consulta.
Si el sistema de fondo de pago no da soporte a consultas en tiempo real, no implemente esta interfaz.
Cuando una implementación de plug-in utiliza esta interfaz y algunos de los métodos de consulta no están admitidos por el sistema de fondo, el plug-in debe generar la excepción FunctionNotSupportedException.
- Interfaz Plugin_V2
- La interfaz Plugin_V2 extiende la interfaz QueryablePlugin y da soporte al proceso por lotes. Por lo tanto, esta interfaz solamente debe implementarse si el plug-in también permite el proceso por lotes.
- Interfaz PluginConfiguration
- PluginConfiguration es una imagen en memoria del descriptor de despliegue de plug-in. El descriptor de despliegue de plug-in describe una implementación de plug-in (información de configuración y metadatos de plug-in metadata). También proporciona propiedades específicas del plug-in que el plug-in puede utilizar durante el proceso de transacciones financieras.
- Interfaz PluginContext
- La interfaz PluginContext proporciona el contexto de la solicitud que se utiliza en el proceso de transacciones y consultas financieras. Por ejemplo, proporciona información de configuración de plug-in y el entorno local a utilizar para el proceso.
- Interfaz PaymentInstruction
PaymentInstruction es un objeto de valor que contiene información detallada que es necesaria para que los plug-in procesen transacciones financieras. Contiene información que incluye el número de cuenta y los importes de pago o abono. No contiene información que se utiliza para realizar el seguimiento de una transacción determinada con un sistema de fondo de pago. (La información de seguimiento se obtiene utilizando las interfaces Payment, Credit y FinancialTransaction.)
Para ver una ilustración de la relación entre el contenedor de objetos de valor PaymentInstruction y los contenedores Payment, Credit y FinancialTransaction, consulte Diagrama de clases de contenedores de plug-ins Payment.
La sección de importes de PaymentInstruction representa el importe máximo final que el Controlador del complemento de pago puede utilizar colectivamente en la instrucción de pago.
El atributo approvedAmount de Payment identifica qué cantidad se aprueba (se autoriza) y limita la cantidad que se puede depositar (capturar).
El atributo depositedAmount de Payment identifica la cantidad que se deposita.
El Controlador del complemento de pago garantiza que el importe de PaymentInstruction sea igual o mayor que el importe total de todas las solicitudes. El Controlador del complemento de pago permite que se lleven a cabo transacciones financieras approve y credit hasta ese importe.
Por ejemplo, se crea un PaymentInstruction con un importe de $100,00 dólares USA, seguidos por una transacción aprobada de $40,00, y luego otra transacción aprobada de $65,00. El Controlador del complemento de pago no permite que se realice el segundo importe de aprobación porque excede el importe máximo de PaymentInstruction. A continuación, el que llama al Controlador del complemento de pago decide si aumenta el importe de PaymentInstruction para permitir que el importe de aprobación agregado (autorización) sea superior.
Los datos de protocolo adicionales más allá de los atributos estándar que se definen en la definición de PaymentInstruction están gestionados por ExtendedData y por palabras clave
Como este contenedor es un objeto de valor, no se producen transacciones financieras en este objeto. Este objeto contiene información sobre las transacciones financieras antes, durante y después de que se procesen las transacciones.
- FinancialTransaction
La interfaz de FinancialTransaction es un contenedor de objetos de valor que representa una transacción financiera. Este contenedor representa todos los tipos posibles de transacciones financieras que un plug-in puede procesar. Los atributos reales que se utilizan dependen del tipo de transacción que se realice.
Un diagrama de flujo que muestra un ejemplo de cómo se ejecuta una transacción financiera en Ejemplo de flujo de ejecución de transacciones financieras.Flujo de ejecución de transacciones financieras
En esta especificación, están admitidos los tipos de transacción siguientes:
- approve
- deposit
- approveAndDeposit
- credit
- reverseApproval
- reverseDeposit
- reverseCredit
Las transacciones financieras que incluyen anulaciones (reverseApproval, reverseDeposit y reverseCredit) se aplican a los importes aprobados actualmente. Los importes de anulaciones pueden ser iguales o inferiores a approvedAmount, depositedAmount y creditedAmount. Tal vez el importe que está aprobado actualmente no sea obvio; por ejemplo, una transacción de aprobación de $50 dólares USA puede ir seguida de una anulación de aprobación de $25 y otra de $25. En este caso, el importe aprobado actualmente es de 50 euros.
Un plug-in debe actualizar el contenedor FinancialTransaction, mientras que el plug-in procesa transacciones financieras. En este contenedor hay predefinidos varios atributos. Un plug-in también puede añadir información adicional al contenedor FinancialTransaction utilizando la clase ExtendedData.
Response codes and reason codes
En esta interfaz, el código de respuesta es una representación específica de fondo de un resultado de transacción financiera. Normalmente lo utiliza el sistema de fondo para indicar si una transacción financiera ha resultado o no ser satisfactorio. Por ejemplo, el código de respuesta puede indicar que ha fallado la autorización de la tarjeta de crédito.
El código de razón es una representación de específica de fondo de una condición de error. Normalmente lo utiliza el sistema de fondo para indicar porqué ha fallado una transacción financiera. Por ejemplo, puede indicar que una tarjeta de crédito ha caducado. Cuando el código de respuesta por sí mismo no puede identificar qué error se ha producido en una transacción financiera, se puede utilizar el código de razón para determinar el error.
Los atributos de código de respuesta y código de razón pueden considerarse códigos de error primario y secundario. Utilícelos para realizar la determinación de problemas cuando las excepciones de plug-in estándar que se pueden emitir al Controlador del complemento de pago en el plug-in o la interfaz QueryablePlugin sean insuficientes para determinar el origen de un problema.
El código de respuesta y los códigos de razón son útiles cuando se realiza la determinación de problemas. Por ejemplo, si un plug-in genera FinancialException durante una transacción de aprobación de la tarjeta de crédito, el código de respuesta y el código de razón pueden indicar si la tarjeta de crédito ha sido robada o ha caducado.
Para las transacciones correctas, los plug-ins siempre deben establecer el código de respuesta "0" (tipo String) y el código de razón "0" (tipo String). Para las transacciones pendientes, los plug-ins no tienen que establecer estos dos códigos. Para las transacciones anómalas, el plug-in de pago debe definir los códigos.
Nota: El plug-in WCPayments establece el código de retorno primario (PRC) del sistema de Controlador del complemento de pago en un código de respuesta. También establece "PRCxxxSRCxxx" en el código de ratón. PRCxxxSRCxxx es la representación de Serie de PRCxxx que concatena con SRCxxx. Donde:- PRC
- Código de retorno primario.
- SRC
- Código de retorno secundario.
- xxx
- Código de retorno correspondiente.
Tracking IDs
El ID de seguimiento es un atributo opcional que el plug-in utiliza para identificar la transacción financiera en el sistema de fondo de pago. Lo establece el plug-in durante el proceso de una transacción financiera y es exclusivo para el plug-in y en el sistema de fondo. Aunque este atributo es opcional, puede ser la única forma de realizar un seguimiento de una transacción financiera en el sistema de fondo, si se produce un error. Por ejemplo, si se pierde la conectividad de la red durante una transacción financiera, el plug-in no podrá decir si el sistema de fondo ha procesado la transacción. El ID de seguimiento es el único mecanismo disponible para consultar más adelante el sistema de fondo, una vez que se haya restablecido la conectividad.
El número de referencia es un ID generado por el sistema de fondo de pago durante el proceso de transacciones financieras. Habitualmente, lo necesita el sistema de fondo de pago para procesar transacciones subsiguientes y relacionadas. Por ejemplo, durante una transacción de depósito, es necesario el número de referencia de una transacción de aprobación anterior. En este caso, el número de referencia es el código de autorización que el sistema de fondo devolvió durante la transacción de aprobación.
Mientras que el ID de seguimiento se utiliza para identificar una transacción financiera desde la perspectiva del plug-in, el número de referencia se utiliza para identificar una transacción financiera desde la perspectiva del sistema de fondo de pago. El ID de seguimiento es el primer identificador que existe de la transacción. Una vez que se ha obtenido el número de referencia del sistema de fondo, puede que el plug-in no necesite más del ID de seguimiento ya que el número de referencia es conocido tanto en plug-in como en el sistema de fondo de pago.
Puesto que este contenedor es un objeto de valor, no se producen transacciones financieras en este objeto. Este objeto contiene información sobre las transacciones financieras antes, durante y después de que se procesen las transacciones.
- Interfaz Payment
La interfaz Payment define un contenedor de objetos de valor para transacciones relacionadas con el pago. Este contenedor puede mantener una sola aprobación de pago (autorización) y varios depósitos (capturas) para la misma aprobación. Sin embargo, es posible que no todos los sistemas de fondo de pago den soporte a varios depósitos para una sola aprobación.
Este contenedor se crea antes de la transacción de aprobación y se utiliza en transacciones subsiguientes como depósitos y anulaciones. El Controlador del complemento de pago garantiza que solo se emita una transacción approve con respecto a una transacción Payment. También garantiza que solo una transacción esté en un estado pendiente para un pago al mismo tiempo.
Los pagos siempre están asociados a un contenedor PaymentInstruction. Un PaymentInstruction mantiene referencias a todos los contenedores de pago y todos los contenedores Credit que están asociados con él.
Los siguientes son los estados que están asociados a un pago:
- Nueva
- Para un objeto de contenedor de pagos que se acaba de crear.
- A aprobar
- Una transacción pendiente de aprobación.
- Aprobadas
- Una transacción de aprobación satisfactoria.
- Cancelado
- Cuando se cancela un pago.
- Caducado
- La aprobación ha caducado.
- Fallido
- Una transición ha fallado.
Para ver una ilustración de cómo una transacción Payment pasa de un estado a otro cuando se ejecutan transacciones financieras o ediciones relacionadas con respecto a ella, consulte Máquina de estado de pago.Máquina de estado de pago
Puesto que este contenedor es un objeto de valor, no se producen transacciones financieras en este objeto. Este objeto contiene información sobre las transacciones financieras antes, durante y después de que se procesen las transacciones.
- Interfaz Credit
Una instrucción de reembolso es similar a una instrucción de pago. Una autorización de devolución de mercancía (RMA) puede tener varias instrucciones de reembolso. Pero, las normas de reembolso no son configurables.
La interfaz Credit es un contenedor de objetos de valor para transacciones relacionadas con abonos. Los abonos a veces se denominan reembolsos cuando están asociados a una autorización de devolución de mercancía. A continuación, se muestran posibles transacciones que están asociadas a un pago:
- Abonar
- Anulación de abono
Un contenedor Credit solo da soporte a una transacción credit durante su ciclo de vida. Sin embargo, es posible dar soporte a varias anulaciones para la misma transacción credit.
Puesto que este contenedor es un objeto de valor, no se producen transacciones financieras en este objeto. Este objeto contiene información sobre las transacciones financieras antes, durante y después de que se procesen las transacciones.
Los siguientes son estados asociados a un abono:
- Nueva
- Para un objeto de contenedor de abonos que se acaba de crear.
- A abonar
- Una transacción de abono está pendiente.
- Abonado
- Una transacción de abono finaliza correctamente.
- Cancelado
- Se anula por completo un abono.
- Fallido
- Una transición ha fallado.
Para ver una ilustración de cómo un abono pasa de un estado a otro cuando se ejecutan transacciones financieras, consultas o ediciones con respecto a él, consulte Máquina de estado de abono.
Pueden producirse dos tipos de transacciones credit:
- Abono dependiente
- Los abonos dependientes son transacciones que están asociadas a un PaymentInstruction donde se han producido previamente depósitos.../../api/com/ibm/commerce/payments/plugin/PaymentInstruction.html Por ejemplo, después de un depósito de $100 dólares USA, un abono de hasta $100,00 dólares se consideraría un abono dependiente.
- Abono independiente
- Los abonos independientes son transacciones que están asociadas a un PaymentInstruction donde no se ha producido ningún depósitos anterior, o el importe del abono va más allá del importe depositado anteriormente.../../api/com/ibm/commerce/payments/plugin/PaymentInstruction.html Por ejemplo, después de un depósito de 100 euros, un abono de 150 es un abono independiente. Asimismo, sin ningún depósito anterior, un abono de cualquier importe sería un abono independiente.
El soporte de abonos dependientes e independientes puede variar entre los sistemas de fondo de pago.
Un plug-in puede acceder a los contenedores Payment asociados para determinar si una transacción de abono depende de una transacción de depósito anterior.../../api/com/ibm/commerce/payments/plugin/Payment.html Si éste fuera el caso, la transacción de abono puede manejarse como un abono dependiente y el plug-in puede continuar. De lo contrario, la transacción es un abono independiente.
Descripción de las clases de plug-in
- Clase ExtendedData
- En un contexto de plug-in de pago, los datos ampliados no son datos de protocolo estándar necesarios en transacciones financieras. La clase ExtendedData recopila los datos de protocolo no estándar requeridos por una transacción financiera. Los plug-ins requieren datos de protocolo adicionales que van más allá de los atributos estándar que se definen en un contenedor PaymentInstruction. Estos atributos adicionales se pasan del Controlador del complemento de pago a un plug-in utilizando la clase ExtendedData.
Cuando están asociadas a PaymentInstruction, todas las transacciones financieras que se ejecutan para el mismo PaymentInstruction utilizan potencialmente la clase ExtendedData.
Sin embargo, ExtendedData también puede conectarse a un contenedor FinancialTransaction concreto de modo que los atributos adicionales solo se utilizan en el mismo contenedor FinancialTransaction. Las transacciones financieras posteriores pueden volver a utilizar el contenido de la clase ExtendedData si están relacionadas con un contenedor FinancialTransaction anterior.
- NamedValueObject
- La clase NamedValueObject representa un atributo de datos con un nombre, un valor y un distintivo de cifrado. Estos objetos se suelen utilizar para almacenar información sobre un protocolo y forman la clase ExtendedData. Si el distintivo de cifrado se establece en el par nombre-valor, los valores de atributo se cifran mientras se almacenan en la base de datos de HCL Commerce.
- PluginMessages
- La clase PluginMessages define los mensajes traducidos estándar y el programa de utilidad para recuperar estos mensajes. Para obtener una lista de mensajes de plug-in estándar, consulte la información de la API correspondiente a esta clase. Los mensajes de plug-in se incluyen en mensajes de excepción registrados. El componente de HCL Commerce predefinido, WC_PPC_PLUGIN se utiliza como nombre de registrador de WebSphere Application Server para los mensajes de plug-in.
El archivo de propiedades para mensajes se encuentra en el directorio siguiente:
WC_eardir/properties/com/ibm/commerce/negotiation/properties/com/ibm/commerce/payments/plugin/PluginMessages *.properties
WC_eardirur\properties\com\ibm\commerce\payments\plugin\PluginMessages *.properties
Manejo de errores de plug-in de pago
La especificación del plug-in de pago identifica un conjunto de excepciones predefinidas. Si un plug-in no implementa un método concreto, el plug-in debe generar la excepción FunctionNotSupportedException. Si necesitan añadirse más excepciones para un plug-in, la excepción PluginException debe ampliarse. Sin embargo, el Controlador del complemento de pago no podrá procesar estas excepciones de ninguna forma. Aunque se detecten todas las excepciones, los errores relacionados con el plug-in no pueden manejarse correctamente. Por ejemplo, un FinancialException informa al Controlador del complemento de pago de que se ha producido algún error financiero y el Controlador del complemento de pago puede actuar informando a otras capas de software, como el Motor de normas de pago. No obstante, si se produce una ABCException, se empaqueta como una excepción de plug-in genérica.
Las excepciones que se generan con un plug-in deben contener tanta información contextual como sea posible para permitir el manejo de errores adecuado y la determinación de problemas. La información puede incluir los códigos de resultado del sistema de fondo de pago y la referencia de contenedor para la instrucción de pago, el pago y el abono.
- EDPException
- La excepción raíz del Motor de normas de pago.
- PluginException
- La excepción raíz del plug-in de Payments.
En situaciones excepcionales, genere PluginException (o una excepción) en el plug-in de pago.
- InvalidDataException
- Si el error de transacción de pago está causado por información de pago no válida que un comprador entra, se puede generar una excepción InvalidDataException con la clave del mensaje y el paquete de recursos.
Esta excepción está correlacionada con la ECApplicationException con un mensaje de error que contiene el mensaje de InvalidDataException. Por ejemplo:InvalidDataException ie = new InvalidDataException(); ie.setMessageKey(your message key); ie.setFormatArguments(your message arguments); ie.setResourceBundleName(your resource bundle); throw ie;A generic payment user exception occured. The exception is as follows: "error message of InvalidDataException"Si no desea mensajes adicionales distintos de los que definió en InvalidDataException, puede alterar temporalmente la definición de mensaje NLV en el paquete de recursos. El paquete de recursos se encuentra en el siguiente directorio:- WC_eardir/Stores.war/WEB-INF/classes/storedir
- workspace_dir\Stores\Web Content\WEB-INF\classes\storedir
Por ejemplo, puede añadir mensajes en inglés en este archivo: storeErrorMessages_en_US.properties.
A continuación, se muestra el mensaje de error siguiente en la página de la tienda:_ERR_PAYMENT_GENERIC_USER_EXCEPTION={0}
Los mensajes de error se pueden visualizar en la página de la tienda. No es necesario que personalice el paquete de recursos tal como se describe en el ejemplo anterior.error message of InvalidDataException - CommunicationException
- Si el plug-in de pago experimenta un problema de conectividad mientras que el plug-in se comunica con el sistema de fondo de pago. Puede generar una excepción CommunicationException con la clave del mensaje y el paquete de recursos.
CommunicationException ce = new CommunicationException(); ce.setMessageKey(your message key); ce.setFormatArguments(your message arguments); ce.setResourceBundleName(your resource bundle); throw ce;Esta excepción está correlacionada con la ECSystemException con un mensaje de error que contiene el mensaje de error CommunicationException. No se ha podido ejecutar la acción de pago debido a {mensaje de error de CommunicationException} Si no desea un contenido de mensaje que sea distinto del que ha definido en CommunicationException, puede alterar temporalmente la definición de mensaje NLV en el paquete de recursos de la tienda en el siguiente directorio:- WC_eardir/Stores.war/WEB-INF/classes/storedir
- workspace_dir\Stores\WebContent\WEB-INF\classes\storedir
Por ejemplo, OrderProcessCmd está configurado de tal modo que si se produce esta excepción debido a un error de autorización de pago en un pedido sometido, se reintenta este mandato y se desencadena de nuevo la autorización de pago. Si no desea que el mandato se reintente en una situación como ésta, establezca el mandato que realiza la llamada en retriable=0, la base de datos CMDREG. No establezca este mandato para que no realice reintentos de ECSystemException, porque el mandato necesita realizar reintentos para manejar situaciones de excepción.
- FunctionNotSupportedException
- Si este tipo de transacción financiera no está soportada por la implementación de plug-in, puede generar la excepción FunctionNotSupportedException con la clave de mensaje y el paquete de recursos. Por ejemplo, si el plug-in no da soporte a la API approveAndDeposit, pero el comerciante intenta llamar a esta API, se genera la excepción FunctionNotSupportedException. Esta excepción está correlacionada con ECApplicationException, de modo que el comportamiento después de que se emita esta excepción es similar a InvalidDataException.
- ConfigurationException
- Si el plug-in de pago no consigue encontrar la información necesaria en la configuración de plug-in, puede generar una excepción ConfigurationException con la clave de mensaje y el paquete de recursos. Por ejemplo, si la configuración en el archivo XML de despliegue de plug-in no es válida, se genera la excepción ConfigurationException. Esta excepción está correlacionada con ECSystemException, de modo que el comportamiento después de que se emita esta excepción es similar a CommunicationException.
- InternalErrorException
- Si el plug-in de pago experimenta un error inesperado que ha sucedido en la implementación de plug-in, puede generar InternalErrorException con la clave de mensaje y el paquete de recursos. Por ejemplo, si el plug-in recibe la respuesta de la pasarela del proveedor de servicios de pago con un formato no válido, se genera InternalErrorException. Esta excepción está correlacionada con ECSystemException, de modo que el comportamiento que esta excepción genera sea similar a CommunicationException.
- TimeoutException
- Si el plug-in de pago excede el tiempo de espera en espera de una respuesta, puede generar TimeoutException con la clave de mensaje y el paquete de recursos. Por ejemplo, si el plug-in está configurado de tal modo que el tiempo de espera de una respuesta ha finalizado y no hay ninguna respuesta, entonces se genera TimeoutExcption. El Controlador del complemento de pago genera la excepción TimeoutException. Si se emiten este tipo de excepciones, la transacción de HCL Commerce global no se retrotrae, sino que el estado del pago establece en pendiente. Si el proveedor de servicios de pago admite un nuevo intento de la transacción de pago, puede generar esta excepción cuando no reciba la respuesta.
- FinancialException
- FinancialException se produce en elControlador del complemento de pago. Si utiliza este tipo de excepciones, la transacción de HCL Commerce global no se retrotrae, sino que el estado del pago implicado se establece en error. Si desea capturar el pedido en caso de que no consiga ejecutarse un pago, utilice FinancialException en el plug-in. Hay tres excepciones de FinancialException:
- ApprovalExpiredException
- Esta excepción se produce cuando la aprobación del pago (autorización) caduca. Esta excepción es diferente de las dos excepciones siguientes porque no está correlacionada con una ECSystemException.
- InvalidPaymentInstructionExcepiton
- Esta excepción se produce para indicar que PaymentInstruction no es válido.
- PaymentInstructionBlockedException
- Esta excepción se produce cuando una transacción financiera no se puede procesar para PaymentInstruction. Esta excepción es una situación temporal. La transacción financiera se puede intentar de nuevo tras algún tiempo, con respecto al mismo PaymentInstruction. Por ejemplo, la tarjeta de crédito que está asociada a una instrucción de pago podría colocarse en espera. El comportamiento de InvalidPaymentInstructionException y PaymentInstrutionBlockedException es el mismo que el de FinancialException.
- PluginException
- Si no puede encontrar una excepción adecuada de las excepciones anteriores, puede utilizar un PluginException. Esta excepción está correlacionada con ECSystemException, de modo que el comportamiento después de que se produzca esta excepción es similar a CommunicationException.
- solo las excepciones CommunicationException y InternalErrorException se correlacionan con ECSystemException, mientras que las demás excepciones de plug-in se correlacionan con ECApplicationException.
- Cuando las excepciones de plug-in se correlacionan con ECException, la clave de mensaje del paquete de recursos que se establece en las excepciones de plug-in está compuesta en un nuevo objeto ECMessage. Este objeto utiliza la clave del mensaje del paquete de recursos como la clave de mensaje de ECException. En la página de la tienda, el mensaje de error que se establece en el plug-in se visualiza sin ningún contenido adicional. No es necesario que personalice en este caso.
Consideraciones de seguridad para plug-ins de pago
Los plug-ins de pago son responsables de la seguridad de la comunicación con sus sistemas de fondo de pago. Puesto que la información de pago son datos confidenciales, los plug-ins cifran todos los datos que se envían a través de las conexiones de red. Controlador del complemento de pago not proporciona servicios de cifrado para este tipo de comunicación con el sistema de fondo de pago.
Todos los datos confidenciales en un contenedor PaymentInstruction están cifrados por el Controlador del complemento de pago cuando permanecen en la tabla PPCEXTDATA.
Si el plug-in conserva datos confidenciales en el sistema de archivos o utilizando bases de datos, cifre los datos confidenciales. El Controlador del complemento de pago no proporciona servicios de cifrado para esta permanencia.
Si utiliza el control de acceso Java EE o EJB, la documentación de plug-in que produce debe identificar claramente los roles de usuario y los permisos necesarios para utilizar la implementación de plug-in. Esta documentación es necesaria para que pueda desplegar el plug-in.
Los datos confidenciales transitorios, por ejemplo, el Código de validación de tarjeta, se transfieren al plug-in como datos ampliados de la instrucción de pago actual. Puede recuperar los datos en el plug-in y transferirlos al sistema de pago de fondo, si es necesario. Evite mantener o eliminar algunos de los datos confidenciales transitorios en el plug-in. El controlador de plug-in de Payments es responsable de la eliminación de datos confidenciales transitorios y de evitar que los datos persistan en la base de datos.