Spécification de plug-in Payment

Version : 1.0

But : cette spécification accompagne les informations d'API Java pour le plug-in IBM Payment. Ces informations donnent un aperçu des plug-ins de paiement et des spécifications de plug-in de paiement.

Exigences en matière du public cible et des compétences : ces informations s'adressent aux développeurs d'applications pour les prestataires de services de paiement, les solutions de commerce électronique ou les systèmes de paiement externes.

Informations connexes : cette spécification API plug-in de paiement est destinée à être utilisée avec les informations d'API suivantes : com.ibm.commerce.payments.plugin.

Fonctions : : La spécification de plug-in de paiement comporte les caractéristiques suivantes :

• Prend en charge les modes de paiement suivants :
  • Cartes de crédit*
  • Chèques électroniques*
  • Cartes-cadeaux
  • Chèques-cadeau
  • Cartes à valeur stockées
  • Facturation ultérieure*
  • Contre remboursement (CoD)*
  • Ligne de crédit* (avec intégration d'arrière-plan typique avec les systèmes de comptes débiteurs)
• HCL Commerce prend en charge les crédits dépendants et indépendants lorsqu'ils sont autorisés par le système dorsal de paiement.
• Prend en charge plusieurs captures de fonds par autorisation lorsque le système dorsal de paiement le permet.
• Permet aux développeurs de plug-ins de créer rapidement un plug-in opérationnel.

* Indique que des plug-ins sont fournis dans HCL Commerce pour prendre en charge ces modes. Si vous élaborez votre propre plug-in, vous devez suivre cette spécification.

Organisation de cette spécification : cette spécification comprend une liste de la terminologie utilisée et les détails de spécification qui complètent les informations d'API. Cette spécification inclut également des exemples de descripteur de déploiement de plug-ins et du fichier XSD associé, ainsi que des diagrammes qui aident à illustrer des concepts importants. Il contient également des informations sur le traitement des erreurs et les considérations de sécurité.

Les sujets suivants sont inclus dans cette spécification :

• Terminologie
• Description de la spécification
• Descripteur de déploiement de plug-ins
• Comprendre les interfaces de plug-in
  • Interface de plug-in
  • TimeOutException dans l'interface de plug-in
  • Interface QueryablePlugin
  • Interface PluginConfiguration
  • Interface PluginContext
  • Interface PaymentInstruction
  • Interface FinancialTransaction
  • Interface Payment
  • Interface Credit
• Comprendre les classes de plug-in
  • Classes de bean étendues
  • NamedValueObject
  • PluginMessages
• Gestion des erreurs du plug-in Payment
• Remarques sur la sécurité pour les plug-ins de paiement

Terminologie utilisée dans cette spécification

Conteneur

Un objet de valeur qui contient des informations financières et qui peut regrouper ou se rapporter à d'autres conteneurs. Les conteneurs qui sont définis dans la spécification de plug-in sont PaymentInstruction, Payment et Credit.

Transaction financière

Une transaction (objet) qui valide ou authentifie les informations de paiement, réserve des fonds dans des comptes et transfère des fonds d'un compte à un autre. L'objet de valeur ExtendedData de la transaction financière fournit aux plug-ins un mécanisme pour les données de protocole de magasin utilisées lors des transactions financières.

Protocole de paiement

Un protocole de paiement est la convention qui régit l'échange de données entre un plug-in de paiement et un système de paiement (prestataire de services de paiement ou processeur de paiement). Un protocole de paiement peut impliquer un traitement en ligne ou hors ligne afin de permettre l'exécution de transactions financières. Le traitement en ligne ou le protocole en ligne fait référence au traitement des transactions financières qui nécessitent une intervention externe pour une exécution réussie. Le traitement en ligne d'une transaction financière se fait par voie électronique et automatiquement sans avoir besoin d'intervention externe ou humaine. Le traitement hors ligne ou le protocole hors ligne fait référence au traitement des transactions financières qui nécessite une intervention externe pour une exécution réussie. Par exemple, lorsqu'une carte de crédit doit être traitée par téléphone ou à l'aide d'un lecteur de cartes de crédit, cela est considéré comme un traitement hors ligne. Ce traitement est hors ligne, car l'intervention externe d'un humain est nécessaire pour traiter la transaction.

Description de la spécification

• Le Contrôleur des plug-in de paiement délègue l'exécution des transactions financières aux plug-ins de paiement.
• Un plug-in de paiement est un bean session sans état avec une interface distante qui externalise un ou plusieurs payment protocols à l'aide d'une interface commune. Un plug-in de paiement peut implémenter directement un protocole de paiement ou utiliser des bibliothèques qui fournissent l'implémentation réelle d'un protocole de paiement.
• Un accord de traitement existe entre le Contrôleur des plug-in de paiement et les plug-ins de paiement. Cet accord précise les informations relatives au packaging, aux API et aux métadonnées des plug-ins.
• Les plug-ins se décrivent au niveau du Contrôleur des plug-in de paiement en utilisant un plug-in deployment descriptor.
• Le Contrôleur des plug-in de paiement conserve toutes les données de protocole utilisées par les plug-ins sous la forme de paires nom-valeur chiffrées.
• La spécification du plug-in identifie les mots clés prédéfinis que le système HCL Commerce utilise pour transmettre les détails des données de protocole jusqu'au Contrôleur des plug-in de paiement puis jusqu'aux plug-ins. Ces mots clés de données de protocole définissent un dictionnaire commun, mais ne sont pas obligatoires. L'utilisation de mots clés courants minimise l'impact sur les vitrines lorsque les données du protocole sont collectées à partir de plusieurs sources pour plusieurs modes de paiement. Ces mots clés sont définis dans les informations d'API PaymentInstruction de la classe ExtendedData.
• Le Contrôleur des plug-in de paiement applique ou contrôle les montants maximums à consommer à partir des conteneurs PaymentInstruction, Credit et Payment.

Descripteur de déploiement de plug-ins

Un descripteur de déploiement de plug-ins permet à un plug-in de s'intégrer à HCL Commerce. Il s'agit d'un fichier XML qui contient des informations sur un plug-in et indique à Contrôleur des plug-in de paiement comment le plug-in doit être déployé. Un descripteur de déploiement de plug-ins contient des propriétés courantes utilisées par le Contrôleur des plug-in de paiement lors de l'initialisation du système pour démarrer et envoyer les requêter vers le plug-in. Il est utilisé par les programmes d'installation et de configuration de HCL Commerce pour activer le plug-in de paiement dans le Contrôleur des plug-in de paiement et l'instance HCL Commerce.

Le descripteur de déploiement de plug-ins décrit les exigences de configuration spécifiques qui doivent être résolues pour que le plug-in fonctionne correctement. Le descripteur doit contenir le nom de l'interface d'accueil du plug-in.

Les descripteurs de déploiement de plug-ins sont nommés PluginDeployment.xml et résident dans le répertoire EAR de l'instance déployée dans WebSphere Application Server.

Un descripteur de déploiement de plug-ins doit exister pour chaque plug-in et peut être utilisé pour définir d'autres propriétés spécifiques à un plug-in spécifique. A XSD de descripteur de déploiement de plug-ins et PluginDeployment.xml sont inclus dans cette spécification.

Comprendre les interface de plug-in

Pour plus d'informations sur ces interfaces, reportez-vous aux informations d'API associées.

Interface du plug-in

L'interface du plug-in est un bean session sans état avec une interface distante qui externalise les services de paiement pour un système dorsal de paiement, un processeur de paiement, ou un prestataire de services de paiement (PSP) spécifique. Les plug-ins peuvent être considérés comme des serveurs proxy pour les systèmes dorsaux de paiement et les méthodes de cette interface consistent à mapper directement les transactions financières d'arrière-plan connexes.

Les plug-ins Payment sont des extensions de Contrôleur des plug-in de paiement, qui fournit une vue collective des services de paiement à HCL Commerce. Le Contrôleur des plug-in de paiement ne fournit pas de connectivité directe à un système dorsal de paiement. Une telle connectivité est l'objectif d'un plug-in de paiement.

Les transactions financières suivantes peuvent être implémentées par une interface FR plug-in :

• Approbation (ou autorisation) de paiement
• Dépôt (ou capture) de paiement
• Crédit (ou remboursement)
• Annulations des transactions précédentes

En tant que créateur du plug-in, vous décidez quelles méthodes doivent être implémentées dans l'interface de plug-in, en fonction du protocole de paiement et de la capacité d'arrière-plan du système. Puisque certaines transactions ne s'appliquent pas à certains plug-ins, vous devez déterminer les transactions à implémenter. Pour les transactions qui ne sont pas implémentées par un plug-in, lancez l'exception FunctionNotSupportedException.

TimeOutException dans l'interface de plug-in

Pour éviter les confits des ressources, un plug-in ne doit pas bloquer de requêtes pendant de longues périodes. Dans la mesure du possible, lancez une exception timeoutException après l'expiration d'un laps de temps configurable. Par exemple, lors d'une requête approve(), un plug-in peut attendre au maximum 45 secondes. Passé ce délai, si le plug-in ne reçoit pas de réponse du système d'arrière-plan (prestataire de services de paiement), le plug-in lance une exception TimeOutException.

Faites en sorte que la période d'attente pour un plug-in soit une propriété configurable dans le descripteur de déploiement de plug-ins. Rendez ce paramètre configurable, car une courte période d'attente pour certaines applications peut être une longue période d'attente pour d'autres.

Puisque les plug-ins sont des beans session sans état (SSB) (et ne sont donc pas censés créer leurs propres unités d'exécution d'arrière-plan), ils pourraient ne pas être en mesure de détecter un délai d'attente par eux-mêmes. Dans ces situations, la transaction EJB qui contient la requête de plug-in est annulée automatiquement par le conteneur EJB selon un délai d'attente préconfigurable.

Pour ajouter une configuration de délai d'attente pour l'interface de plug-in, définissez une propriété timeout personnalisée dans le fichier PluginDeployment.xml de votre plug-in. Votre plug-in utilise cette propriété personnalisée comme configuration de délai d'attente. Définissez la propriété avec le format suivant, qui, à titre d'exemple, définit une période d'attente de 30 secondes :

<PluginProperty name="timeout" value="30"/>

Où la valeur est la période d'attente en secondes du plug-in qu'il ne lance une exception. Votre plug-in obtient la valeur de cette propriété à partir du fichier PluginDeployment.xml et détermine s'il faut lancer une exception en fonction de la valeur configurée. Par exemple, dans la configuration de l'exemple précédente, un plug-in lance une exception après 30 secondes écoulées sans que le plug-in ne reçoive une réponse.

Interface QueryablePlugin

L'interface QueryablePlugin étend l'interface du plug-in et prend en charge les requêtes financières. En tant que créateur de plug-ins, décidez si le plug-in doit implémenter cette interface et basez-la sur la capacité de requête du système d'arrière-plan. Il incombe au plug-in de déterminer s'il utilise les informations reçues en interrogeant le système d'arrière-plan.

En général, Contrôleur des plug-in de paiement gère l'état des objets financiers pour les plug-ins. Toutefois, si le système dorsal de paiement prend en charge les requêtes en temps réel, vous souhaiterez peut-être utiliser cette fonctionnalité en implémentant cette interface.

En implémentant cette interface, vous pouvez disposer de statuts en temps réel et à jour des objets financiers (paiements et crédits). Toutefois, l'utilisation de cette interface nécessite une plus grande connectivité réseau que l'absence de requête.

Si le système dorsal de paiement ne prend pas en charge les requêtes en temps réel, n'implémentez pas cette interface.

Lorsqu'une implémentation de plug-in utilise cette interface et que certaines des méthodes de requête ne sont pas prises en charge par le système d'arrière-plan, le plug-in doit lancer l'exception FunctionNotSupportedException.

Interface Plugin_V2

L'interface Plugin_V2 étend l'interface QueryablePlugin et prend en charge le traitement par lots. Par conséquent, cette interface ne doit être implémentée que si le plug-in prend également en charge le traitement par lots.

Interface PluginConfiguration

Le PluginConfiguration est une image en mémoire du descripteur de déploiement de plug-ins. Le descripteur de déploiement de plug-ins décrit une implémentation de plug-ins (métadonnées de plug-in et informations de configuration). Il fournit également des propriétés spécifiques au plug-in qui peuvent être utilisées par le plug-in pendant le traitement des transactions financières.

Interface PluginContext

L'interface PluginContext fournit le contexte de la requête utilisée dans le traitement des transactions et des requêtes financières. Par exemple, elle fournit les informations de configuration du plug-in et les paramètres à utiliser pour le traitement.

Interface PaymentInstruction

PaymentInstruction est un objet de valeur qui contient des informations détaillées requises par les plug-ins pour traiter les transactions financières. Il contient des informations qui incluent le numéro de compte, ainsi que les montants de paiement ou de crédit. Il ne contient pas d'informations utilisées pour suivre une transaction particulière avec un système dorsal de paiement. (Les informations de suivi sont obtenues à l'aide des interfaces Payment, Credit et FinancialTransaction.)

