Gestion des wallets acheteur

Un wallet (portefeuille électronique) permet à un acheteur de stocker plusieurs cartes de paiement et de choisir laquelle utiliser au moment de l'achat, sans avoir à saisir son numéro de carte. L'acheteur peut à tout moment demander la suppression d'une carte enregistrée dans son wallet.

Les données bancaires sont stockées par la plateforme de paiement, en respect des règles imposées par la RGPD (= Règlement Général sur la Protection des Données).

Principe d'utilisation

Lors de l'affichage du formulaire, l'acheteur a plusieurs possibilités :

payer sans enregistrer son moyen de paiement,
payer et enregistrer son moyen de paiement.

Si l'acheteur choisit d'enregistrer les données de moyen de paiement, la plateforme de paiement les stocke et les associe à sa référence acheteur (wallet acheteur).
Lors de son prochain achat, l'acheteur aura alors plusieurs choix possibles :

payer en utilisant un moyen de paiement précédemment enregistré dans son wallet acheteur,
payer avec un nouveau moyen de paiement et l'ajouter à son wallet acheteur,
payer avec un nouveau moyen de paiement sans l'ajouter à son wallet acheteur,
supprimer un moyen de paiement précédemment enregistré dans son wallet acheteur.

Les moyens de paiement expirés ne sont pas proposés.

Moyens de paiement éligibles

AMEX
CB
Cartes Titre-Restaurant
VISA
VISA ELECTRON
MASTERCARD
MAESTRO

Mise en oeuvre

