Cas d’usage expliqués

La caisse KAI-Pay accepte les paiements en bitcoin via Lightning – au comptoir, sur un stand de marché ou lors d’événements, sur un appareil de caisse dédié ou directement sur votre téléphone.

Vos avantages

• L’argent arrive en quelques secondes dans votre propre portefeuille en auto-garde – personne ne le conserve entre-temps.
• Pas de terminal de carte, pas de contrat, pas d’inscription : un navigateur sur une tablette, un téléphone ou un ordinateur portable suffit.
• Sûr pour votre équipe : les appareils de caisse peuvent seulement encaisser, jamais envoyer d’argent – idéal pour les appareils du personnel.
• Vos clients paient avec n’importe quel portefeuille Lightning, partout dans le monde.
• Encaissez en sat ou en EUR, USD, GBP, CHF, CAD, AUD et JPY – le cours est fixé pour chaque facture.
• Articles d’un simple toucher, reçu en PDF, clôture journalière et mensuelle avec export CSV et remboursement directement dans le portefeuille.

Comment cela fonctionne

1. Dans le portefeuille, sous « Caisse et clôture », configurez la caisse – ouvrez-la sur le même appareil ou transférez-la sur un appareil de caisse par code QR.
2. Saisissez le montant ou touchez les articles, puis choisissez « Encaisser ». La caisse affiche une facture Lightning sous forme de code QR.
3. Le client scanne et paie. La caisse affiche « Payé » et un reçu de paiement numéroté.

Notre approche

La caisse est volontairement une page distincte, sans clés : elle peut créer des factures, mais pas déplacer d’argent. Elle n’utilise que des cours récents (récupérés il y a 5 minutes au plus) de mempool.space. À chaque paiement, elle envoie une note chiffrée avec la caisse, le numéro de reçu, le montant et les lignes, que seul votre portefeuille peut lire – c’est à partir de cette note que le portefeuille calcule votre clôture.

Bon à savoir : La caisse est un terminal de paiement, pas une caisse enregistreuse ; le reçu est un justificatif de paiement, pas un ticket de caisse. KAI-Pay est une bêta publique.

Explication animée · Guide de la caisse · Ouvrir la caisse

L402 est un standard ouvert qui permet aux sites web, aux interfaces de programmation (API) et à d’autres services en ligne de demander de petits montants directement via Lightning – au lieu d’un compte utilisateur, d’un abonnement ou d’une carte de crédit. Le nom fait référence au code d’état HTTP 402 « Payment Required » (paiement requis) ; L402 a été développé par Lightning Labs (ancien nom : LSAT).

Vos avantages

• Pas de compte, pas d’abonnement, pas de données de carte : payez et utilisez immédiatement.
• Ne payez que ce que vous utilisez réellement – dès quelques sat par requête, même des montants inférieurs à un centime.
• Payé en quelques secondes, partout dans le monde et à toute heure – sans banque intermédiaire.
• Plus de confidentialité : par le paiement, le service n’apprend ni votre nom ni vos données de carte.
• Les programmes et les agents IA peuvent aussi payer ainsi – un programme n’a pas de compte bancaire, mais il peut tout de même régler une facture Lightning.

À quoi cela peut vous servir

• Payer à la requête plutôt que par abonnement : par exemple des données, des cours, des données cartographiques ou météo, des réponses d’IA ou de la puissance de calcul.
• Débloquer des contenus et des outils sans créer de compte utilisateur.
• Processus automatisés : des programmes et des agents IA paient des services à chaque appel, sans qu’il faille créer chez chaque fournisseur un compte avec identifiants.

Comment cela fonctionne

1. Vous – ou votre programme – adressez une requête au service. Au lieu de la réponse arrive une demande L402 : une clé d’accès (« Macaroon ») et la facture Lightning correspondante.
2. Vous collez la demande dans le portefeuille sous « Envoyer » et payez. En guise de quittance, le portefeuille reçoit une valeur secrète (« Preimage ») que seule obtient la personne qui a payé.
3. Ensemble, la clé d’accès et la quittance forment la preuve d’accès. Votre programme l’envoie dans l’en-tête Authorization ; le service la vérifie et libère la réponse.

Notre approche

Dans KAI-Pay, L402 est une fonction propre au portefeuille : le portefeuille n’appelle pas lui-même le service et ne transmet rien à KAI-Pay. Il ne paie que si la facture appartient de manière vérifiable à la clé d’accès, au maximum 1 000 sat par paiement (bêta), et ne paie pas une seconde fois un accès déjà payé tant que le paiement figure dans l’historique de votre appareil. Il affiche les services inconnus avec un avertissement. Il enregistre la preuve d’accès uniquement sur votre appareil. Pour les agents IA, la règle est : le contrôle plutôt que le pilote automatique – voir « Gérer le budget IA ».

