Service de traitement des paiements

Le service de traitement des paiements est un service Web entrant, dont le rôle est de traiter les transactions financières en ligne, telles que les autorisations de paiement et les captures de paiement. Ce service Web entrant est généralement appelé, dans une solution intégrée, par un système externe qui n'est pas directement relié aux prestataires de services de paiement, mais qui fait traiter ses transactions financières en ligne par le système de traitement des paiements de HCL Commerce et ses plug-ins de paiement.

Cas d'utilisation typiques

  • Autorisation de paiement avec une carte de crédit non encore capturée comme instruction de paiement
  • Capture d'un paiement, sachant qu'un autre paiement a déjà été autorisé dans le cadre d'une précédente transaction financière

URL du point d'extrémité et opération du service Web

L'URL de nœud final par défaut de ce service Web entrant est https://hostname:8000/webapp/wcs/services/PaymentServices. L'opération mise à disposition par ce service Web entrant est ProcessFinancialTransaction, avec le BOD ProcessFinancialTransaction pour la requête et le BOD AcknowledgeFinancialTransaction pour la réponse.

Demande

Les requêtes adressées à ce service Web entrant ont la forme de documents BOD (Business Object Documents) ProcessFinancialTransaction. Elles seront mappées à la commande PaymentProcessFinancialTransaction et devront contenir les informations suivantes :

XPath* Type Mappé au paramètre de commande suivant Description Obligatoire
DataArea/Process/ActionCriteria/ ActionExpression/@actionCode chaîne actionCode Le code d'action. Doit être "Approve", "Deposit", "ApproveAndDeposit", "Credit", "ReverseApproval", "ReverseDeposit" ou "ReverseCredit". O
DataArea/FinancialTransaction@type chaîne actionCode Doit être identique au code d'action. O
DataArea/FinancialTransaction/ RequestedAmount decimal amount Le montant demandé. O
DataArea/FinancialTransaction/ RequestedAmount@currency chaîne currency Devise dans laquelle est exprimé le montant demandé. O
DataArea/FinancialTransaction/Payment/

PaymentIdentifier/PaymentID

long paymentId ID du paiement HCL Commerce à associer à la transaction financière. Un nouveau paiement sera créé si paymentID n'est pas spécifié. Facultatif pour les codes d'action "Approve" et "ApproveAndDeposit", requis pour "Deposit", "ReverseApproval" et "ReverseDeposit". N
DataArea/FinancialTransaction/Credit/ CreditIdentifier/CreditID long creditId ID du crédit HCL Commerce à associer à la transaction financière. Un nouveau crédit sera créé si creditID n'est pas spécifié. Optionnel pour les codes d'action "Credit" ; obligatoire pour "ReverseCredit". N
DataArea/FinancialTransaction/*/ PaymentInstruction/PaymentInstructionIdentifier/ PaymentInstructionID long paymentInstructionId ID de l'instruction de paiement HCL Commerce à associer à la transaction financière et au paiement (ou au crédit). Un nouveau paiement et une instruction de paiement seront créés à partir des informations fournies si aucun ID de paiement (ou de crédit) ni aucun ID d'instruction de paiement n'est spécifié. N
DataArea/FinancialTransaction/*/ PaymentInstruction/StoreID int storeId HCL Commerce ID de magasin de l'instruction de paiement. Obligatoire en cas de création d'une nouvelle instruction de paiement. N
DataArea/FinancialTransaction/*/ PaymentInstruction/OrderIdentifier/OrderID long orderId HCL Commerce ID de commande de l'instruction de paiement, si applicable. Utilisé en cas de création d'une nouvelle instruction de paiement. N
DataArea/FinancialTransaction/*/ PaymentInstruction/PaymentConfigurationID chaîne paymentConfigurationGroupId L'ID de configuration de paiement HCL Commerce. Sauf indication contraire, la valeur de ce champ doit être "default". Obligatoire en cas de création d'une nouvelle instruction de paiement. N
DataArea/FinancialTransaction/*/ PaymentInstruction/PaymentSystemName chaîne paymentSystemName Nom du système de paiement HCL Commerce à associer à l'instruction de paiement ; par exemple, "SimpleOffline". Obligatoire en cas de création d'une nouvelle instruction de paiement et si le nom du mode de paiement n'est pas spécifié. N
DataArea/FinancialTransaction/*/ PaymentInstruction/PaymentMethodName chaîne paymentMethodName Nom du mode de paiement HCL Commerce à associer à l'instruction de paiement ; par exemple, "VISA". Obligatoire en cas de création d'une nouvelle instruction de paiement et si le nom du système de paiement n'est pas spécifié. N
DataArea/FinancialTransaction/*/ PaymentInstruction/ExtendedData[i]/@name chaîne extendedDataName_i Nom de la i-th donnée étendue de l'instruction de paiement. Obligatoire en cas de création d'une nouvelle instruction de paiement. Certains plug-ins de paiement peuvent nécessiter des données étendues qui leur sont propres ; consultez leur documentation pour les détails. N
DataArea/FinancialTransaction/*/ PaymentInstruction/ExtendedData[i] chaîne extendedDataValue_j Valeur de la i-th donnée étendue de l'instruction de paiement. Obligatoire en cas de création d'une nouvelle instruction de paiement. N