Le site marchand doit associer une référence unique à chaque acheteur (par exemple l'identifiant du compte client sur le site marchand). Le site marchand doit s'assurer de l'unicité de cette référence.
Pour proposer l'utilisation d'un wallet acheteur lors du paiement, le site marchand doit :

appeler le Web Service Charge/CreatePayment,
transmettre la référence acheteur dans le champ customer.reference
transmettre le champ formAction avec la valeur CUSTOMER_WALLET.

Cas d'utilisation

Utiliser un wallet acheteur lors d'un paiement

Ce cas d'utilisation nécessite la création d'un formToken via un appel au Web Service Charge/CreatePayment.

Pour indiquer qu'il souhaite utiliser un wallet acheteur, le site marchand doit transmettre :

la référence acheteur dans le champ customer.reference,
le champ formAction avec la valeur CUSTOMER_WALLET.

Une erreur sera retournée :

si l'offre de la boutique ne dispose pas de l’option "Paiement par alias",
si le champ formAction est valorisé à CUSTOMER_WALLET mais que le champ customer.reference n'est pas transmis.

Remarque sur les données de l'acheteur associées au wallet acheteur

Les informations de facturation (objet billingDetails) transmises lors de l'enregistrement du moyen de paiement sont automatiquement reportées sur les transactions réalisées avec le wallet acheteur.

Cependant, si le marchand transmet de nouvelles données dans la requête Charge/CreatePayment, alors ce sont les données de la requête qui sont utilisées pour la transaction. Dans ce cas, les données de l'acheteur associées au moyen de paiement ne sont pas mises à jour.

Si le marchand souhaite mettre à jour les données de l'acheteur sur l'ensemble des alias asociés à la référence acheteur, il doit appeler le Web Service CustomerWallet/Update.

Exemple de requête POST Charge/CreatePayment

/doc/fr-FR/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44

https://api.systempay.fr/api-payment/V4/Charge/CreatePayment

{
    "amount": 40000,
    "currency": "EUR",
    "orderId": "myOrderId-999999",
    "formAction": "CUSTOMER_WALLET", 
    "customer": {
      "email": "sample@example.com",
      "reference": "cust-001"
    }
}

La réponse contient un formToken qui sera utilisé pour afficher le formulaire.

{
  "webService": "Charge/CreatePayment",
  "version": "V4",
  "applicationVersion": "5.13.0",
  "status": "SUCCESS",
  "answer": {
    "formToken": "10n5J2yTR-Sb6jnXXOohmfsw209eyJhbW91bnQiOjQwMDAwLCJjdXJyZW5jeSI6IkVVUiIsIm1vZGUiOiJURVNUIiwidmVyc2lvbiI6Mywib3JkZXJJZCI6Im15T3JkZXJJZC05OTk5OSIsInNob3BOYW1lIjoiRGVtbyBzaG9wIiwiYnJhbmRQcmlvcml0eSI6WyJCQU5DT05UQUNUIiwiTUFFU1RSTyJdLCJjYXRlZ29yaWVzIjp7ImRlYml0Q3JlZGl0Q2FyZHMiOnsiYXBwSWQiOiJjYXJkcyIsInBhcmFtIjpbIkVERU5SRUQiLCJBTUVYIiwiQ09ORUNTIiwiTUFTVEVSQ0FSRF9ERUJJVCIsIkRJU0NPVkVSIiwiVklTQSIsIlZJU0FfREVCSVQiLCJTT0RFWE8iLCJESU5FUlMiLCJNQUVTVFJPIiwiRS1DQVJURUJMRVVFIiwiQ0hRX0RFSiIsIk1BU1RFUkNBUkQiLCJCQU5DT05UQUNUIiwiQVBFVElaIiwiVklTQV9FTEVDVFJPTiIsIkNCIl19fSwiY2FyZHMiOnsiQ09ORUNTIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJBTUVYIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsibWF4TGVuZ3RoIjo0fX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJFREVOUkVEIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJNQVNURVJDQVJEX0RFQklUIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJESVNDT1ZFUiI6eyJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiVklTQSI6eyJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiRElORVJTIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsicmVxdWlyZWQiOmZhbHNlfX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJTT0RFWE8iOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIlZJU0FfREVCSVQiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIk1BRVNUUk8iOnsiZmllbGRzIjp7InNlY3VyaXR5Q29kZSI6eyJyZXF1aXJlZCI6ZmFsc2V9LCJkb1JlZ2lzdGVyIjp7ImhpZGRlbiI6dHJ1ZX19LCJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiRS1DQVJURUJMRVVFIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJDSFFfREVKIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJNQVNURVJDQVJEIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJCQU5DT05UQUNUIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsicmVxdWlyZWQiOmZhbHNlLCJoaWRkZW4iOnRydWV9LCJkb1JlZ2lzdGVyIjp7ImhpZGRlbiI6dHJ1ZX19LCJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiVklTQV9FTEVDVFJPTiI6eyJmaWVsZHMiOnsic2VjdXJpdHlDb2RlIjp7InJlcXVpcmVkIjpmYWxzZX19LCJjb3B5RnJvbSI6ImNhcmRzLkRFRkFVTFQifSwiQVBFVElaIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJERUZBVUxUIjp7ImZpZWxkcyI6eyJwYW4iOnsibWluTGVuZ3RoIjoxMCwibWF4TGVuZ3RoIjoxOSwidmFsaWRhdG9ycyI6WyJOVU1FUklDIiwiTFVITiJdLCJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwiZXhwaXJ5RGF0ZSI6eyJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwic2VjdXJpdHlDb2RlIjp7Im1pbkxlbmd0aCI6MywibWF4TGVuZ3RoIjo0LCJ2YWxpZGF0b3JzIjpbIk5VTUVSSUMiXSwicmVxdWlyZWQiOnRydWUsInNlbnNpdGl2ZSI6dHJ1ZSwiaGlkZGVuIjpmYWxzZSwiY2xlYXJPbkVycm9yIjp0cnVlfSwiZG9SZWdpc3RlciI6eyJ2YWx1ZSI6ImZhbHNlIiwidmFsaWRhdG9ycyI6WyJCT09MRUFOIl0sInJlcXVpcmVkIjpmYWxzZSwic2Vuc2l0aXZlIjpmYWxzZSwiaGlkZGVuIjpmYWxzZSwiY2xlYXJPbkVycm9yIjpmYWxzZX19fSwiQ0IiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn19LCJwYXNzQWN0aXZhdGVkIjp0cnVlLCJhcGlSZXN0VmVyc2lvbiI6IjQuMCJ96902",
    "_type": "V4/Charge/PaymentForm"
  },
  "ticket": null,
  "serverDate": "2020-09-25T10:09:36+00:00",
  "applicationProvider": "NPS",
  "metadata": null,
  "_type": "V4/WebService/Response"
}

En suivant les principes de base de l'utilisation du client JavaScript, vous utilisez le formToken, généré lors de l'appel au Web Service Charge/CreatePayment, pour spécifier l'identifiant du formulaire à afficher dans l'attribut kr-form-token de votre <div>.

Le formulaire s'affiche :

L'acheteur saisit les données de sa carte, coche la case Enregistrer ma carte et clique sur le bouton "Payer".

Si l'acheteur avait déjà enregistré une carte dans son wallet acheteur, alors les champs de saisie sont pré-remplis avec les données de son moyen de paiement :

S'il ne souhaite pas régler son achat avec cette carte, l'onglet "Nouvelle carte" lui permet de saisir un nouveau moyen de paiement et de l'enregistrer s'il le souhaite :

Si l'acheteur a enregistré plusieurs moyens de paiement dans son wallet acheteur, il devra choisir la carte à utiliser ou saisir une nouvelle carte depuis l'onglet "Nouvelle carte" :

Une fois le paiement terminé, une notification est envoyée au site marchand sur l'URL définie dans le Back Office marchand. Les mêmes informations sont retournées au navigateur par le client JavaScript vers l'URL déclarée dans le paramètre kr-post-url-success lors de l'affichage du formulaire.

Parmi les informations transmises, l'objet kr-answer contient l'objet Payment détaillant la transaction réalisée ainsi que le détail du moyen de paiement utilisé.

Enregistrer une carte dans un wallet acheteur sans paiement

Ce cas d'utilisation nécessite la création d'un formToken via un appel au Web Service Charge/CreateToken.

Pour indiquer qu'il souhaite utiliser un wallet acheteur, le site marchand doit transmettre la référence acheteur dans le champ customer.reference.

Si la référence acheteur n'est pas transmise, la carte sera bien enregistrée et un alias sera créé, mais la carte ne sera pas ajoutée au wallet.

Lors du prochain paiement, si le site marchand transmet la référence acheteur (utilisation du wallet acheteur), cette carte ne sera pas proposée dans la liste des cartes enregistrées.

Exemple de requête POST Charge/CreateToken

/doc/fr-FR/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44

https://api.systempay.fr/api-payment/V4/Charge/CreateToken

{
    "currency": "EUR",
    "orderId": "myOrderId-999999",    
    "customer": {
      "email": "sample@example.com",
      "reference": "cust-001"
    }       
}

La réponse contient un formToken qui sera utilisé pour afficher le formulaire.

{
  "webService": "Charge/CreateToken",
  "version": "V4",
  "applicationVersion": "5.13.0",
  "status": "SUCCESS",
  "answer": {
    "formToken": "10hIV6-LQ9TGeZIRI9C_zENg209eyJhbW91bnQiOjAsImN1cnJlbmN5IjoiRVVSIiwibW9kZSI6IlRFU1QiLCJ2ZXJzaW9uIjozLCJvcmRlcklkIjoibXlPcmRlcklkLTk5OTk5Iiwic2hvcE5hbWUiOiJEZW1vIHNob3AiLCJjYXRlZ29yaWVzIjp7ImRlYml0Q3JlZGl0Q2FyZHMiOnsiYXBwSWQiOiJjYXJkcyIsInBhcmFtIjpbIkFNRVgiLCJFLUNBUlRFQkxFVUUiLCJNQVNURVJDQVJEX0RFQklUIiwiTUFTVEVSQ0FSRCIsIkRJU0NPVkVSIiwiVklTQSIsIlZJU0FfRUxFQ1RST04iLCJWSVNBX0RFQklUIiwiQ0IiLCJESU5FUlMiXX19LCJjYXJkcyI6eyJBTUVYIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsibWF4TGVuZ3RoIjo0fX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJFLUNBUlRFQkxFVUUiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIk1BU1RFUkNBUkRfREVCSVQiOnsiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIkRJU0NPVkVSIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJNQVNURVJDQVJEIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJWSVNBIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJWSVNBX0VMRUNUUk9OIjp7ImZpZWxkcyI6eyJzZWN1cml0eUNvZGUiOnsicmVxdWlyZWQiOmZhbHNlfX0sImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJERUZBVUxUIjp7ImZpZWxkcyI6eyJwYW4iOnsibWluTGVuZ3RoIjoxMCwibWF4TGVuZ3RoIjoxOSwidmFsaWRhdG9ycyI6WyJOVU1FUklDIiwiTFVITiJdLCJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwiZXhwaXJ5RGF0ZSI6eyJyZXF1aXJlZCI6dHJ1ZSwic2Vuc2l0aXZlIjp0cnVlLCJoaWRkZW4iOmZhbHNlLCJjbGVhck9uRXJyb3IiOmZhbHNlfSwic2VjdXJpdHlDb2RlIjp7Im1pbkxlbmd0aCI6MywibWF4TGVuZ3RoIjo0LCJ2YWxpZGF0b3JzIjpbIk5VTUVSSUMiXSwicmVxdWlyZWQiOnRydWUsInNlbnNpdGl2ZSI6dHJ1ZSwiaGlkZGVuIjpmYWxzZSwiY2xlYXJPbkVycm9yIjp0cnVlfX19LCJESU5FUlMiOnsiZmllbGRzIjp7InNlY3VyaXR5Q29kZSI6eyJyZXF1aXJlZCI6ZmFsc2V9fSwiY29weUZyb20iOiJjYXJkcy5ERUZBVUxUIn0sIkNCIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9LCJWSVNBX0RFQklUIjp7ImNvcHlGcm9tIjoiY2FyZHMuREVGQVVMVCJ9fSwicGFzc0FjdGl2YXRlZCI6dHJ1ZSwiYXBpUmVzdFZlcnNpb24iOiI0LjAifQ4a02",
    "_type": "V4/Charge/PaymentForm"
  },
  "ticket": null,
  "serverDate": "2020-09-25T10:15:37+00:00",
  "applicationProvider": "NPS",
  "metadata": null,
  "_type": "V4/WebService/Response"
}

Une fois l'enregistrement du moyen de paiement terminé, une notification est envoyée au site marchand sur l'URL définie dans le Back Office marchand.

Les mêmes informations sont retournées au navigateur par le client JavaScript vers l'URL déclarée dans le paramètre kr-post-url-success lors de l'affichage du formulaire.

Le champ kr-answer transmis contient un objet Payment décrivant la transaction de vérification ainsi que les informations sur l'alias créé.

Seule la présence du champ customer.reference, valorisé avec la référence acheteur transmise par le marchand, permet d'identifier que la carte a été ajoutée au wallet acheteur.

Supprimer une carte enregistrée

Durant le paiement, l'acheteur peut demander la suppression d'une carte enregistrée dans son wallet acheteur en cliquant sur la corbeille.

La suppression est dite "logique", c'est à dire, que l'alias est résilié, il n'est plus possible de l'utiliser pour les paiements. Mais il est toujours visible dans le Back Office Marchand.

En respect des règles de sécurité et de protection des données bancaires exigées par PCI DSS, les données du moyen de paiement sont purgées au delà de 15 mois de non utilisation de l'alias associé.

Un nouveau paramétrage du Back Office Marchand vous permet de configurer si la suppression est automatique ou si elle doit être réalisée par le marchand.

Suppression automatique

En cliquant sur la corbeille un message de confirmation apparait :

Si l'acheteur clique sur Supprimer, la carte disparait de la liste des cartes disponibles.

Cette action déclenche les notifications basées sur la mise à jour d'un alias :

URL de notification à la fin du paiement
E-mail de confirmation d'une création d'alias à destination de l'acheteur
E-mail de confirmation d'une création d'alias à destination du marchand
SMS de confirmation d'une création d'alias à destination du marchand
SMS de confirmation d'une création d'alias à destination de l'acheteur

Si la carte supprimée était la seule carte enregistrée, alors l'onglet "Nouvelle carte" s'affiche automatiquement.

Si la carte est en cours d'utilisation pour le réglement d'un abonnement automatique, un message d'avertissement apparait, invitant l'acheteur à prendre contact avec le marchand :

Pour activer la suppression automatique :

Depuis le Back Office Marchand, ouvrez le menu Paramétrage > Société puis cliquez sur l'onglet Paramètres abonnement et alias.
Dans la section Paramètre du wallet acheteur, cochez la case Suppression logique de l'alias autorisée par l'acheteur.
Cliquez sur le bouton Sauvegarder pour enregistrer vos modifications.

Suppression manuelle

En cliquant sur la corbeille un message d'information apparait, invitant l'acheteur à prendre contact avec le marchand :

Pour activer la suppression manuelle :

Depuis le Back Office Marchand, ouvrez le menu Paramétrage > Société puis cliquez sur l'onglet Paramètres abonnement et alias.
Dans la section Paramètre du wallet acheteur, décochez la case Suppression logique de l'alias autorisée par l'acheteur.
Cliquez sur le bouton Sauvegarder pour enregistrer vos modifications.

Catégories

Tags