Bon à savoir : Le portefeuille paie uniquement la facture ; c’est le service qui décide s’il donne accès et pour combien de temps. Le portefeuille protège contre une facture substituée, pas contre une demande entièrement falsifiée – vérifiez donc de qui elle provient. Aujourd’hui, cela s’adresse surtout aux développeurs et aux personnes intéressées par la technique.

Explication animée · Ouvrir le portefeuille

Acceptez des paiements pour votre boutique, votre projet ou votre site web – avec un lien ou un bouton, sans contrat avec un prestataire de paiement, sans serveur propre et sans nœud Lightning propre. Si vous le souhaitez, chaque paiement est notifié à votre boutique, avec une signature.

Vos avantages

• Pas de contrat avec un prestataire de paiement ni de frais de mise en place : un lien suffit.
• L’argent va directement dans votre portefeuille en auto-garde.
• Votre boutique est informée immédiatement de chaque paiement reçu – avec une signature fondée sur un secret que seuls votre boutique et le prestataire Spark connaissent. Si votre boutique vérifie la notification, elle peut comptabiliser les commandes automatiquement.
• Les paiements via Lightning sont définitifs – pas de rétrofacturations (chargebacks) comme avec les cartes.
• Des clients du monde entier paient en quelques secondes, avec n’importe quel portefeuille Lightning.

Comment cela fonctionne