Pour illustrer la relation entre le conteneur d'objets de valeur PaymentInstruction et les conteneurs Payment, Credit et FinancialTransaction, voir Diagramme de classe des conteneurs de plug-in Payment.

La section sur les montants dans PaymentInstruction représente le montant cible maximal que Contrôleur des plug-in de paiement peut consommer collectivement sur l'instruction de paiement.

L'attribut Payment approvedAmount indique le montant approuvé (autorisé) et limite le montant qui peut être déposé (capturé).

L'attribut Payment déposéAmount identifie le montant déposé.

Le Contrôleur des plug-in de paiement garantit que le montant de PaiementInstruction est toujours égal ou supérieur au montant total de toutes les requêtes. Le Contrôleur des plug-in de paiement permet aux transactions financières d'approbation et de crédit de se produire jusqu'à ce montant.

Par exemple, une opération PaymentInstruction est créée avec un montant de 100 $ US, suivie d'une transaction approuvée de 40 $, puis d'une autre transaction approuvée de 65 $. Le Contrôleur des plug-in de paiement ne permet pas que le deuxième montant d'approbation se produise puisqu'il dépasse le montant maximal de PaymentInstruction. L'appelant de Contrôleur des plug-in de paiement décide alors d'augmenter le montant de PaymentInstruction pour permettre un montant d'approbation agrégé plus élevé (autorisation).

