Documentation Paylet

Paylet est une passerelle de micro-paiement Machine-to-Machine (M2M). Cette documentation vous donne toutes les clés pour payer et encaisser des micro-services, que vous soyez développeur ou simplement curieux de l'économie des agents autonomes.

Qu'est-ce que Paylet ?

Paylet permet à des agents IA autonomes (ou à tout système) de payer à la volée pour accéder à un micro-service exposé derrière une API. Un « client » (l'agent) paie un « vendeur » (le marchand) sans aucune intervention humaine, pour des montants pouvant descendre au millième de centime.

Concrètement, Paylet fournit : un compte prépayé rechargé par carte via Stripe, un ledger (grand livre) qui suit chaque mouvement au micro-crédit près, des SDK Python et TypeScript, et une API (sur api.paylet.fr) qui orchestre le protocole d'échange.

ÉlémentDescription
paylet.frSite vitrine et documentation publique (vous êtes ici).
api.paylet.frAPI de la passerelle (base URL des appels /v1).
dashboard.paylet.frTableau de bord marchand : solde, clés API, webhooks.

Le protocole x402, expliqué simplement

x402 désigne le code de statut HTTP 402 Payment Required. À l'origine, ce code devait signaler « cette ressource est payante ». Il n'a jamais été standardisé dans le web grand public, mais il est idéal pour le Machine-to-Machine : au lieu d'afficher une page de paiement, le serveur répond « paye-moi, et voici ce que tu dois », et le client paie automatiquement.

L'échange se déroule en cinq temps :

  1. Le client appelle un endpoint payant sans preuve de paiement.
  2. Le vendeur répond 402 avec un challenge signé (le montant demandé).
  3. Le client règle ce challenge auprès de Paylet, qui débite son solde.
  4. Le client rejoue sa requête avec le reçu signé en guise de preuve.
  5. Le vendeur vérifie la preuve et délivre la ressource (200 OK).
schéma du fluxSéquence nominale du paiement x402
  Agent acheteur              Vendeur (marchand)               Paylet (gateway)
       |                            |                              |
       |-- 1. GET /data/42 -------->|                              |
       |   (sans preuve de paiement)|                              |
       |                            |                              |
       |<-- 2. HTTP 402 ------------|                              |
       |    X-Payment-Challenge     |                              |
       |                            |                              |
       |-- 3. POST /v1/payments --> |                              |
       |    (règle le challenge)    |                              |
       |                            |                              |
       |<-- reçu signé -------------|------------------------------|
       |                            |                              |
       |-- 4. GET /data/42 -------->|                              |
       |    X-Payment: <reçu>       |                              |
       |                            |-- vérifie la signature ----->|
       |                            |                              |
       |<-- 5. 200 OK + données ----|                              |

La clé du système : le challenge et le reçu sont des objets JSON signés en HMAC-SHA256. Le vendeur peut vérifier une preuve de paiement localement, sans rappeler Paylet, et personne ne peut falsifier un montant ou une ressource.

Glossaire minimal

TermeDéfinition
challengeDemande de paiement signée renvoyée par le vendeur dans la réponse 402. Elle contient le montant, la ressource, un nonce et une expiration (durée de vie 5 minutes).
nonceIdentifiant unique (UUID) généré pour chaque challenge. Il est consommé une seule fois : rejouer un challenge déjà réglé est refusé, ce qui prévient la double dépense.
IdempotencePropriété qui garantit que rejouer la même opération produit le même résultat sans effet de bord. Paylet l'obtient via le header <InlineCode key="i">Idempotency-Key</InlineCode> : un même paiement ne débite qu'une seule fois.
CommissionPrélevée par Paylet à hauteur de 1,5 % du prix net, avec un minimum de 0,002 € (2 000 micro-crédits).
Micro-créditUnité de compte indivisible de Paylet : 1 micro-crédit = 0,000001 €, donc 1 € = 1 000 000 micro-crédits. Tous les montants sont des entiers.
reçu (receipt)Preuve de paiement signée renvoyée par Paylet après règlement. Le client la rejoue via le header <InlineCode key="r">X-Payment</InlineCode>.
fee_modeRéglage du vendeur qui détermine qui supporte la commission : <InlineCode key="d">deduct_from_amount</InlineCode> (défaut) ou <InlineCode key="a">add_to_price</InlineCode>. Voir le guide « Recevoir ».

Par où commencer ?

  • Démarrage rapide — créer un compte, générer une clé API et recharger votre solde.
  • Payer (côté acheteur) — dérouler le flux 402 étape par étape, en Python, TypeScript et curl.
  • Recevoir (côté vendeur) — émettre un challenge, vérifier un reçu et choisir votre mode de commission.
  • Agents IA — des exemples complets avec function calling OpenAI et LangChain.

Référence de l'API

Pour la liste exhaustive des endpoints, codes d'erreur et formats de réponse, consultez la documentation de référence de l'API.