{
"completionId": 1231231,
"spaceId": 12,
"amount": 12.96,
"transactionId": 542131,
"merchantReference": "Some reference from the merchant for this completion",
"lastCompletion": true,
}Les Payment Web Apps permettent d’intégrer des services de paiement qui ne sont pas directement intégrés à notre service.
Les Payment Web Apps sont en général simplement des Web Apps normales dotées de la capacité de traiter des paiements.
À un niveau général, vous devez effectuer les étapes suivantes pour intégrer le traitement des paiements à votre Web App :
Vous devez intégrer le processus d’installation pour votre Web App.
Vous devez utiliser le service REST Payment Web App pour ajouter un processeur correspondant et un ou plusieurs connecteurs.
Vous devez fournir une URL sur laquelle vous pouvez présenter une page de paiement permettant à l’acheteur de confirmer le paiement.
L’acheteur confirme le paiement sur votre page de paiement. Vous renvoyez le résultat via JavaScript.
En arrière-plan, vous informez également notre backend du résultat du traitement du paiement. Pour cela, vous utilisez l’opération de mise à jour de la tentative de débit.
En option, vous pouvez aussi permettre au marchand d’effectuer des complétions différées et d’exécuter des remboursements.
La section suivante vous guide à travers les détails du processus permettant de réaliser une telle intégration.
L’installation du processeur et des connecteurs s’effectue via le service REST Payment Web App. Pour pouvoir les installer, vous devez d’abord avoir accès au Space du marchand. Pour cela, veuillez suivre les instructions expliquant comment réaliser l’installation d’une web app.
Une fois la Web App installée dans le Space du marchand, les identifiants de la Web App permettent l’installation des processeurs et des connecteurs. Dans le cadre du processus d’installation, vous pouvez demander au marchand de vous accorder certaines permissions. Pour pouvoir ensuite installer les processeurs et les connecteurs, vous devez demander la permission Payment Web Apps (ID: 1627022088852).
Une fois que vous avez demandé au marchand la permission d’accéder au Space, utilisez l’opération d’insertion de processeur pour ajouter un nouveau processeur.
Lors de l’insertion du processeur, vous devez fournir un externalId. Cet ID doit être unique par Space. Si
le service est invoqué plusieurs fois avec le même externalId, le processeur est mis à jour et aucun nouveau processeur n’est inséré.
|
Note
|
Lorsque le marchand désinstalle votre Web App, les processeurs associés sont également supprimés. |
Une fois que vous avez ajouté un processeur, vous pouvez également insérer un connecteur. Pour ce faire, vous devez utiliser l’opération d’insertion de connecteur.
externalId : comme pour le processeur, vous devez fournir un externalId. Cet ID doit être unique. Les requêtes avec
le même externalId mettent à jour le connecteur au lieu d’en insérer un nouveau.
processorExternalId : le connecteur est toujours associé à un processeur. Vous devez donc également fournir le processorExternalId
du processeur ajouté précédemment.
completionConfiguration et refundConfiguration : en fournissant les configurations correspondantes, vous contrôlez si
les remboursements et les complétions différées sont pris en charge. Gardez à l’esprit qu’une fois que vous avez indiqué prendre en charge ces fonctionnalités optionnelles, vous
ne pouvez plus les désactiver sur le connecteur via un appel de mise à jour.
paymentPageEndpoint : le paymentPageEndpoint reçoit les demandes de paiement.
Voir Gestion de la page de paiement pour plus de détails.
connector : le connector définit quel mode de paiement (et éventuellement aussi quelle marque) est associé à votre nouveau
connecteur de Web App. Voir ci-dessous les connecteurs que vous pouvez fournir.
Voir connecteurs pris en charge pour la liste complète des connecteurs pris en charge.
Le processeur est par défaut automatiquement prêt à être utilisé dans l’environnement de production. Si vous souhaitez d’abord intégrer le
marchand dans un mode test puis passer plus tard en mode live, c’est possible. Lorsque vous créez un nouveau processeur, vous pouvez définir la productionModeUrl. Si
vous fournissez cette URL, l’utilisateur sera redirigé vers cette URL dès que le processeur passera en mode production.
Les paramètres suivants seront ajoutés à l’URL :
timestamp : l’heure sous forme de timestamp Unix (secondes depuis janvier 1970). Il empêche les attaques par rejeu. Vous devez donc vous assurer qu’il n’est pas trop ancien.
externalId : l’ID du processeur tel que fourni lors de sa création via l’API de service web. Il vous aide à identifier le processeur de votre côté.
returnUrl : lorsque l’utilisateur a terminé l’activation, vous pouvez le rediriger vers cette URL. Vous pouvez en outre ajouter un
message et un type. Le message peut contenir un message pour l’utilisateur et le type indique s’il s’agit d’un failure ou d’un success.
spaceId : l’ID du Space indique dans quel Space le processeur a été installé.
hmac : le HMAC permet de vérifier si l’utilisateur provient réellement de nos serveurs. Le calcul du hmac fonctionne de la même manière que pour les autres HMAC.
|
Note
|
Veuillez inclure tous les paramètres que vous recevez sur l’URL. Nous pourrions étendre la liste des paramètres à l’avenir. Dans ce cas, nous les inclurons également dans le calcul du HMAC. |
Lors de l’installation du connecteur, vous devez fournir un endpoint de page de paiement. Cette URL d’endpoint sera invoquée par l’acheteur pendant le traitement du paiement.
Cette invocation permet de traiter le paiement en demandant des détails supplémentaires, en authentifiant l’acheteur, etc. L’endpoint de page de paiement doit fournir le comportement suivant :
Vérifiez l’origine de la requête. La requête contient un HMAC qui permet de vérifier l’origine de la requête. Vous pouvez ainsi être sûr que la requête est légitime.
Demandez des détails supplémentaires à l’utilisateur. Par exemple, vous demandez à l’utilisateur de s’authentifier. Cette étape peut aussi être ignorée lorsqu’elle n’est pas nécessaire.
Une fois le résultat du traitement connu, vous invoquez le JavaScript correspondant pour renvoyer le résultat du traitement du paiement. Ce retour n’est utilisé qu’au sein du client. Il déclenche dans le client le changement de l’interface utilisateur afin que l’utilisateur connaisse le résultat. Si quelque chose se passe mal avec le paiement et que le client plante, vous devez également renvoyer le résultat en arrière-plan à notre backend.
Les deux sections suivantes couvrent plus en détail la première et la dernière étape du processus.
Lorsque l’acheteur invoque l’URL de l’endpoint de la page de paiement, les paramètres suivants font partie de la requête GET :
transactionId : l’ID de transaction référence la transaction en cours de traitement. Si le marchand l’autorise, il peut y avoir plusieurs tentatives de débit par transaction.
chargeAttemptId : l’ID de tentative de débit référence la tentative de débit effectuée dans le cadre de cette invocation.
language : la langue indique la langue parlée par l’acheteur. La page de paiement doit donc être rendue dans cette
langue. Le paramètre language est au format du tag de langue IETF. Par exemple de-DE.
currency : la devise contient le code ISO à 3 lettres de la devise (p. ex. USD, EUR, CHF, etc.).
returnUrl : lorsque le paiement est terminé, vous devez rediriger l’utilisateur vers cette URL.
amount : le montant correspond au montant qui doit être débité. Le format du montant est un nombre décimal normal. Par exemple 10.56. Veuillez
garder à l’esprit que vous devrez peut-être utiliser une structure de données dédiée pour le gérer correctement. Par exemple, en Java, vous devriez utiliser un BigDecimal.
Le nombre de décimales dépend de la devise.
authorizationEnvironment : l’environnement dans lequel le paiement doit être effectué. La valeur peut être TEST ou PRODUCTION.
Si la valeur est TEST, vous devez seulement exécuter un paiement simulé. Aucun argent ne doit être déplacé dans ce cas.
completionBehavior : le comportement de complétion indique si le paiement doit être complété IMMEDIATELY ou DEFERRED.
Si le connecteur ne prend pas en charge la fonctionnalité de complétion différée, le completionBehavior sera toujours IMMEDIATELY.
spaceId : l’ID du Space référence le Space dans lequel la web app a été installée.
connectorExternalId : il s’agit de l’ID du connecteur qui doit exécuter le paiement. L’ID correspond à
l’ID fourni lors de la création du connecteur.
merchantReference : la référence marchand aide le marchand à identifier le paiement. Lorsque cela a du sens, ajoutez cette référence au
paiement. Elle n’est pas unique mais aide normalement l’acheteur et le marchand à comprendre à quelle commande le paiement appartient.
hmac : le hmac contient le hachage des paramètres ci-dessus, sécurisé avec le secret de la Web App. Le calcul du hmac
fonctionne comme pour les autres HMAC liés aux Web Apps. Veuillez inclure tous les paramètres fournis
dans la requête HTTP (à l’exclusion des paramètres déjà présents dans l’URL de l’endpoint). Nous pourrions ajouter d’autres paramètres à l’avenir
et vous devez les inclure, sinon le traitement ne fonctionnera plus.
Si les paramètres ci-dessus ne contiennent pas ce dont vous avez besoin pour traiter le paiement, vous pouvez récupérer l’objet transaction via l’API REST. Dans ce cas, vous devrez peut-être demander davantage de permissions lors de l’installation de la Web App.
La requête contient un chargeAttemptId. Chaque transaction peut avoir plusieurs tentatives de débit. Chaque tentative essaie de débiter le consommateur. Si une tentative réussit, la transaction
est marquée comme authorized. Cela implique qu’une transaction peut avoir au plus une tentative de débit successful. Vous voudrez peut-être vérifier cela de votre côté
et vous assurer que cela ne pose jamais de problème. Toute opération ultérieure (remboursement, annulation et complétion) référencera simplement la transaction.
|
Note
|
Vous devez valider le HMAC pour garantir que le système ne peut pas être manipulé. Si vous omettez cette vérification, un attaquant pourrait être en mesure de falsifier un paiement. |
|
Note
|
Veuillez inclure tous les paramètres que vous recevez sur l’URL. Nous pourrions étendre la liste des paramètres à l’avenir. Dans ce cas, nous les inclurons également dans le calcul du HMAC. |
Une fois que vous avez traité la tentative de débit, vous devez nous communiquer l’état de la tentative de débit. Vous devez le faire avant de rediriger l’utilisateur
vers la returnUrl. À cette fin, vous devez utiliser l’opération de l’API REST de mise à jour de la tentative de débit.
Le prestataire de services externe peut décider de proposer également la complétion différée. Cela signifie que le marchand autorise d’abord un
montant, puis complète dans un deuxième temps un montant différent. Pour permettre un tel processus en deux étapes, le connecteur doit contenir la
propriété de configuration completionConfiguration. Lors de la création du connecteur, vous pouvez ajouter la propriété correspondante.
|
Note
|
Lorsque le connecteur a une fois pris en charge la complétion différée, elle ne peut plus être désactivée. Une mise à jour qui supprime la configuration de complétion échouera donc. |
Le paramètre completionBehavior dans la requête de la page de paiement indique si le paiement doit être complété directement
ou si une demande de complétion suivra plus tard. IMMEDIATELY signifie que le paiement doit être comptabilisé directement.
Lorsque le marchand exécute une demande de complétion, le completionEndpoint défini dans la completionConfiguration
est invoqué. La requête HTTP POST envoyée à l’endpoint contient le corps suivant :
{
"completionId": 1231231,
"spaceId": 12,
"amount": 12.96,
"transactionId": 542131,
"merchantReference": "Some reference from the merchant for this completion",
"lastCompletion": true,
}Description des paramètres :
completionId : cet ID référence la complétion dans nos systèmes. Vous pouvez aussi utiliser l’API de service web pour lire l’objet complétion
avec cet ID et récupérer plus de détails. Combiné au spaceId, le completionId est unique.
spaceId : l’ID du Space référence le Space auquel la complétion appartient.
amount : le montant correspond au montant qui doit être complété.
transactionId : l’ID de la transaction référence l’objet transaction.
merchantReference : la référence marchand correspond à une référence du marchand aidant à identifier cette complétion.
lastCompletion : ce drapeau indique s’il s’agit de la dernière complétion ou si une autre complétion peut suivre.
La requête HTTP avec le message JSON ci-dessus est répétée jusqu’à ce que le comopletionEndpoint réponde avec un code de statut HTTP 2xx. Le retour
sur l’état de la complétion doit être fourni via une invocation
de l’opération de l’API REST de mise à jour de la complétion. Ce retour doit avoir lieu
dans les completionTimeoutInMinutes. Sinon, nous considérons la complétion comme échouée.
Si le marchand décide de ne pas compléter la transaction, nous exécutons une annulation (void). Lorsque le marchand a déclenché une ou plusieurs complétions, aucune annulation ne peut plus être déclenchée.
Lorsque le marchand déclenche une annulation, le voidEndpoint défini dans la completionConfiguration reçoit le corps de requête HTTP POST suivant :
{
"voidId": 65437,
"spaceId": 12,
"transactionId": 542131,
}Description des paramètres :
voidId : cet ID référence l’annulation dans nos systèmes. Vous pouvez aussi utiliser l’API de service web pour lire l’objet void
avec cet ID et récupérer plus de détails. Combiné au spaceId, le voidId est unique.
spaceId : l’ID du Space référence le Space auquel l’annulation appartient.
transactionId : l’ID de la transaction référence l’objet transaction.
La requête HTTP avec le message JSON ci-dessus est répétée jusqu’à ce que le voidEndpoint réponde avec un code de statut HTTP 2xx. Le retour
sur l’état de l’annulation doit être fourni via une invocation
de l’opération de l’API REST de mise à jour de l’annulation. Ce retour doit avoir lieu
dans les completionTimeoutInMinutes. Sinon, nous considérons l’annulation comme échouée.
Les remboursements permettent à un marchand de rendre de l’argent à l’acheteur. Le marchand ne peut déclencher un tel remboursement que lorsque le connecteur prend en charge les remboursements. Lors de
la création du connecteur, la propriété refundConfiguration active les remboursements pour le connecteur correspondant. Lorsqu’un connecteur
a une fois pris en charge les remboursements, cela ne peut plus être désactivé. Une mise à jour du connecteur qui ne contient plus la refundConfiguration
échouera donc.
Lorsque le marchand déclenche un remboursement, nous invoquons le refundEndpoint. Le corps de la requête HTTP POST contient le JSON suivant :
{
"refundId": 5623,
"spaceId": 12,
"amount": 12.96,
"merchantReference": "Some reference from the merchant for this refund",
"transactionId": 542131,
}Description des paramètres :
refundId : cet ID référence le remboursement dans nos systèmes. Vous pouvez aussi utiliser l’API de service web pour lire l’objet remboursement
avec cet ID et récupérer plus de détails. Combiné au spaceId, le refundId est unique.
spaceId : l’ID du Space référence le Space auquel le remboursement appartient.
amount : le montant correspond au montant qui doit être remboursé à l’acheteur.
transactionId : l’ID de la transaction référence l’objet transaction.
merchantReference : la référence marchand correspond à une référence du marchand aidant à identifier ce remboursement.
La requête HTTP avec le message JSON ci-dessus est répétée jusqu’à ce que le refundEndpoint réponde avec un code de statut HTTP 2xx. Le retour
sur l’état du remboursement doit être fourni via une invocation
de l’opération de l’API REST de mise à jour du remboursement. Ce retour doit avoir lieu
dans les refundTimeoutInMinutes. Sinon, nous considérons le remboursement comme échoué.