Les données de protocole supplémentaires au-delà des attributs standard définis dans la définition PaymentInstruction sont gérées par ExtendedData et Keywords

Etant donné que ce conteneur est un objet de valeur, aucune transaction financière ne se produit dans cet objet. Cet objet contient des informations sur les transactions financières avant, pendant et après le traitement des transactions.

FinancialTransaction

L'interface FinancialTransaction est un conteneur d'objets de valeur qui représente une transaction financière. Ce conteneur représente tous les types possibles de transactions financières qui peuvent être traitées par un plug-in. Les attributs réels utilisés dépendent du type de transaction qui se produit.

Un diagramme de flux qui montre un exemple de l'exécution d'une transaction financière dans Exemple de flux d'exécution de transactions financières.

Les types de transactions suivants sont pris en charge dans la présente spécification :

• approve
• deposit
• approveAndDeposit
• credit
• reverseApproval
• reverseDeposit
• reverseCredit

Les transactions financières qui impliquent des annulations (reverseApproval, reverseDeposit et reverseCredit) s'appliquent aux montants actuellement approuvés. Les montants annulés peuvent être égaux ou inférieurs à ApprovedAmount, depositedAmount et creditedAmount. Le montant qui est actuellement approuvé pourrait ne pas être évident. Par exemple, une transaction d'approbation de 50 $ US peut être suivie d'une approbation annulée de 25 $ et d'une autre approbation annulée de 25 $. Dans ce cas, le montant actuellement approuvé est de 0 $.

