# module Paiements · v0

> Le module Paiements permet à une personne de payer une marque sur Each: paiement unique, abonnement à une marque ou frais d'usage. Chaque transaction produit une preuve signée, vérifiable par tout le monde. Each: mode test seulement, aucun paiement réel.

Statut: draft · mis à jour 2026-10-30 · JSON: https://test.each.app/surface/payments/v0.json

## Ce qu'il fait
- **one_time**: Paiement unique: un montant, une fois (ex.: une commande, un billet).
- **subscription**: Abonnement de marque: un montant récurrent (mensuel ou annuel) qu'une personne ou un commerce paie à une marque.
- **usage**: Frais d'usage: un montant calculé selon l'usage d'un outil (ex.: par commande passée par le réseau).

## Le noyau (non modifiable)
Le noyau Each n'est pas modifiable par un module. Un module peut l'étendre, jamais le contourner. Le noyau garde: les clés d'accès (qui confirme), le consentement (rien n'est payé sans confirmation par clé d'accès), les plafonds en dollars et la signature des preuves.

| Plafond | Valeur |
|---|---|
| Devise | CAD |
| Par transaction | 500 $ |
| Par personne par jour | 1 000 $ |
| Par marque par jour | 5 000 $ |
| Minimum | 0,50 $ |
| Mode test seulement | oui |

Plafonds, appliqués par le noyau avant tout appel au fournisseur. Un module peut demander des plafonds plus bas, jamais plus hauts.

## Scopes
- `payments:read`: Lire tes paiements et leurs preuves.
- `payments:checkout`: Préparer un paiement; il n'est jamais fait sans ta clé d'accès.
- `payments:subscribe`: Préparer un abonnement de marque; chaque abonnement est confirmé par ta clé d'accès.
- `payments:usage`: Une marque déclare des frais d'usage, dans les plafonds du noyau.
- `payments:refund`: Une marque rembourse un paiement (à définir, voir questions ouvertes).

## Parcours
1. La personne choisit un paiement (type, marque, montant).
2. Le noyau vérifie la session, la devise et les plafonds.
3. La personne confirme avec sa clé d'accès (consentement).
4. Le module crée le paiement chez le fournisseur (ou le simule en Each).
5. Le fournisseur confirme par webhook signé; Each vérifie la signature et ignore les doublons.
6. Each émet une preuve signée de la transaction.

## Webhooks
- POST /v1/modules/payments/webhook
- Signature: En-tête de signature: t={horodatage},v1={HMAC-SHA256 hexadécimal de "{t}.{corps brut}"} avec le secret de webhook. Refusé si la signature ne correspond pas ou si t a plus de 5 minutes.
- Idempotence: Chaque événement a un id unique. Un id déjà reçu répond 200 sans rien refaire. Les appels sortants portent une clé d'idempotence (id du paiement Each).
- Sans secret de webhook, le point d'entrée répond 503 module_not_configured.

## Preuve signée pour chaque transaction
Chaque transaction produit une preuve signée (ES256, même clé publique que les preuves de geste: /.well-known/each-keys), en ajout seulement. Vérifiable sur /verifier/{id}.

Type: `each.payment` · champs: `v`, `type`, `id`, `issuer`, `environment`, `issued_at`, `test`, `person`, `brand`, `payment.kind`, `payment.amount_cents`, `payment.currency`, `payment.interval`, `payment.provider_mode`, `statement`, `confirmation (passkey)`, `core.version`, `module.version`

## API
- `GET /v1/modules/payments/status`
- `POST /v1/modules/payments/simulate/options`
- `POST /v1/modules/payments/simulate`
- `POST /v1/modules/payments/checkout`
- `POST /v1/modules/payments/webhook`
- `GET /v1/proofs/{id}`

## Configuration
La clé du fournisseur est un secret serveur ajouté par l'équipe Each. Elle n'est jamais saisie dans un navigateur. Sans clé: état "module non configuré". Clé de production refusée en Each.

## Versions
Version sémantique du contrat: v0 = brouillon. Toute modification incompatible crée v1 à une nouvelle adresse; v0 reste lisible. Pour proposer un changement: copie src/modules/payments/, modifie contract.json, ouvre une revue.

Taxes: à venir

## Questions ouvertes
- Qui encaisse l'argent: Each, la marque, ou des comptes connectés (chaque marque a son compte, Each prend une part)?
- Quelle part pour Each, et sur quels types (unique, abonnement, usage)?
- Remboursements: qui décide, dans quel délai, et la preuve d'origine reste-t-elle valide (une preuve de remboursement s'ajoute)?
- Devises: CAD seulement au départ, puis lesquelles pour l'international?