1. Dans le portefeuille : Menu → Connecter un service. Vous y trouvez votre lien de paiement kai-pay.net/@votrenom (il vous faut pour cela une adresse Lightning, à configurer sous « Recevoir »).
2. Facultatif : indiquez un montant et un numéro de commande – le lien génère alors aussitôt une facture correspondante. Copiez le lien ou le bouton prêt à l’emploi (HTML, sans script) sur votre site web, dans vos factures ou vos e-mails.
3. Pour des confirmations automatiques : sous « Notification à votre boutique », saisissez l’adresse de votre boutique (https://…), confirmez et copiez dans votre boutique le secret affiché. Dès lors, le prestataire Spark Lightspark y envoie une notification signée à chaque paiement Lightning reçu.
4. Votre boutique vérifie la signature et associe le paiement à la commande – comment, c’est expliqué plus bas sous « Pour les développeurs ».

Notre approche

Aucun intermédiaire : la page de paiement ne conserve rien, et les notifications vont directement du prestataire Spark à votre boutique – notre serveur ne les voit pas. Le portefeuille affiche le secret de signature une seule fois et ne l’enregistre pas.

Pour les développeurs

Une facture par commande : interrogez le serveur de paiement de votre adresse Lightning (LNURL-pay, LUD-06) : d’abord /.well-known/lnurlp/votrenom sur son domaine, puis son callback avec amount (en millisatoshis) et, en option, comment. La réponse contient la facture (pr) et une adresse de vérification (verify, LUD-21). Conservez avec la commande le payment_hash de la facture.

La notification arrive sous forme de requête POST avec du JSON. Vérifiez d’abord l’en-tête X-Spark-Signature : HMAC-SHA256 du contenu non modifié avec votre secret, en hexadécimal. Ensuite : type = SPARK_LIGHTNING_RECEIVE_FINISHED, status = TRANSFER_COMPLETED, et le SHA-256 de payment_preimage est le payment_hash de la facture payée (champs selon la documentation de Breez sur les webhooks). Exemple pour Node.js :

import { createHash, createHmac, timingSafeEqual } from 'node:crypto'

// raw: the unmodified request body (Buffer); secret: the secret shown once in the wallet
// orders: your order store; amountMatches(order, amount): compares in the same unit (amount = { value, unit })
// Returns 'reject' (answer 401), null (nothing to do - answer 200) or the booked order (answer 200).
export function kaiPayPayment(raw, signatureHeader, secret, orders) {
  const expected = createHmac('sha256', secret).update(raw).digest()
  const given = Buffer.from(String(signatureHeader ?? '').replace(/^sha256=/, ''), 'hex')
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return 'reject'  // wrong seal: answer 401
  // From here on always answer 200 - the notification comes for every Lightning payment of the wallet.
  const e = JSON.parse(raw)
  if (e.type !== 'SPARK_LIGHTNING_RECEIVE_FINISHED' || e.status !== 'TRANSFER_COMPLETED' || !e.payment_preimage) return null
  // SHA-256 of the preimage = payment_hash of the paid invoice
  const paymentHash = createHash('sha256').update(Buffer.from(e.payment_preimage, 'hex')).digest('hex')
  const order = orders.byPaymentHash(paymentHash)
  if (!order) return null                                    // not one of your invoices (e.g. a private payment)
  if (order.paid) return order                               // repeated notification: already booked
  if (!amountMatches(order, e.invoice_amount)) return null   // wrong amount: do not release, check by hand
  return orders.markPaid(order)                              // markPaid must be atomic: only the first call books
}

Répondez avec HTTP 401 uniquement si le sceau est faux, sinon toujours avec 200 – y compris à une notification répétée ou à un paiement qui ne correspond à aucune commande ; le paiement n’est comptabilisé qu’une seule fois. Le montant figure dans invoice_amount avec son unité (unit) ; comparez-le à la commande dans la même unité. En cas de doute, l’adresse de vérification de la facture (settled: true) confirme la réception.

Bon à savoir : La notification arrive pour chaque paiement Lightning reçu par le portefeuille, y compris les paiements privés – idéalement, utilisez un portefeuille séparé pour la boutique. Les liens de paiement kai-pay.net/@nom existent pour les adresses Lightning chez breez.tips. KAI-Pay est une bêta publique.

Explication animée · Ouvrir dans le portefeuille

Un assistant IA – par exemple un agent personnel, un script ou KAI – peut vous proposer des paiements. Vous fixez à qui et combien par jour et par mois ; chaque paiement, vous le confirmez vous-même.

Vos avantages

• Faites préparer des paiements récurrents sans que rien ne se passe sans vous : une proposition ne paie jamais d’elle-même.
• Limites fixes : uniquement vers des destinataires que vous avez autorisés et dans la limite d’un budget journalier et mensuel (frais compris).
• Infalsifiable : chaque proposition est signée ; le portefeuille vérifie l’expéditeur, le destinataire, le budget et la validité, et n’accepte chaque proposition qu’une seule fois.
• Vue d’ensemble complète : pour chaque assistant, le portefeuille indique la part déjà utilisée du budget journalier et mensuel.

Comment l’essayer

1. Ouvrez le portefeuille : Menu → Budget IA.
2. Touchez « Créer un assistant de test ». Comme destinataire autorisé, saisissez une adresse que vous voulez vraiment payer – par exemple un second portefeuille à vous – et définissez un petit budget journalier et mensuel. Enregistrez.
3. Sur l’assistant, touchez « Créer une proposition », saisissez un montant, puis « Créer et vérifier la proposition ». Vous voyez maintenant ce qu’un assistant IA vous enverrait : expéditeur, destinataire, montant et budget restant.
4. « Continuer vers le paiement » : le portefeuille vérifie à nouveau le destinataire et le budget et affiche les frais. Seul « Confirmer et envoyer » déclenche le paiement – le budget diminue ensuite du montant et des frais. Une seconde tentative avec la même proposition est refusée.

Connecter un assistant

Si un assistant vous a remis un code, un lien ou un code QR (avec KAI dans Telegram : /vorschlag quelle), ouvrez-le sous Menu → Budget IA → « Connecter un assistant », comparez l’empreinte et définissez les destinataires et le budget. Ses propositions arrivent sous forme de lien et ouvrent directement la page de vérification.

Notre approche

Le contrôle plutôt que le pilote automatique : un assistant n’a jamais accès à vos clés et peut seulement proposer. Le portefeuille n’accepte volontairement pas de factures Lightning dans les propositions, car il ne peut pas en vérifier le destinataire. Vous profitez ainsi des avantages de l’IA sans renoncer à la maîtrise de votre argent.

Pour les développeurs : connecter votre propre agent

Créez un assistant dans le portefeuille et enregistrez son « Fichier d’accès pour agents ». Votre agent – un script, une automatisation ou une IA capable d’exécuter du code – s’en sert pour créer des propositions signées. Ce script (Node.js 20 ou plus récent, sans paquets) affiche un lien que votre agent vous envoie et que vous ouvrez dans le portefeuille :

// kai-vorschlag.mjs - signed KAI-Pay proposal from the access file (Node.js 20+, no packages)
// node kai-vorschlag.mjs access.json name@provider.com 2100 "Server bill October"
import { readFileSync } from 'node:fs'
const [file, to, sat, purpose] = process.argv.slice(2)
const acc = JSON.parse(readFileSync(file, 'utf8'))
const b64u = (b) => Buffer.from(b).toString('base64url')
const now = Math.floor(Date.now() / 1000)
const p = { v: 1, id: b64u(crypto.getRandomValues(new Uint8Array(16))), src: acc.id,
  iat: now, exp: now + 24 * 3600, to, sat: Number(sat), purpose }
const signed = 'kaiprop1.' + b64u(JSON.stringify(p))
const key = await crypto.subtle.importKey('pkcs8', Buffer.from(acc.pkcs8, 'base64url'),
  { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign'])
const sig = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, key, new TextEncoder().encode(signed))
console.log(acc.app + '#kaiprop=' + encodeURIComponent(signed + '.' + b64u(new Uint8Array(sig))))

Une proposition est valable 7 jours au maximum et indique une destination (adresse Lightning ou Bitcoin, pas de facture), un montant en sat (1 000 000 au maximum) et un motif (140 caractères au maximum). Quiconque possède le fichier d’accès peut vous envoyer des propositions, mais ne peut rien payer – ne le confiez qu’à votre propre agent.

Bon à savoir : La fonction est en bêta. Le motif d’une proposition est indiqué par l’assistant ; le portefeuille ne le vérifie pas.

Explication animée · Ouvrir dans le portefeuille