Un plug-in doit mettre à jour le conteneur FinancialTransaction pendant que le plug-in traite les transactions financières. Plusieurs attributs sont prédéfinis dans ce conteneur. Un plug-in peut également ajouter des informations supplémentaires au conteneur FinancialTransaction à l'aide de la classe ExtendedData.

Response codes and reason codes

Dans cette interface, le code de réponse est une représentation d'arrière-plan spécifique d'un résultat de transaction financière. Il est généralement utilisé par le système d'arrière-plan pour indiquer si une transaction financière a été réussie ou non. Par exemple, le code de réponse peut indiquer qu'une autorisation de carte de crédit a échoué.

Le code de raison est la représentation d'arrière-plan spécifique d'une condition d'erreur. Il est généralement utilisé par le système d'arrière-plan pour indiquer pourquoi une transaction financière a échoué. Par exemple, il peut indiquer qu'une carte de crédit a expiré. Lorsque le code de réponse à lui seul ne peut pas identifier ce qu'il s'est produit dans une transaction financière, le code de raison peut être utilisé pour déterminer l'erreur de transaction financière.

Les attributs de code de réponse et de code de raison peuvent être considérés comme des codes d'erreur primaires et secondaires. Utilisez-les pour déterminer le problème lorsque les exceptions standard de plug-in qui peuvent être renvoyées au Contrôleur des plug-in de paiement dans l'interface de plug-in ou QueryablePlugin sont insuffisantes pour déterminer la source d'un problème.

Le code de réponse et les codes de raison sont utiles lorsque vous déterminez des problèmes. Par exemple, si un plug-in lance FinancialException lors d'une transaction d'approbation de carte de crédit, le code de réponse et le code de raison peuvent indiquer si la carte de crédit est volée ou expirée.

Pour les transactions réussies, les plug-ins doivent toujours définir le code de réponse sur "0" (type de chaîne) et le code de raison sur "0" (type de chaîne). Pour les transactions en attente, les plug-ins n'ont pas à définir ces deux codes. Pour les transactions ratées, le plug-in de paiement doit définir les codes.

Remarque : Le plug-in WCPayments définit le code de retour principal (PRC) du système Contrôleur des plug-in de paiement sur un code de réponse. Il définit également le code de raison sur "PRCxxxSRCxx". PRCxxxSRCxxx est la représentation de la chaîne de PRCxxx qui concatène SRCxxx. Où :

PRC

Code retour principal.

SRC

Code retour secondaire.

xxx

Code de retour correspondant.

Tracking IDs

