Création de commandes

3.1.3. Création de commandes#

Cette page contient toute la documentation du didacticiel vidéo expliquant la création d’une commande simple via l’API et la vérification de son statut.

3.1.3.1. Vidéo#

3.1.3.2. Exigences#

Nécessaire pour cette série de tutoriels :

  • Un backend marchand Taler
    Si vous avez besoin d’aide pour utiliser le backend marchand pour la première fois, vous pouvez regarder le Taler merchant introduction tutorial.
  • Une instance de portefeuille Taler
    Les instructions d’installation sont disponibles sur le site https://wallet.taler.net.
  • Un logiciel de gestion d’API REST ou des compétences en programmation pertinentes
    Dans cette série de vidéos, nous allons utiliser le logiciel gratuit Insomnia, disponible en téléchargement sur https://insomnia.rest.

3.1.3.3. Démonstration de l’avis du backend#

Vous pouvez utiliser votre propre service de backend marchand ou le service de démonstration en ligne à l’adresse https://backend.demo.taler.net/instances/sandbox/ pour ce tutoriel.

3.1.3.4. Traitement des paiements des commerçants#

  1. Création d’une commande de paiement

Les paiements dans Taler s’articulent autour d’une commande, qui est une description lisible par machine de la transaction commerciale pour laquelle le paiement doit être effectué. Avant d’accepter un paiement dans Taler en tant que commerçant, vous devez créer une telle commande.

Cela se fait en envoyant un objet JSON au point d’arrivée /private/orders de l’API du backend. Au moins les champs suivants doivent être fournis dans le champ order :

  • amount : Le montant à payer, sous forme de chaîne au format CURRENCY:DECIMAL_VALUE, par exemple EUR:10 pour 10 Euros ou KUDOS:1.5 pour 1.5 KUDOS.

  • summary : Un résumé lisible par l’homme de l’objet du paiement. Le résumé doit être suffisamment court pour être inséré dans les titres, bien qu’aucune limite stricte ne soit imposée.

  • fulfillment_url : URL qui sera affichée une fois le paiement effectué. Pour les biens numériques, il doit s’agir d’une page qui affiche le produit qui a été acheté. Lors d’un paiement réussi, le portefeuille ajoute automatiquement le order_id en tant que paramètre de requête, ainsi que le session_sig pour les paiements liés à une session (voir ci-dessous).

Les commandes peuvent avoir beaucoup plus de champs, voir Le format de commande Taler. Lorsque vous postez une commande, vous pouvez également spécifier des détails supplémentaires tels qu’une dérogation pour la durée de remboursement et des instructions pour la gestion de l’inventaire. Ces détails sont rarement nécessaires et ne sont pas abordés dans ce tutoriel ; veuillez consulter le manuel de référence pour plus de détails.

Un extrait Python minimal pour la création d’une commande ressemblerait à ceci :

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Le backend complétera certains détails manquants dans la commande, tels que l’adresse de l’instance marchande. Les détails complets sont appelés les conditions du contrat.

Note

La requête ci-dessus désactive l’utilisation des jetons de réclamation en mettant l’option create_token à false. Si vous avez besoin de jetons de réclamation, vous devez ajuster le code pour construire l’URI taler://pay/ donné ci-dessous pour inclure le jeton de réclamation.

Après avoir réussi à POST vers /private/orders, un JSON avec juste un champ order_id avec une chaîne de caractères représentant l’ID de la commande sera retourné. Si vous obtenez également un jeton de réclamation, vérifiez que vous avez utilisé la requête comme décrit ci-dessus.

Avec l”instance du marchand, l’identifiant de la commande identifie de manière unique la commande au sein du backend du marchand. En utilisant l’identifiant de la commande, vous pouvez trivialement construire l’URI taler://pay/ qui doit être fourni au portefeuille. Prenons exemple.com comme nom de domaine où les terminaux publics de l’instance sont accessibles. L’URI de Taler pay est alors simplement taler://pay/example.com/$ORDER_ID/ où $ORDER_ID doit être remplacé par l’ID de la commande qui a été retournée.

Vous pouvez placer l’URI taler:// comme cible d’un lien pour ouvrir le portefeuille Taler via le schéma taler://, ou l’insérer dans un code QR. Cependant, pour une boutique en ligne, le plus simple est de rediriger le navigateur vers https://example.com/orders/$ORDER_ID. Cette page déclenchera alors le portefeuille Taler. Ici, le backend génère la bonne logique pour déclencher le portefeuille, en prenant en charge les différents types de portefeuilles Taler existants. Au lieu de construire l’URL ci-dessus à la main, il est également possible de l’obtenir en vérifiant l’état du paiement comme décrit dans la section suivante.

Lorsque vous construisez manuellement cette URL, assurez-vous de fournir le jeton de réclamation (à moins qu’il n’ait été désactivé) et si le backend fonctionne sans TLS, utilisez taler+http:// (notez que ce dernier n’est supporté que par les portefeuilles fonctionnant en mode débogage).

Note

Une façon triviale d’obtenir le bon payment_redirect_url est de vérifier le statut du paiement (voir ci-dessous). Donc, si vous n’êtes pas sûr de la façon de la construire, vous pouvez simplement demander au backend de le faire pour vous. Cependant, en production, vous devriez probablement le construire manuellement et éviter la requête supplémentaire au backend.

  1. Vérification de l’état des paiements et demande de paiement

Compte tenu de l’identifiant de la commande, le statut d’un paiement peut être vérifié avec le point de terminaison /private/orders/$ORDER_ID`. Si le paiement n'a pas encore été effectué par le client, ``/private/orders/$ORDER_ID donnera au frontend une URL (sous le nom payment_redirect_url) qui déclenchera l’exécution du paiement par le portefeuille du client. C’est en fait l’URL https://example.com/orders/$ORDER_ID dont nous avons parlé plus haut.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Si le champ order_status de la réponse est paid, vous n’obtiendrez pas de payment_redirect_url mais des informations sur le statut du paiement, notamment :

  • contract_terms : Les conditions contractuelles complètes de la commande.

  • refunded : vrai si un remboursement (éventuellement partiel) a été accordé pour cet achat.

  • refunded_amount : Montant remboursé

Une fois que le frontend a confirmé que le paiement a été effectué avec succès, il doit généralement déclencher la logique de gestion du commerçant pour que ce dernier remplisse ses obligations contractuelles.

Note

Vous n’avez pas besoin de continuer à faire des requêtes pour remarquer les changements dans le statut de la transaction de la commande. Les points de terminaison supportent l’interrogation longue, il suffit de spécifier un paramètre de requête timeout_ms avec le temps d’attente maximum pour que le statut de la commande passe à payé.

3.1.3.5. Plus de tutoriels#

Pour consulter d’autres tutoriels, vous pouvez parcourir ce site ou vous rendre sur https://docs.taler.net pour obtenir la documentation la plus récente sur les services Taler.