diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..eb5f6df
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,10 @@
+version: 2
+updates:
+ - package-ecosystem: maven
+ directory: /
+ schedule:
+ interval: weekly
+ - package-ecosystem: github-actions
+ directory: /
+ schedule:
+ interval: weekly
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..344882d
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,63 @@
+name: CI
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+permissions:
+ contents: read
+
+# Actions épinglées par empreinte de commit (une étiquette se déplace) ; Dependabot les met à jour.
+
+jobs:
+ test:
+ # Dépôt PUBLIC : machines GitHub, gratuites et isolées. Jamais les runners ARC du cluster ici
+ # (une PR de fork y exécuterait son code ; décision de Jonas, 15/11/2026).
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ strategy:
+ fail-fast: false
+ matrix:
+ java: ["17", "21"]
+ steps:
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+ - uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4
+ with:
+ distribution: temurin
+ java-version: ${{ matrix.java }}
+ cache: maven
+ - name: Compilation (avertissements = erreurs) et tests, contrat partagé compris
+ run: mvn -B install
+ - name: Les exemples Spring Boot (Java et Kotlin) compilent contre ce SDK
+ run: |
+ (cd examples/spring-boot && mvn -B -q compile)
+ (cd examples/kotlin-spring && mvn -B -q compile)
+
+ securite:
+ # Exigences de sécurité (Jonas, 15/11/2026) : analyse statique au plus strict, dépendances
+ # vulnérables, secrets.
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ steps:
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+ with:
+ fetch-depth: 0
+ - uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4
+ with:
+ distribution: temurin
+ java-version: "17"
+ cache: maven
+ - name: SpotBugs (effort max, seuil bas) avec FindSecBugs
+ run: mvn -B -DskipTests verify spotbugs:check
+ - name: Dépendances vulnérables (OSV-Scanner)
+ run: |
+ curl -fsSL -o osv-scanner https://github.com/google/osv-scanner/releases/download/v2.7.1/osv-scanner_linux_amd64
+ echo "fb7dab19a8bd9bbe5c3189f09d4b7ee1820c9553a23bac202648a56efd2f6ee8 osv-scanner" | sha256sum -c -
+ chmod +x osv-scanner
+ ./osv-scanner scan source -L pom.xml
+ - name: Secrets dans l'historique
+ uses: trufflesecurity/trufflehog@ddc015e5ed99942b2253d8ea16a0586a01ef2ab1 # v3.88.0
+ with:
+ version: 3.88.0
+ extra_args: --only-verified
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5b80c29
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,227 @@
+# technas-pay-java : règles pour un agent de code
+
+Consignes pour un assistant de code. Appliquez-les dans l'application de l'utilisateur, pas dans ce dépôt. Le README détaille chaque fonction ; des exemples compilés sont dans [`examples/`](examples) (Spring Boot en Java et en Kotlin).
+
+Même API, mêmes règles que les SDK Node (`@technas/pay`), Python, PHP et Dart : mêmes noms de méthodes, en Java (`pay.askForPayment(PaymentRequest.builder()…build())`, accesseurs `payment.checkoutUrl()`). Kotlin s'en sert tel quel.
+
+## Avant de commencer
+
+1. Java 17 ou plus récent. Côté SERVEUR uniquement : jamais dans une app Android ni dans du code envoyé au navigateur.
+2. `TECHNAS_PAY_SECRET` doit exister dans l'environnement du serveur (variable d'environnement, coffre, jamais un fichier commité) et commencer par `tps_test_`. S'il manque, demandez-le à l'utilisateur. **N'en inventez pas, ne l'affichez pas, ne le loggez pas, ne le commitez pas.**
+3. Repérez l'entité de commande : un identifiant, un montant calculé côté serveur, un état « payée », et une colonne pour garder `payment.id()`.
+4. Un seul `TechnasPay` pour l'application (un `@Bean` Spring, un singleton) : il est sans état et sûr entre threads.
+
+## Installer
+
+Dépendance JitPack (voir le README) :
+
+```xml
+jitpack.iohttps://jitpack.io
+
+ com.github.Technas-Organization
+ technas-pay-java
+ v0.1.0
+
+```
+
+## Quelle méthode pour quoi
+
+| Besoin | Appel |
+|---|---|
+| Faire payer une commande | `pay.askForPayment(PaymentRequest.builder().amount(5000).reference(Status.retryReference(orderId, attempt)).customer(Customer.of(email, name)).returnUrl(…).build())`, puis rediriger (303) vers `payment.checkoutUrl()` |
+| Savoir qu'elle est payée | avis signé : `pay.handleWebhook(corpsBrut, signature, WebhookHandlers.builder().onCompleted(…).build())` |
+| Rattraper un avis manqué | `pay.getPaymentByReference(reference)` |
+| Savoir si on peut relancer | `onExpired`, ou `Status.canRetry(pay.getPayment(id).status())` |
+| Rembourser | `pay.refund(paymentId)` ou `pay.refund(paymentId, amount, fees, reference)` |
+| Noter un remboursement fait hors Technas | `pay.recordExternalRefund(paymentId, 2000, "Flooz", null, null, null)` |
+| Recharger le solde | `pay.topUpBalance(20000, "XOF", returnUrl)`, ouvrir `checkoutUrl()` ; `onTopUp` |
+| Solde, reversements, historique | `pay.getBalance()`, `pay.getSettlements()`, `pay.listTransactions(20, null, null)` |
+| Hors zone CFA | `pay.getFxMode()`, `pay.setFxMode("local", true, null, null)` (après accord explicite) |
+| Pays où vendre | `pay.setCountryRules(null, List.of("NG"))`, ou `.allowedCountries(…)` / `.excludedCountries(…)` par paiement |
+| Numéro de reversement (administrateur) | `pay.getPayoutNetworks("TG")`, `pay.setPayoutDestination("TG", "moov_tg", "+228…", "Nom")` |
+| Payer par carte | `.method("card").amount(new BigDecimal("12.50")).currency("EUR")` après `pay.getCardAccount().canAcceptPayments()` |
+| Ouvrir le compte carte | `pay.startCardOnboarding(returnUrl, refreshUrl, "TG", null, null)`, rediriger le RESPONSABLE vers `url()` |
+| Tableau de bord carte | `pay.getCardDashboardLink()` (le responsable s'y connecte avec ses identifiants) |
+| Tester la route d'avis | `pay.createTestWebhook("payment.completed", "42-1", BigDecimal.valueOf(5000), "XOF")` (corps et en-tête) |
+| Jouer le payeur en test | `pay.simulateTestPayment(id, "completed" \| "failed" \| "expired")` |
+
+## Étapes
+
+1. `TechnasPay pay = TechnasPay.fromEnv();` (lit `TECHNAS_PAY_SECRET` au premier appel).
+2. Action « payer » : relire la commande en base, `askForPayment`, garder `payment.id()`, rediriger vers `checkoutUrl()`.
+3. Route d'avis `POST` : corps BRUT (`@RequestBody String raw`), puis `handleWebhook` ; répondre `r.status()` avec `r.body()` en JSON. Spring Security : exclure cette route du CSRF et de l'authentification (la signature l'authentifie). Modèles : `examples/`.
+4. Test : poster `pay.createTestWebhook(...)` sur la route, puis le lancer.
+
+## App mobile (Flutter)
+
+Ne réécrivez pas de routes : `pay.appRoutes(authorize, resolveOrder).returnUrl(…).webhooks(…).card(?).authorizeAdmin(?).build()`, montées sous `/api/technas-pay` par `TechnasPayServlet.handle(routes, req, res, "/api/technas-pay")` (Spring MVC, Quarkus, Tomcat, Jetty). Hors Servlet : `routes.handle(new AppRequest(…))`. `resolveOrder(orderId, user)` relit la commande EN BASE et rend `null` si elle n'est pas à cet utilisateur. N'y mettez jamais un montant reçu de l'app. Côté app : `TechnasPayClient(baseUrl: '…/api/technas-pay')`.
+
+## Obligatoire
+
+- **`amount`** : en unité principale (`5000` = 5 000 FCFA, `new BigDecimal("12.50")` = 12,50 €, jamais × 100, jamais un `double`), calculé côté serveur. Entier pour le mobile money ; décimales seulement par carte.
+- **`reference`** : l'identifiant unique de la commande.
+- **`customer.email`** et **`customer.name`** : de vrais champs du client, jamais inventés.
+- **`returnUrl`** : la page de retour, en https en production.
+- Le reste est facultatif. Passez `customer.country` et `customer.phone` si l'application les connaît : ils évitent au client de choisir son pays.
+
+## La devise est automatique
+
+- **Ne passez pas `currency`** si l'application vend en francs CFA.
+ - La devise suit le pays du client : TG → XOF, CM → XAF, pour le même montant.
+ - Sans pays, le client choisit le sien sur la page de paiement.
+- **Ne fixez pas `defaultCurrency`** : il empêcherait ce choix.
+- **Hors zone, les montants peuvent avoir des centimes** (`121.96` GHS) : stockez-les en décimal, ne les arrondissez pas.
+- Dans le webhook, `event.payment().originalAmount()` est le montant demandé en F CFA ; `amount` et `currency` sont ce qui a été payé.
+
+## Où vendre (tout est facultatif)
+
+- **Le client choisit son pays** : sans `currency` ni `customer.country`, la page le lui demande.
+- **Pays fixé** : `customer.country`.
+- **Pour tout le compte** : `pay.setCountryRules(allowed, excluded)`. Codes ISO à deux lettres.
+- **Pour un seul paiement** : `.allowedCountries(…)` / `.excludedCountries(…)` dans `PaymentRequest`.
+- **Devise imposée** : `.currency("XAF")` ; ajoutez `.askCountry(true)` pour que le client choisisse parmi les pays de cette devise.
+- **Pays refusé** : `country_not_allowed`. Ne contournez pas ce refus : c'est le choix du marchand.
+
+## Clients hors zone franc CFA : une option à risque, décidée par l'utilisateur
+
+- **Montant** : il reste en F CFA, ne passez pas `currency`.
+- **C'est une option** : `pay.getFxMode()` dit laquelle est active, quels pays sont ouverts, et ce qui manque à chacun (`reason`).
+- **Technas ne couvre aucun risque de change.** Avant d'activer `local` ou `converted` :
+ 1. lisez `pay.getFxMode()` → `risks[mode]` (et `risks.markup` si un supplément est prévu) ;
+ 2. **montrez ce texte à l'utilisateur, en entier, et expliquez-le simplement** : ce qu'il peut perdre, dans quelle monnaie il sera payé, quel numéro de reversement il lui faut ;
+ 3. attendez son accord explicite, en toutes lettres ;
+ 4. seulement ensuite, appelez `pay.setFxMode(mode, true, markupPct, null)`.
+- **N'activez jamais une option de vous-même**, et ne passez jamais `acceptRisk: true` sans cet accord.
+- **`local`** : le solde est tenu et reversé dans la monnaie du client. Il faut un numéro de reversement **confirmé** dans cette monnaie (`setPayoutDestination`, réservé à un administrateur), sinon le pays reste fermé (`no_payout_number`).
+- **`converted`** : PAS ENCORE OUVERT. `setFxMode("converted", …)` lève `fx_mode_unavailable` : ne le proposez pas. Seules les options de `pay.getFxMode()` → `availableModes` existent (aujourd'hui `none` et `local`).
+- **`markupPct`** (0 à 20) : supplément payé par le client, affiché, qui revient au marchand.
+- **Ne promettez jamais** un pays que `getFxMode()` ne donne pas `available: true`.
+- **Webhooks** :
+ - branchez `onFxModeUpdated` : un changement d'option que l'utilisateur n'a pas fait signale une clé compromise ;
+ - branchez `onBalanceConverted` en mode `converted`.
+
+## Sécurité
+
+- **Le secret reste côté serveur.**
+ - Jamais dans un template rendu au navigateur, une variable JavaScript, une app mobile, un `application.properties` commité ni un endpoint Actuator (`/env`, `/configprops`).
+ - `TechnasPay.toString()` n'affiche pas le secret ; ne l'écrivez pas vous-même dans un log.
+ - Jamais de secret dans une page, une réponse JSON, une URL, un log ou un commit.
+- **Vérifiez la signature de chaque webhook avec le bon secret.**
+ - `handleWebhook` (ou `verifyWebhook`) le fait, avec le secret de `TechnasPay.of(…)` ou `TECHNAS_PAY_SECRET`.
+ - Un secret `tps_test_` ne vérifie que les webhooks de test, un secret `tps_live_` que ceux du réel.
+ - Le serveur qui reçoit les webhooks réels doit avoir le secret `tps_live_`.
+ - Ne contournez jamais un refus de signature (réponse 400).
+- **Conservez le corps brut** : `@RequestBody String raw` (Spring), jamais un objet désérialisé puis re-sérialisé avant la vérification.
+- **Seul le webhook prouve le paiement.** Ne marquez jamais une commande payée depuis la page `returnUrl`.
+- **Réservez à un administrateur** les remboursements et le numéro de reversement. Ne les exposez jamais sur une page publique.
+
+## La règle de relance (à respecter strictement)
+
+**Une référence = un essai. Relancez avec une NOUVELLE référence seulement après `payment.expired` (ou `getPayment` → `expired`), jamais sur `failed`.**
+
+- Ne prenez pas l'identifiant de commande tel quel comme `reference` : `Status.retryReference(orderId, tentative)` compose `"orderId-tentative"` ; gardez la tentative en base, pour pouvoir en créer une nouvelle.
+- Rejouer la référence d'un paiement expiré lève `payment_expired` (409) : ne réessayez pas le même appel, créez une nouvelle référence.
+- Après expiration, `checkoutUrl()` vaut `null` : n'envoyez jamais l'ancien lien au client.
+
+- `failed` n'est **pas** définitif : le client peut encore payer sur la même page pendant une heure, et `onCompleted` arriver ensuite. Dans `onFailed`, ne marquez pas la commande annulée, n'envoyez pas de nouveau lien.
+- `expired` est définitif : le lien est fermé, Technas a vérifié chez l'opérateur que rien n'a été payé ni n'est en cours. `Status.canRetry(payment.status())` vaut `true` seulement là.
+- La même référence rend le même paiement expiré : générez-en une nouvelle (ex. `orderId + "-2"`) et gardez le nouveau `payment.id()`.
+- Expliquez cette règle à l'utilisateur : un client relancé sur `failed` pourrait payer deux fois.
+
+## Webhooks
+
+- **Ils peuvent arriver plusieurs fois** : vos fonctions doivent le supporter. Vérifiez l'état en base, ou gardez `event.id()`.
+- **Ne rattrapez pas leurs erreurs pour répondre 200.** Une erreur doit remonter pour que le webhook soit relivré.
+- **Deux paiements pour une commande** : une cliente peut payer par mobile money puis par carte (deux séries de références). Dans `onCompleted`, si la commande est déjà payée par un AUTRE `payment.id()`, ne l'ignorez pas : signalez-la au marchand pour remboursement.
+- **`onFailed` n'est pas définitif** : `onCompleted` peut arriver après.
+- **`onExpired` est définitif** : seul moment où relancer le client (nouvelle référence).
+- **`onRefund`** : prévenez le client, par e-mail ou SMS. Technas ne lui écrit pas.
+ - `refund.completed` : l'argent est arrivé, `sentAmount` sur son téléphone.
+ - `refund.failed` : rien n'est parti et votre solde est recrédité. Proposez un autre moyen, ou refaites le même appel `refund` : il est permis après un échec.
+
+## Paiement par carte (`.method("card")`)
+
+Ce n'est PAS le même parcours que le mobile money. Ne le proposez que si l'utilisateur le demande.
+
+1. **Un compte carte d'abord, une seule fois.** Ajoutez dans les réglages de l'application un bouton « Activer le paiement par carte », réservé au responsable du compte. Au clic, côté serveur :
+ ```java
+ CardOnboardingLink link = pay.startCardOnboarding(site + "/reglages/carte?fin=1", site + "/reglages/carte?relance=1", "FR", null, null);
+ return ResponseEntity.status(303).location(URI.create(link.url())).build();
+ ```
+ - `country` est le pays de l'UTILISATEUR (pas de ses clients). Demandez-le-lui, ne le devinez pas.
+ - Le lien expire en quelques minutes : générez-le au clic, ne l'envoyez jamais par e-mail.
+ - Sur `refreshUrl`, rappelez `startCardOnboarding` et redirigez à nouveau.
+ - Sur `returnUrl`, affichez `pay.getCardAccount()` : `status` dit où il en est (`onboarding`, `under_review`, `restricted`, `enabled`) et `requirements` ce qui manque.
+ - Le responsable y donne son identité et sa banque sur la page sécurisée de notre partenaire carte (Stripe), qui lui fera accepter son contrat. Ni vous ni Technas ne voyez son IBAN.
+2. **Proposer la carte seulement si `canAcceptPayments` est vrai.** Gardez l'état en base via `onCardAccountUpdated`, ou relisez `getCardAccount()`. Sinon, ne montrez que le mobile money.
+3. **Faire payer :** `PaymentRequest.builder().method("card").amount(new BigDecimal("49.90")).currency("EUR")…`, puis redirection vers `payment.checkoutUrl()`. `currency` est obligatoire par carte. Le reste est identique : même webhook `onCompleted`, même règle « une référence = un essai », même `payment.expired` au bout d'une heure.
+4. **L'argent va directement sur le compte carte de l'utilisateur**, commission Technas déjà retirée. Il n'apparaît PAS dans `getBalance()` et ne passe pas par les reversements. Les virements vers sa banque se règlent dans son tableau de bord carte (`getCardDashboardLink()`).
+5. **Rembourser :** le même `pay.refund(paymentId, amount, null, null)`. La carte est remboursée depuis son compte carte (`refund.kind()` vaut `"card"`), sans toucher au solde Technas ; `fees` est sans objet. La commission n'est pas rendue.
+6. **Erreur `card_account_not_ready` (409)** : le compte n'encaisse pas encore. `e.details().get("accountStatus")` dit pourquoi. Ne réessayez pas : proposez le mobile money, ou renvoyez le responsable vers `startCardOnboarding`.
+7. **En test** (`tps_test_`), la carte de test `4242 4242 4242 4242`, une date future et n'importe quel code valident le paiement ; l'inscription de test accepte des données fictives.
+
+## Rembourser
+
+- **Appel** : `pay.refund(paymentId)` rembourse tout ce qui reste ; `pay.refund(paymentId, BigDecimal.valueOf(2000), null, null)` rembourse une partie.
+- **Destination** : l'argent repart au numéro qui a payé, jamais à un autre.
+- **Plafond** : le total remboursé ne dépasse jamais le montant payé.
+- **Commission** : la commission Technas n'est pas rendue.
+- **Frais du renvoi**, choisis à chaque appel avec `fees` :
+ - `"partner"` (défaut) : le client reçoit tout, les frais sont pris en plus sur votre solde ;
+ - `"customer"` : les frais sont retirés de ce qu'il reçoit (`sentAmount`).
+- **Idempotence** : rejouer le même appel ne rembourse pas deux fois. Pour deux remboursements partiels identiques et voulus, donnez à chacun sa `reference`, par exemple l'identifiant de la décision.
+- **Statut** : la réponse peut être `pending`. Le résultat arrive dans `onRefund`, ou par `pay.getRefund(id)`.
+- **Solde insuffisant** : l'erreur `insufficient_balance` donne `e.details().get("missingAmount")`. Rechargez avec `pay.topUpBalance`, puis rappelez `refund`.
+- **Remboursement fait hors Technas** (Flooz, T-Money, espèces) : `pay.recordExternalRefund(paymentId, amount, method, note, recordedBy, reference)`.
+ - Aucun argent ne bouge, le solde ne change pas.
+ - Il compte dans le même plafond que `refund`.
+ - Même idempotence, webhook `refund.recorded`.
+ - N'appelez jamais `refund` pour un remboursement déjà fait à la main : le client serait remboursé deux fois.
+- **Total remboursé** : `payment.refundedAmount()` additionne les deux sortes.
+
+## Erreurs
+
+- `card_account_not_ready` (409) : paiement par carte demandé sans compte carte actif. Voir « Paiement par carte ».
+- `card_payments_unavailable` (503) : la carte n'est pas encore ouverte chez Technas. Proposez le mobile money.
+- `currency_required` : `.method("card")` sans `currency`.
+
+`e.code()`, avec `e.retryable()` (vrai : refaites **le même appel**, mêmes valeurs) et `e.details()`.
+
+| `e.code()` | Que faire |
+|---|---|
+| `invalid_secret` | Variable absente ou mal copiée : demandez à l'utilisateur de la vérifier |
+| `invalid_api_key` | Secret refusé : contacter Technas |
+| `invalid_request` | Corriger le champ indiqué dans le message |
+| `invalid_amount`, `amount_too_low` | Montant entier positif, assez grand pour couvrir les frais |
+| `currency_not_enabled` | Devise non ouverte sur ce compte : contacter Technas |
+| `currency_conversion_unavailable` | Client hors zone CFA, mode de change `none` : ne pas proposer ce pays ; voir `getFxMode()` |
+| `country_not_allowed` | Le marchand ne vend pas dans ce pays : ne pas le proposer |
+| `country_not_available` | Pays pas prêt : `e.details().get("reason")` dit quoi (`no_payout_number`…) |
+| `risk_not_accepted` | Montrer `e.details().get("risk")` à l'utilisateur ; n'activer qu'avec son accord explicite |
+| `fx_mode_unavailable`, `fx_channel_unavailable` | Mode `converted` pas ouvert : proposer `local` (avec l'accord de l'utilisateur sur le risque) ou rester en `none` |
+| `quote_expired` | Le client rechoisit son pays sur la page, rien à faire côté code |
+| `reference_conflict` | Même référence, autres valeurs : ne pas réutiliser la référence |
+| `payment_in_progress` | Réessayer dans une minute, même appel |
+| `payment_not_found`, `refund_not_found` | Mauvais identifiant ou autre compte |
+| `payment_expired` | Cette référence est un essai expiré : nouveau paiement avec une NOUVELLE référence, jamais le même appel |
+| `payment_not_refundable` | Seul un paiement `completed` se rembourse |
+| `refund_exceeds_payment` | Rembourser au plus `e.details().get("refundableAmount")` |
+| `refund_conflict` | Cette `reference` de remboursement a déjà servi avec d'autres valeurs |
+| `insufficient_balance` | Recharger au moins `e.details().get("missingAmount")` avec `topUpBalance`, puis rappeler |
+| `payer_unknown`, `refund_network_unavailable` | Remboursement impossible par Technas : rembourser le client autrement, prévenir Technas |
+| `provider_unavailable`, `unavailable`, `network_error` | Panne passagère : refaire le même appel |
+| `rate_limited` | Ralentir, réessayer |
+
+## Vérifier l'intégration
+
+Avec un secret `tps_test_`, aucun argent ne circule.
+
+1. Lancez l'application et déclenchez un paiement : `checkoutUrl` ouvre une page de test (choix du pays, opérateurs, boutons « réussi » ou « refusé »).
+2. Cliquez sur « Simuler un paiement réussi », puis contrôlez côté serveur avec `pay.getPaymentByReference(reference)`.
+ Testez aussi la relance : sur un autre paiement, « Simuler un refus » (rien ne doit être relancé), puis « Simuler l'expiration du lien » (`onExpired` doit relancer avec une nouvelle référence). Sans navigateur : `pay.simulateTestPayment(id, "failed")` puis `"expired"`. Un paiement de test non payé expire aussi tout seul au bout d'une heure.
+3. Remboursez avec `pay.refund(payment.id())` : en test, le remboursement est terminé aussitôt, avec des frais réalistes, et aucun argent ne part. Si le solde manque, `pay.topUpBalance` ouvre une page de test pour le recharger.
+4. Le webhook n'arrive sur votre poste que si Technas connaît une adresse publique. Sinon, testez la route avec `pay.createTestWebhook`, et demandez à l'utilisateur de transmettre à son contact Technas l'adresse d'un tunnel.
+
+## Passer en réel
+
+Remplacez seulement le secret par `tps_live_…`. `returnUrl` doit alors être en https. Cette étape revient à l'utilisateur et à Technas : ne la faites pas de votre propre initiative.
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..965bacc
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,5 @@
+# Journal
+
+## 0.1.0 (15/11/2026)
+
+Première version : paiements mobile money et carte, statut, historique, remboursements, recharges, numéro de reversement, change, avis signés, routes toutes faites pour l'app (contrat v1, 23 cas) et adaptateur Servlet (Spring Boot, Quarkus, Tomcat, Jetty).
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d54f775
--- /dev/null
+++ b/README.md
@@ -0,0 +1,177 @@
+# technas-pay-java (Java, Kotlin)
+
+Encaissez des paiements mobile money et par carte via Technas depuis un serveur Java ou Kotlin : Spring Boot, Quarkus, Micronaut, Ktor, ou Java sans framework.
+
+**Technas Pay réunit le mobile money et la carte dans un seul SDK, du serveur jusqu'à l'app Flutter.** Carte : 1 % (plus les frais de votre compte carte). Mobile money : 2 % (les frais de l'opérateur sont payés par le client). Sans abonnement, et une clé de test sans papier pour commencer.
+
+Devises et pays, pièces demandées, versements, comparaison avec les autres prestataires : [le hub Technas Pay](https://github.com/Technas-Organization/technas-pay).
+
+Vous intégrez avec un assistant de code ? Dites-lui de lire [AGENTS.md](AGENTS.md).
+
+C'est la même API que les SDK [Node](https://github.com/Technas-Organization/technas-pay-node), [Python](https://github.com/Technas-Organization/technas-pay-python), [PHP](https://github.com/Technas-Organization/technas-pay-php) et [Dart](https://github.com/Technas-Organization/technas-pay-dart).
+
+## 1. Installer
+
+Java 17 ou plus récent. Une seule dépendance : `jackson-databind`. Installation depuis GitHub, par [JitPack](https://jitpack.io/#Technas-Organization/technas-pay-java).
+
+Maven :
+
+```xml
+
+ jitpack.iohttps://jitpack.io
+
+
+
+ com.github.Technas-Organization
+ technas-pay-java
+ v0.1.0
+
+```
+
+Gradle (Kotlin) :
+
+```kotlin
+repositories { maven("https://jitpack.io") }
+dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.1.0") }
+```
+
+Technas vous remet **un secret**. Mettez-le dans les variables d'environnement du serveur :
+
+```bash
+TECHNAS_PAY_SECRET=tps_test_...
+```
+
+Un secret `tps_test_` ne déplace aucun argent. Un secret `tps_live_` encaisse pour de vrai. Le code est le même.
+
+## 2. Demander un paiement
+
+```java
+import fr.technas.pay.Status;
+import fr.technas.pay.TechnasPay;
+import fr.technas.pay.model.Customer;
+import fr.technas.pay.model.Payment;
+import fr.technas.pay.model.PaymentRequest;
+
+TechnasPay pay = TechnasPay.fromEnv(); // lit TECHNAS_PAY_SECRET au premier appel ; un seul client pour l'application
+
+Payment payment = pay.askForPayment(PaymentRequest.builder()
+ .amount(5000) // entier : 5 000 FCFA
+ .reference(Status.retryReference(order.id(), order.attempt())) // "42-1" : une référence = un essai
+ .customer(Customer.of("client@exemple.com", "Awa Mensah"))
+ .returnUrl("https://votre-site.com/merci")
+ .metadata(Map.of("order_id", order.id()))
+ .build());
+order.setPaymentId(payment.id());
+return ResponseEntity.status(303).location(URI.create(payment.checkoutUrl())).build(); // Spring
+```
+
+Calculez le montant côté serveur. Ne passez pas `currency` si vous vendez en francs CFA : la devise suit le pays du client (`new Customer(email, name, phone, "TG")`), ou le client choisit son pays sur la page. Par carte : `.method("card")`, une `.currency("EUR")`, décimales permises (`.amount(new BigDecimal("12.50"))`). Les montants sont des `BigDecimal`, jamais des `double`.
+
+## 3. Recevoir l'avis de paiement
+
+Technas signe chaque avis (`X-Technas-Payment-Signature: t=…,s=…`). Le SDK vérifie la signature sur le **corps brut**, puis appelle votre fonction.
+
+```java
+@PostMapping("/technas/webhook")
+ResponseEntity