L'ID de suivi est un attribut facultatif qui est utilisé par le plug-in pour identifier la transaction financière dans le système dorsal de paiement. Il est défini par le plug-in pendant le traitement d'une transaction financière, et est unique au plug-in et dans le système d'arrière-plan. Bien que cet attribut soit facultatif, c'est parfois le seul moyen de suivre une transaction financière dans le système d'arrière-plan en cas d'erreur. Par exemple, si la connectivité réseau est perdue lors d'une transaction financière, le plug-in ne sera pas en mesure de savoir si le système d'arrière-plan a traité la transaction. L'ID de suivi est le seul mécanisme disponible pour interroger le système d'arrière-plan plus tard après que la connectivité est rétablie.

Le numéro de référence est un ID généré par le système dorsal de paiement pendant le traitement des transactions financières. Il est généralement exigé par le système dorsal de paiement pour traiter les transactions ultérieures et connexes. Par exemple, lors d'une transaction de dépôt, le numéro de référence d'une transaction d'approbation précédente est requis. Dans ce cas, le numéro de référence est le code d'autorisation renvoyé par le système d'arrière-plan lors de la transaction d'approbation.

Même si l'ID de suivi est utilisé pour identifier une transaction financière du point de vue du plug-in, le numéro de référence est utilisé pour identifier une transaction financière du point de vue du système de paiement dorsal. L'ID de suivi est le premier identificateur d'existence de la transaction. Une fois le numéro de référence obtenu à partir du système d'arrière-plan, le plug-in n'a peut-être plus besoin de l'ID de suivi puisque le numéro de référence est connu à la fois par le plug-in et par le système dorsal de paiement.

Puisque ce conteneur est un objet de valeur, aucune transaction financière ne se produit dans cet objet. Cet objet contient des informations sur les transactions financières avant, pendant et après le traitement des transactions.

Interface Payment

L'interface Payment définit un conteneur d'objets de valeur pour les transactions liées au paiement. Ce conteneur peut contenir une seule approbation de paiement (autorisation) et plusieurs dépôts (captures) pour la même approbation. Toutefois, plusieurs dépôts pour une seule approbation peuvent ne pas être pris en charge par tous les systèmes dorsaux de paiement.

Ce conteneur est créé avant la transaction d'approbation et est utilisé sur des transactions ultérieures telles que des dépôts et les annulations. Le Contrôleur des plug-in de paiement vérifie qu'une seule transaction d'approbation est émise par paiement. Il garantit également qu'une seule transaction est dans un état d'attente pour un paiement en même temps.

Les paiements sont toujours associés à un conteneur PaymentInstruction. PaymentInstruction conserve des références sur tous les conteneurs Payment et Credit qui lui sont associés.

Voici les états associés à un paiement :

Nouveau

Pour un objet de conteneur de paiement lorsqu'il est nouvellement créé.

Approbation en cours

Une transaction d'approbation en attente.

Approuvé

Une transaction d'approbation réussie.

Annulé

Lorsqu'un paiement est annulé.

Périmé

L'approbation a expiré.

Echec

Une transaction a échoué.

Pour illustrer comment un paiement se déplace d'un état à l'autre lorsque des transactions financières ou des modifications sont effectuées au niveau de ce paiement, voir Machine d'état du paiement.

Puisque ce conteneur est un objet de valeur, aucune transaction financière ne se produit dans cet objet. Cet objet contient des informations sur les transactions financières avant, pendant et après le traitement des transactions.

Interface Credit

Une instruction de remboursement est similaire à une instruction de paiement. Une autorisation de retour de marchandise (RMA) peut avoir plusieurs instructions de remboursement. Toutefois, les règles de remboursement ne sont pas configurables.

L'interface Credit est un conteneur d'objets de valeur pour les transactions liées au crédit. Les crédits sont parfois appelés remboursements lorsqu'ils sont associés à une autorisation de retour de marchandise. Voici les transactions possibles associées à un crédit :

• Crédit
• Annulation de crédit

Un conteneur Credit ne prend en charge qu'une seule transaction de crédit au cours de sa durée de vie. Toutefois, plusieurs annulations peuvent être prises en charge pour la même transaction de crédit.

Puisque ce conteneur est un objet de valeur, aucune transaction financière ne se produit dans cet objet. Cet objet contient des informations sur les transactions financières avant, pendant et après le traitement des transactions.

Les états suivants sont associés à un crédit :

Nouveau

Pour un objet de conteneur de crédit lorsqu'il est nouvellement créé.

Crédit

Une transaction de crédit est en cours.

Crédité

Une transaction de crédit réussie est terminée.

Annulé

Un crédit est complètement annulé.

Echec

Une transaction a échoué.

Pour illustrer comment un crédit se déplace d'un état à l'autre lorsque des transactions financières, des requêtes ou des modifications sont effectuées au niveau de ce paiement, voir la Machine d'état du crédit.

Deux types de transactions de crédit peuvent avoir lieu :

Crédit dépendant