* Les préfixes d'espace de noms sont omis pour simplifier la présentation.

Exemples

Réponse

Les réponses de ce service Web entrant ont la forme de documents BOD AcknowledgeFinancialTransaction. Elles contiennent les informations suivantes :

XPath* Type Description
DataArea/FinancialTransaction/FinancialTransactionIdentifier/ FinancialTransactionID long ID de la transaction financière HCL Commerce.
DataArea/FinancialTransaction/RequestedAmount decimal Le montant demandé.
DataArea/FinancialTransaction/RequestedAmount/@currency chaîne Devise dans laquelle est exprimé le montant demandé.
DataArea/FinancialTransaction/ProcessedAmount decimal Le montant effectivement traité (par exemple, approuvé). 0 si la transaction financière est en attente (état Pending).
DataArea/FinancialTransaction/ProcessedAmount/@currency chaîne Devise dans laquelle est exprimé le montant traité.
DataArea/FinancialTransaction/State chaîne Etat de la transaction financière. L'état peut être :
  • "Pending" - la transaction financière est en attente, ce qui est généralement le cas lorsqu'il s'agit d'une transaction hors ligne.
  • "Success" - la transaction financière a réussi.
  • "Failed" - la transaction financière a échoué.
  • "Canceled" - la transaction financière a été annulée avant d'être achevée.
DataArea/FinancialTransaction/ReferenceNumber chaîne Numéro de référence de la transaction financière renvoyé par le fournisseur de services de paiement.
DataArea/FinancialTransaction/ResponseCode chaîne Code de réponse renvoyé par le fournisseur de services de paiement. Généralement 0 (zéro) si la transaction financière a réussi ou une valeur non nulle si elle a échoué ; sinon, il s'agit d'un code spécifique au plug-in de paiement. Reportez-vous à la rubrique Spécification de plug-in Payment pour plus d'informations.
DataArea/FinancialTransaction/ReasonCode chaîne Code raison (ou code de réponse secondaire) renvoyé par le prestataire de services de paiement. Généralement 0 (zéro) si la transaction financière a réussi ou une valeur non nulle si elle a échoué ; sinon, il s'agit d'un code spécifique au plug-in de paiement. Reportez-vous à la rubrique Spécification de plug-in Payment pour plus d'informations.
DataArea/FinancialTransaction/ReasonMessage chaîne Message de raison renvoyé par le fournisseur de services de paiement. Généralement défini uniquement si la transaction financière a échoué ; sinon, il est spécifique au plug-in de paiement. Reportez-vous à la rubrique Spécification de plug-in Payment pour plus d'informations.
DataArea/FinancialTransaction/TrackingID chaîne ID de suivi renvoyé par le plug-in de paiement. Reportez-vous à la rubrique Spécification de plug-in Payment pour plus d'informations.
DataArea/FinancialTransaction/TimeCreated dateTime Date et heure de création de la transaction financière.
DataArea/FinancialTransaction/TimeUpdated dateTime Date et heure de dernière mise à jour de la transaction financière.
DataArea/FinancialTransaction/Payment/PaymentIdentifier/PaymentID long ID du paiement HCL Commerce associé à la transaction financière. Donnée à stocker pour les futures transactions financières rattachées au même paiement ; par exemple, la demande de capture de paiement faisant suite à la demande d'autorisation de paiement.

* Les préfixes d'espace de noms sont omis pour simplifier la présentation.

Exemples

Exceptions

Toutes les exceptions sont renvoyées sous forme de documents BOD AcknowledgeFinancialTransaction avec un élément ResponseCriteria sous le verbe Acknowledge. Elles contiennent les informations suivantes :

XPath* Type Description
DataArea/Acknowledge/ResponseCriteria/ChangeStatus/Code chaîne L'identificateur de corrélation. Peut être utilisé pour identifier de manière unique une exception dans les journaux du serveur.
DataArea/Acknowledge/ResponseCriteria/ChangeStatus/ReasonCode chaîne Le code raison, qui est soit un HCL Commercecode d'erreur système HCL Commercecode d'erreur système plus un code d'erreur secondaire en option, si le code d'erreur système de HCL Commerce n'est pas disponible (ce qui est généralement le cas lorsque l'exception est émise par l'application).
DataArea/Acknowledge/ResponseCriteria/ChangeStatus/Reason chaîne Le message de l'exception.

* Les préfixes d'espace de noms sont omis pour simplifier la présentation.

Exemples

Remarque : Les attributs releaseID et versionID doivent être à blanc lorsque le service de traitement des paiements est appelé. Ignorez ceux qui sont renvoyés dans le BOD de réponse.