Les crédits dépendants sont des transactions associées à PaymentInstruction lorsque des dépôts ont déjà eu lieu. Par exemple, après un dépôt de 100 dollars américains, un crédit pouvant atteindre 100 dollars américains serait considéré comme un crédit dépendant.

Crédit indépendant

Les crédits indépendants sont des transactions associées à PaymentInstruction où aucun dépôt antérieur n'a eu lieu, ou où le montant du crédit dépasse le montant précédemment déposé. Par exemple, après un dépôt de 100 $, un crédit de 150 $ est un crédit indépendant. En outre, sans aucun dépôt antérieur, un crédit de n'importe quel montant serait un crédit indépendant.

La prise en charge des crédits dépendants et indépendants peut varier d'un système dorsal de paiement à l'autre.

Un plug-in peut accéder aux conteneurs Payment associés pour déterminer si une transaction de crédit dépend d'une transaction de dépôt antérieure. Si tel est le cas, la transaction de crédit peut être traitée comme un crédit dépendant et le plug-in peut continuer. Dans le cas contraire, la transaction est un crédit indépendant.

Comprendre les classes de plug-in

Classe ExtendedData

Dans un contexte de plug-in de paiement, les données étendues sont des données de protocole non standard requises dans les transactions financières. La classe ExtendedData recueille les données de protocole non standard requises par une transaction financière. Les plug-ins nécessitent des données de protocole supplémentaires qui vont au-delà des attributs standard définis dans un conteneur PaymentInstruction. Ces attributs supplémentaires sont transmis entre le Contrôleur des plug-in de paiement et un plug-in à l'aide de la classe ExtendedData.

Lorsqu'elle est associée à PaymentInstruction, la classe ExtendedData est potentiellement utilisée par toutes les transactions financières effectuées sur la même instruction PaymentInstruction.

Toutefois, ExtendedData peut également être joint à un conteneur FinancialTransaction particulier afin que les attributs supplémentaires ne soient utilisés que dans le même conteneur FinancialTransaction. Les transactions financières ultérieures peuvent réutiliser le contenu de la classe ExtendedData si elles sont liées à un conteneur FinancialTransaction précédent.

NamedValueObject

La classe NamedValueObject représente un attribut de données avec un nom, une valeur et un indicateur de chiffrement. Ces objets sont généralement utilisés pour stocker des informations sur un protocole et composent la classe ExtendedData. Si l'indicateur de chiffrement est défini sur la paire nom-valeur, les valeurs d'attribut sont chiffrées lorsqu'elles sont stockées dans la base de données HCL Commerce.

PluginMessages

La classe PluginMessages définit les messages traduits standard et l'utilitaire pour récupérer ces messages. Pour obtenir une liste des messages plug-in standard, consultez les informations d'API de cette classe. Les messages de plug-in sont inclus dans les messages d'exception enregistrés. Le composant de traçage prédéfini HCL Commerce, WC_PPC_PLUGIN, est utilisé comme nom de l'enregistreur WebSphere Application Server pour les messages de plug-in.

Le fichier de propriétés pour les messages est situé dans le répertoire suivant :

• 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

Gestion des erreurs du plug-in Payment

La spécification de plug-in de paiement identifie un ensemble d'exceptions prédéfinies. Si un plug-in n'implémente pas une méthode particulière, il doit lancer l'exception FunctionNotSupportedException. Si d'autres exceptions doivent être ajoutées pour un plug-in, l'exception PluginException doit être étendue. Toutefois, le Contrôleur des plug-in de paiement ne sera pas en mesure de traiter ces exceptions d'une manière spécifique. Même si toutes les exceptions sont interceptées, les erreurs spécifiques au plug-in ne peuvent pas être traitées correctement. Par exemple, FinancialException informe le Contrôleur des plug-in de paiement qu'une erreur financière s'est produite et que le Contrôleur des plug-in de paiement peut agir en informant d'autres couches logicielles, telles que le Moteur de règles de paiement. Toutefois, si ABCException se produit, cette exception est enveloppée comme une exception de plug-in générique.

Les exceptions qui sont lancées par un plug-in doivent contenir autant d'informations contextuelles que possible pour permettre un traitement pratique des erreurs et la détermination des problèmes. Les informations peuvent inclure les codes de résultats du système dorsal de paiement et la référence des conteneurs à l'instruction de paiement, au paiement et au crédit.

Pour des situations exceptionnelles, lancez PluginException (ou exception) dans votre plug-in de paiement.

InvalidDataException

Si l'échec de la transaction de paiement est causé par des informations de paiement non valides qu'un client saisit, vous pouvez lancer une exception InvalidDataException avec votre clé de message et votre regroupement de ressources.

InvalidDataException ie = new InvalidDataException();  ie.setMessageKey(your message key);  ie.setFormatArguments(your message arguments);  ie.setResourceBundleName(your resource bundle); throw ie;

Cette exception est mappée à ECApplicationException avec un message d'erreur qui contient le message de InvalidDataException. Par exemple :

A generic payment user exception occured. The exception is as follows: "error message of InvalidDataException"

Si vous ne souhaitez pas de messages supplémentaires autres que ceux que vous avez définis dans invalidDataException, vous pouvez remplacer la définition de message NLV dans le regroupement de ressources. Le regroupement de ressources se trouve dans le répertoire suivant :

• WC_eardir/Stores.war/WEB-INF/classes/storedir
• workspace_dir\Stores\Web Content\WEB-INF\classes\storedir

Par exemple, vous pouvez ajouter des messages en anglais dans ce fichier : storeErrorMessages_en_US.properties.

_ERR_PAYMENT_GENERIC_USER_EXCEPTION={0}

Ensuite, le message d'erreur suivant s'affiche dans votre page de magasin :

error message of InvalidDataException

Les messages d'erreur peuvent s'afficher sur la page de magasin. Vous n'avez pas besoin de personnaliser le regroupement de ressources tel que décrit dans l'exemple précédent.

CommunicationException

Si votre plug-in de paiement rencontre un problème de connectivité lorsque le plug-in communique avec le système dorsal de paiement. Vous pouvez lancer une exception CommunicationException avec votre clé de message et votre regroupement de ressources.

CommunicationException ce = new CommunicationException(); ce.setMessageKey(your message key); ce.setFormatArguments(your message arguments); ce.setResourceBundleName(your resource bundle); throw ce; 

Cette exception est mappée à ECSystemException avec un message d'erreur qui contient le contenu du message d'erreur CommunicationException : Echec de l'exécution de l'action de paiement en raison de {error message of CommunicationException} Si vous ne voulez pas de contenu de message autre que celui que vous avez défini dans CommunicationException, vous pouvez remplacer la définition de message NLV dans le regroupement de ressources de votre magasin sous le répertoire suivant :

• WC_eardir/Stores.war/WEB-INF/classes/storedir
• workspace_dir\Stores\WebContent\WEB-INF\classes\storedir

Par exemple, si votre magasin ne s'adresse qu'à la langue anglaise, vous pouvez ajouter la définition de message NLV suivante dans storeErrorMessages_en_US.properties sous ce répertoire : _ERR_PAYMENT_DO_PAYMENT_ACTIONS_POLICY_CMD={1}. Ensuite, le message d'erreur qui s'affiche dans votre page de magasin devient : message d'erreur de CommunicationException. Puisque l'exception CommunicationException est mappée à ECSystemException, ce qui annule la transaction globale HCL Commerce, la demande de paiement serait soumise de nouveau si la commande de contrôleur HCL Commerce d'appel est configurée sur retriable=1.

Par exemple, la commande OrderProcescsCmd est configurée de telle sorte que si cette exception se produit en raison d'une défaillance d'autorisation de paiement lors d'une commande soumise, cette commande est réessayée et l'autorisation de paiement est à nouveau déclenchée. Si vous ne souhaitez pas que la commande soit réessayée dans une telle situation, définissez la commande d'appel sur retriable=0 pour la table de base de données CMDREG. Ne définissez pas cette commande pour qu'elle ne réessaie pas ECSystemException, car la commande doit réessayer pour gérer des situations exceptionnelles.

FunctionNotSupportedException

Si ce type de transaction financière n'est pas pris en charge par votre implémentation plug-in, vous pouvez lancer FonctionNotSupportedException avec votre clé de message et votre regroupement de ressources. Par exemple, si le plug-in ne prend pas en charge l'API approveAndDeposit, mais que le commerçant tente d'appeler cette API, alors l'exception fonctionNotSupportedException est lancée. Cette exception est mappée à ECApplicationException. Ainsi, le comportement après le lancement de cette exception est similaire à InvalidDataException.

ConfigurationException

Si votre plug-in de paiement ne trouve pas les informations requises dans la configuration du plug-in, vous pouvez lancer configurationException avec votre clé de message et votre regroupement de ressources. Par exemple, si la configuration du fichier XML de déploiement plug-in n'est pas valide, l'exception ConfigurationException est lancée. Cette exception est mappée à ECSystemException. Ainsi, le comportement après le lancement de cette exception est similaire à CommunicationException.

InternalErrorException

Si votre plug-in de paiement rencontre une erreur inattendue dans l'implémentation du plug-in, vous pouvez lancer InternalErrorException avec votre clé de message et votre regroupement de ressources. Par exemple, si le plug-in reçoit la réponse depuis la passerelle du prestataire de services de paiement avec un format non valide, alors l'exception InternalErrorException est lancée. Cette exception est mappée à ECSystemException. Ainsi, le comportement après le lancement de cette exception est similaire à CommunicationException.

TimeoutException

Si votre plug-in de paiement expire dans l'attente d'une réponse, vous pouvez lancer TimeoutException avec votre clé de message et votre regroupement de ressources. Par exemple, si le plug-in est configuré de telle sorte que le délai d'attente pour une réponse est terminé et qu'il n'y a pas de réponse, alors l'exception TimeoutException est lancée. L'exception TimeoutException est lancée par le Contrôleur des plug-in de paiement. Si vous lancez ce type d'exceptions, la transaction HCL Commerce globale n'est pas annulée. Au lieu de cela, l'état de paiement est défini sur En attente. Si le prestataire de services de paiement prend en charge le nouvel essai de transaction de paiement, alors vous pouvez lancer cette exception lorsque vous ne recevez pas la réponse.

FinancialException

L'exception FinancialException est lancée par le Contrôleur des plug-in de paiement. Si vous utilisez cette exception, la transaction HCL Commerce globale n'est pas annulée. Au lieu de cela, l'état de paiement impliqué est défini sur Echec. Si vous souhaitez capturer la commande dans l'éventualité où un paiement ne s'exécute pas, utilisez FinancialException dans votre plug-in. Il y a trois exceptions FinancialException :

ApprovalExpiredException

Cette exception se produit lors de l'expiration de l'approbation de paiement (autorisation). Cette exception est différente des deux exceptions suivantes, car elle n'est pas mappée à ECSystemException.

InvalidPaymentInstructionExcepiton

Cette exception a pour but d'indiquer que PaymentInstruction n'est pas valide.

PaymentInstructionBlockedException

Cette exception se produit lorsqu'une transaction financière ne peut pas être traitée en se basant sur PaymentInstruction. Cette exception est une situation temporaire. La transaction financière peut être essayée à nouveau après un certain temps, en se basant sur la même instruction PaiementInstruction. Par exemple, la carte de crédit associée à une instruction de paiement peut être mise en attente. Le comportement de InvalidPaymentInstructionException et de PaymentInstrutionBlockedException est le même que celui de FinancialException.

PluginException

Si vous ne trouvez pas d'exception appropriée à partir des exceptions précédentes, vous pouvez utiliser PluginException. Cette exception est mappée à ECSystemException. Ainsi, le comportement après le lancement de cette exception est similaire à CommunicationException.

1. Seules les exceptions CommunicationException et InternalErrorException sont mappées à ECSystemException, tandis que toutes les autres exceptions de plug-in sont mappées à ECApplicationException.
2. Lorsque les exceptions de plug-in sont mappées à ECException, la clé de message du regroupement de ressources définie dans les exceptions de plug-in est composée dans un nouvel objet ECMessage. Cet objet utilise la clé de message du regroupement de ressources comme clé de message de ECException. Dans la page de magasin, le message d'erreur défini dans le plug-in s'affiche sans contenu supplémentaire. Dans ce cas, il n'est pas nécessaire de procéder à une personnalisation.

Remarques sur la sécurité pour les plug-ins de paiement

Les plug-ins Payment sont responsables de la sécurité de la communication avec leurs systèmes dorsaux de paiement. Etant donné que les informations de paiement sont des données sensibles, les plug-ins chiffrent toutes les données envoyées sur les connexions réseau. Le Contrôleur des plug-in de paiement ne fournit not des services de chiffrement pour ce type de communication avec le système dorsal de paiement.

Toutes les données sensibles d'un conteneur PaymentInstruction sont chiffrées par le Contrôleur des plug-in de paiement lorsqu'elles sont conservées dans la table PPCEXTDATA.

Si le plug-in conserve des données sensibles dans le système de fichiers ou à l'aide de bases de données, chiffrez les données sensibles. Le Contrôleur des plug-in de paiement ne fournit pas de services de chiffrement pour cette conservation.

Si vous utilisez le contrôle d'accès Java EE ou EJB, la documentation de plug-in que vous produisez doit identifier clairement les rôles utilisateur requis et les autorisations d'utilisation de l'implémentation du plug-in. Cette documentation est nécessaire pour que vous puissiez déployer le plug-in.

Les données sensibles transitoires, par exemple, le code de validation de carte, sont transmises au plug-in en tant que données étendues de l'instruction de paiement en cours. Vous pouvez récupérer les données de votre plug-in et les transmettre au système dorsal de paiement si nécessaire. Evitez de conserver ou de supprimer des données sensibles transitoires dans le plug-in. Le contrôleur de plug-in Payments est chargé de supprimer les données sensibles transitoires et d'empêcher la conservation des données dans la base de données.