From 9a1aa7bae20255083402e8a0d04551ad3f79c743 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Vihoal=C3=A9=20ANIGLO?= <46029829+JIV-DLS@users.noreply.github.com> Date: Sun, 15 Nov 2026 22:15:46 +0100 Subject: [PATCH] Le client change d'offre ou revient plus tard : essai suivant, jamais un refus, 0.3.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Routes toutes faites : reference_conflict fait passer à l'essai suivant, comme payment_expired (le montant de la commande a changé). Contrat v1 à 24 cas. README, AGENTS.md et llms.txt : la règle et un exemple ; test de scénario (essai expiré, nouvelle offre, référence réutilisée refusée). --- AGENTS.md | 48 ++++++++++- CHANGELOG.md | 4 + README.md | 50 ++++++++++- contract/app-contract.v1.json | 83 ++++++++++++++++++- examples/kotlin-spring/pom.xml | 2 +- examples/spring-boot/pom.xml | 2 +- llms.txt | 4 +- pom.xml | 2 +- src/main/java/fr/technas/pay/TechnasPay.java | 2 +- .../java/fr/technas/pay/app/AppRoutes.java | 4 +- .../java/fr/technas/pay/AppContractTest.java | 2 +- .../fr/technas/pay/ChangementDOffreTest.java | 43 ++++++++++ 12 files changed, 234 insertions(+), 12 deletions(-) create mode 100644 src/test/java/fr/technas/pay/ChangementDOffreTest.java diff --git a/AGENTS.md b/AGENTS.md index 1c5346c..713499f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ Dépendance JitPack (voir le README) : com.github.Technas-Organization technas-pay-java - v0.2.1 + v0.3.0 ``` @@ -31,6 +31,7 @@ Dépendance JitPack (voir le README) : | 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)` | +| Le client change d'offre ou revient plus tard | nouvel essai `Status.retryReference(factureId, n + 1)` ; au retour, `pay.getPayment(dernierPaymentId)` d'abord (voir la section dédiée) | | 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)` | @@ -129,6 +130,51 @@ Ne réécrivez pas de routes : `pay.appRoutes(authorize, resolveOrder).returnUrl - 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. +## Le client change d'offre ou revient plus tard + +Le client choisit une offre, ouvre la page de paiement, ne paie pas, puis revient choisir une AUTRE offre, ou revient le lendemain. Rien n'est payé : ne répondez jamais « un paiement existe déjà ». + +- **Une référence = un essai.** Nouvelle offre, ou retour après expiration : un NOUVEL essai, `Status.retryReference(factureId, n + 1)`, `n` gardé en base. Réutiliser la référence d'un autre montant lève `reference_conflict` (409) ; celle d'un essai expiré, `payment_expired` (409). Les routes toutes faites (`appRoutes`) le font seules. +- **Une facture n'est payée QUE sur `payment.completed`** (`onCompleted`). Jamais sur `returnUrl`, jamais à l'ouverture de la page. +- **Un essai non payé ne bloque jamais un nouvel essai.** Même offre et essai `pending` ou `failed` : renvoyez le client sur la même page (`checkoutUrl()`). Autre offre : créez le nouvel essai, ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer. +- **Au retour du client**, vérifiez `pay.getPayment(dernierPaymentId)` avant de dire quoi que ce soit : votre base peut avoir manqué un avis. +- **Un ancien essai payé APRÈS le nouveau** (le client a payé les deux pages) : n'activez rien deux fois, remboursez l'essai en trop avec `pay.refund(paymentId)`. + +```java +Payment payer(Facture f, long montant) { + if (f.dernierPaymentId() != null) { + Payment dernier = pay.getPayment(f.dernierPaymentId()); // jamais la base seule + if ("completed".equals(dernier.status())) { + throw new DejaPayee(f.id()); + } + boolean memeOffre = dernier.amount().compareTo(BigDecimal.valueOf(montant)) == 0; + if (memeOffre && !"expired".equals(dernier.status()) && dernier.checkoutUrl() != null) { + return dernier; // pending ou failed : même page, le client peut encore payer + } + } + int essai = factures.essaiSuivant(f.id()); // n + 1, gardé en base + Payment p = pay.askForPayment(PaymentRequest.builder() + .amount(montant) + .reference(Status.retryReference(f.id(), essai)) + .customer(Customer.of(f.email(), f.nom())) + .returnUrl("https://votre-site.com/merci") + .metadata(Map.of("facture_id", f.id())) + .build()); + factures.retenirPaiement(f.id(), p.id()); + return p; +} + +// Dans onCompleted : la facture déjà payée par un AUTRE paiement → rembourser celui-ci. +.onCompleted(e -> { + String id = e.payment().metadata().get("facture_id").toString(); + if (factures.estPayeePar(id, e.payment().id()) || !factures.estPayee(id)) { + factures.marquerPayee(id, e.payment().id()); // idempotent + } else { + pay.refund(e.payment().id()); // second paiement : rien n'est activé deux fois + } +}) +``` + ## Webhooks - **Ils peuvent arriver plusieurs fois** : vos fonctions doivent le supporter. Vérifiez l'état en base, ou gardez `event.id()`. diff --git a/CHANGELOG.md b/CHANGELOG.md index 4953525..77f70f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Journal +## 0.3.0 (15/11/2026) + +Le client change d'offre ou revient plus tard : les routes toutes faites passent à l'essai suivant sur `reference_conflict` (comme sur `payment_expired`) ; contrat v1 à 24 cas ; section dédiée dans README et AGENTS.md ; test de scénario. + ## 0.2.1 (15/11/2026) Avis `account.kyc_required` complet : `stage()`, `blockReason()`, `daysElapsed()`, `graceDays()`, `firstCollectedAt()` (nuls dans un avis plus ancien). diff --git a/README.md b/README.md index 86078d1..a8a9599 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Maven : com.github.Technas-Organization technas-pay-java - v0.2.1 + v0.3.0 ``` @@ -32,7 +32,7 @@ Gradle (Kotlin) : ```kotlin repositories { maven("https://jitpack.io") } -dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.2.1") } +dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.3.0") } ``` Technas vous remet **un secret**. Mettez-le dans les variables d'environnement du serveur : @@ -169,6 +169,52 @@ En réel, un compte sans pièce d'identité vérifiée voit ses NOUVEAUX paiemen **Une référence = un essai.** `failed` n'est pas définitif : le client peut encore payer sur la même page pendant une heure. Ne relancez qu'après `payment.expired`, avec une nouvelle référence. +### Le client change d'offre ou revient plus tard + +Le client choisit une offre, ouvre la page de paiement, ne paie pas, puis revient choisir une AUTRE offre, ou revient le lendemain. Rien n'est payé : ne répondez jamais « un paiement existe déjà ». + +- **Une référence = un essai.** Nouvelle offre, ou retour après expiration : un NOUVEL essai, `Status.retryReference(factureId, n + 1)`, `n` gardé en base. Réutiliser la référence d'un autre montant lève `reference_conflict` (409) ; celle d'un essai expiré, `payment_expired` (409). Les routes toutes faites (`appRoutes`) le font seules. +- **Une facture n'est payée QUE sur `payment.completed`** (`onCompleted`). Jamais sur `returnUrl`, jamais à l'ouverture de la page. +- **Un essai non payé ne bloque jamais un nouvel essai.** Même offre et essai `pending` ou `failed` : renvoyez le client sur la même page (`checkoutUrl()`). Autre offre : créez le nouvel essai, ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer. +- **Au retour du client**, vérifiez `pay.getPayment(dernierPaymentId)` avant de dire quoi que ce soit : votre base peut avoir manqué un avis. +- **Un ancien essai payé APRÈS le nouveau** (le client a payé les deux pages) : n'activez rien deux fois, remboursez l'essai en trop avec `pay.refund(paymentId)`. + +```java +Payment payer(Facture f, long montant) { + if (f.dernierPaymentId() != null) { + Payment dernier = pay.getPayment(f.dernierPaymentId()); // jamais la base seule + if ("completed".equals(dernier.status())) { + throw new DejaPayee(f.id()); + } + boolean memeOffre = dernier.amount().compareTo(BigDecimal.valueOf(montant)) == 0; + if (memeOffre && !"expired".equals(dernier.status()) && dernier.checkoutUrl() != null) { + return dernier; // pending ou failed : même page, le client peut encore payer + } + } + int essai = factures.essaiSuivant(f.id()); // n + 1, gardé en base + Payment p = pay.askForPayment(PaymentRequest.builder() + .amount(montant) + .reference(Status.retryReference(f.id(), essai)) + .customer(Customer.of(f.email(), f.nom())) + .returnUrl("https://votre-site.com/merci") + .metadata(Map.of("facture_id", f.id())) + .build()); + factures.retenirPaiement(f.id(), p.id()); + return p; +} + +// Dans onCompleted : la facture déjà payée par un AUTRE paiement → rembourser celui-ci. +.onCompleted(e -> { + String id = e.payment().metadata().get("facture_id").toString(); + if (factures.estPayeePar(id, e.payment().id()) || !factures.estPayee(id)) { + factures.marquerPayee(id, e.payment().id()); // idempotent + } else { + pay.refund(e.payment().id()); // second paiement : rien n'est activé deux fois + } +}) +``` + + ## Développer ```bash diff --git a/contract/app-contract.v1.json b/contract/app-contract.v1.json index 101639d..191a3dc 100644 --- a/contract/app-contract.v1.json +++ b/contract/app-contract.v1.json @@ -1,7 +1,7 @@ { "name": "technas-pay-app", "version": 1, - "doc": "Contrat entre une app (technas_pay_flutter, TechnasPayClient) et les routes toutes faites des SDK serveur Technas Pay. Les chemins sont relatifs au préfixe de montage (ex. /api/technas-pay). Fichier copié À L'IDENTIQUE dans technas-pay-node, technas-pay-python et technas-pay-dart : chaque dépôt rejoue tous les cas. 'message' est un texte libre, jamais comparé. 'user' : l'utilisateur rendu par authorize (null = non authentifié). 'orders' : ce que resolveOrder rend pour (orderId, user) ; absent = commande inconnue ou d'un autre. 'gateway' : réponses successives de pay-api.technas.fr. Le webhook (POST /webhook, signé) est testé à part : sa signature dépend de l'heure. 'options' : options des routes pour ce cas ({card: true} ouvre la carte). 'admin' : présent = authorizeAdmin est branché et rend cette valeur (null = pas le marchand, 403). Une référence de paiement par carte est orderId-card-N, mobile money orderId-N. Le paiement rendu à l'app porte 'method'.", + "doc": "Contrat entre une app (technas_pay_flutter, TechnasPayClient) et les routes toutes faites des SDK serveur Technas Pay. Les chemins sont relatifs au préfixe de montage (ex. /api/technas-pay). Fichier copié À L'IDENTIQUE dans technas-pay-node, technas-pay-python et technas-pay-dart : chaque dépôt rejoue tous les cas. 'message' est un texte libre, jamais comparé. 'user' : l'utilisateur rendu par authorize (null = non authentifié). 'orders' : ce que resolveOrder rend pour (orderId, user) ; absent = commande inconnue ou d'un autre. 'gateway' : réponses successives de pay-api.technas.fr. Le webhook (POST /webhook, signé) est testé à part : sa signature dépend de l'heure. 'options' : options des routes pour ce cas ({card: true} ouvre la carte). 'admin' : présent = authorizeAdmin est branché et rend cette valeur (null = pas le marchand, 403). Une référence de paiement par carte est orderId-card-N, mobile money orderId-N. Un essai expiré (payment_expired) ou dont le montant ne correspond plus (reference_conflict : le client a changé d'offre) est sauté : essai suivant. Le paiement rendu à l'app porte 'method'.", "routes": [ { "method": "GET", @@ -200,6 +200,85 @@ } } }, + { + "name": "démarrer : le client a changé d'offre (autre montant) → essai suivant, jamais un refus", + "request": { + "method": "POST", + "path": "/payments", + "body": { + "orderId": "42" + } + }, + "user": "u1", + "orders": { + "42": { + "amount": 7500, + "customer": { + "email": "awa@exemple.tg", + "name": "Awa Mensah" + } + } + }, + "gateway": [ + { + "status": 409, + "body": { + "code": "reference_conflict", + "message": "m" + } + }, + { + "status": 201, + "body": { + "id": "pay_2", + "reference": "42-2", + "amount": 7500, + "currency": null, + "commission": 150, + "net_amount": 7350, + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_2", + "metadata": {}, + "test_mode": true, + "created_at": "2026-11-15T10:00:00Z", + "expires_at": "2026-11-15T11:00:00Z" + } + } + ], + "expect_gateway": [ + { + "method": "POST", + "path": "/v1/payments", + "body_includes": { + "amount": 7500, + "reference": "42-1" + } + }, + { + "method": "POST", + "path": "/v1/payments", + "body_includes": { + "amount": 7500, + "reference": "42-2" + } + } + ], + "expect": { + "status": 200, + "body": { + "payment": { + "id": "pay_2", + "reference": "42-2", + "status": "pending", + "checkout_url": "https://pay-api.technas.fr/checkout/pay_2", + "amount": 7500, + "currency": null, + "expires_at": "2026-11-15T11:00:00Z", + "method": "mobile_money" + } + } + } + }, { "name": "démarrer : le montant ne vient jamais du téléphone", "request": { @@ -1088,4 +1167,4 @@ } } ] -} \ No newline at end of file +} diff --git a/examples/kotlin-spring/pom.xml b/examples/kotlin-spring/pom.xml index 589440b..7e1d22d 100644 --- a/examples/kotlin-spring/pom.xml +++ b/examples/kotlin-spring/pom.xml @@ -28,7 +28,7 @@ fr.technas technas-pay - 0.2.1 + 0.3.0 diff --git a/examples/spring-boot/pom.xml b/examples/spring-boot/pom.xml index a682f66..77ebe40 100644 --- a/examples/spring-boot/pom.xml +++ b/examples/spring-boot/pom.xml @@ -23,7 +23,7 @@ fr.technas technas-pay - 0.2.1 + 0.3.0 diff --git a/llms.txt b/llms.txt index e61595e..a15ce0a 100644 --- a/llms.txt +++ b/llms.txt @@ -1,9 +1,11 @@ # technas-pay-java (Java, Kotlin) -> SDK Java 17+ et Kotlin (côté serveur : Spring Boot, Quarkus, Micronaut, Ktor) pour encaisser du mobile money en Afrique et des paiements par carte via Technas Pay, rembourser et recharger son solde. Une dépendance (jackson-databind). Montant seul, en F CFA : la devise (XOF ou XAF) suit le pays du client. Installation depuis GitHub par JitPack : com.github.Technas-Organization:technas-pay-java:v0.2.1. +> SDK Java 17+ et Kotlin (côté serveur : Spring Boot, Quarkus, Micronaut, Ktor) pour encaisser du mobile money en Afrique et des paiements par carte via Technas Pay, rembourser et recharger son solde. Une dépendance (jackson-databind). Montant seul, en F CFA : la devise (XOF ou XAF) suit le pays du client. Installation depuis GitHub par JitPack : com.github.Technas-Organization:technas-pay-java:v0.3.0. Agents de code : lisez d'abord AGENTS.md. +Client qui change d'offre ou revient plus tard : nouvel essai (référence suivante), jamais « paiement déjà existant » ; payé seulement sur payment.completed ; au retour, getPayment(dernierPaymentId) d'abord ; un second paiement réussi se rembourse. + Une référence = un essai : `Status.retryReference(orderId, attempt)`. Relancez avec une NOUVELLE référence seulement après payment.expired (`Status.canRetry`), jamais sur failed. Routes toutes faites pour une app Flutter : `pay.appRoutes(authorize, resolveOrder).build()` + `TechnasPayServlet.handle(routes, req, res, "/api/technas-pay")`. diff --git a/pom.xml b/pom.xml index 50c5830..0449259 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ 4.0.0 fr.technas technas-pay - 0.2.1 + 0.3.0 Technas Pay Encaisser du mobile money et des paiements par carte via Technas Pay depuis Java ou Kotlin (Spring Boot, Jakarta Servlet). https://github.com/Technas-Organization/technas-pay-java diff --git a/src/main/java/fr/technas/pay/TechnasPay.java b/src/main/java/fr/technas/pay/TechnasPay.java index f05d318..eb9ca74 100644 --- a/src/main/java/fr/technas/pay/TechnasPay.java +++ b/src/main/java/fr/technas/pay/TechnasPay.java @@ -50,7 +50,7 @@ * } */ public final class TechnasPay { - public static final String VERSION = "0.2.1"; + public static final String VERSION = "0.3.0"; public static final String DEFAULT_BASE_URL = "https://pay-api.technas.fr"; public static final String SECRET_ENV = "TECHNAS_PAY_SECRET"; private static final Pattern SECRET = Pattern.compile("^tps_(live|test)_([\\x21-\\x2d\\x2f-\\x7e]+)\\.([\\x21-\\x2d\\x2f-\\x7e]+)$"); // ASCII imprimable sans « . » diff --git a/src/main/java/fr/technas/pay/app/AppRoutes.java b/src/main/java/fr/technas/pay/app/AppRoutes.java index 5e6a8dc..d2e8788 100644 --- a/src/main/java/fr/technas/pay/app/AppRoutes.java +++ b/src/main/java/fr/technas/pay/app/AppRoutes.java @@ -136,7 +136,9 @@ private Payment start(String orderId, AppOrder order, String method) { try { return pay.askForPayment(r.build()); } catch (TechnasPayException e) { - if ("payment_expired".equals(e.code()) && attempt < maxAttempts) { + // Essai expiré, ou référence d'un autre montant (le client a changé d'offre) : essai + // suivant. Un essai non payé ne bloque jamais un nouvel essai. + if (("payment_expired".equals(e.code()) || "reference_conflict".equals(e.code())) && attempt < maxAttempts) { continue; } throw e; diff --git a/src/test/java/fr/technas/pay/AppContractTest.java b/src/test/java/fr/technas/pay/AppContractTest.java index 2032c15..2999690 100644 --- a/src/test/java/fr/technas/pay/AppContractTest.java +++ b/src/test/java/fr/technas/pay/AppContractTest.java @@ -106,7 +106,7 @@ Stream contrat() throws IOException { } })); } - assertEquals(23, tests.size(), "le contrat v1 a 23 cas"); + assertEquals(24, tests.size(), "le contrat v1 a 24 cas"); return tests.stream(); } diff --git a/src/test/java/fr/technas/pay/ChangementDOffreTest.java b/src/test/java/fr/technas/pay/ChangementDOffreTest.java new file mode 100644 index 0000000..928fea3 --- /dev/null +++ b/src/test/java/fr/technas/pay/ChangementDOffreTest.java @@ -0,0 +1,43 @@ +package fr.technas.pay; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import fr.technas.pay.model.Payment; +import java.math.BigDecimal; +import java.util.Map; +import org.junit.jupiter.api.Test; + +/** Le client ouvre la page, ne paie pas, revient avec une AUTRE offre : nouvel essai, jamais un refus. */ +class ChangementDOffreTest { + @Test + void essaiExpirePuisNouvelleOffre() { + FakeTransport t = new FakeTransport() + .reply(201, ClientTest.payment(Map.of("id", "pay_1", "reference", "F-1", "amount", 5000))) + .reply(303, Map.of()) + .reply(200, ClientTest.payment(Map.of("id", "pay_1", "reference", "F-1", "amount", 5000, "status", "expired"))) + .reply(200, ClientTest.payment(Map.of("id", "pay_1", "reference", "F-1", "amount", 5000, "status", "expired"))) + .reply(201, ClientTest.payment(Map.of("id", "pay_2", "reference", "F-2", "amount", 7500))) + .reply(409, Map.of("code", "reference_conflict", "message", "m")); + TechnasPay pay = ClientTest.pay(t); + + Payment p1 = pay.askForPayment(ClientTest.req(Status.retryReference("F", 1)).amount(5000).build()); + assertEquals("expired", pay.simulateTestPayment(p1.id(), "expired").status()); + Payment relu = pay.getPayment(p1.id()); // au retour du client : on relit avant de répondre + assertEquals("expired", relu.status()); + assertEquals(true, Status.canRetry(relu.status())); + + Payment p2 = pay.askForPayment(ClientTest.req(Status.retryReference("F", 2)).amount(7500).build()); + assertEquals("pending", p2.status()); + assertEquals("F-2", t.calls.get(4).json().get("reference").asText()); + assertEquals(0, new BigDecimal("7500").compareTo(t.calls.get(4).json().get("amount").decimalValue())); + + // Réutiliser la référence d'un autre montant : refus explicite, à ne pas rejouer tel quel. + TechnasPayException e = assertThrows(TechnasPayException.class, + () -> pay.askForPayment(ClientTest.req("F-1").amount(7500).build())); + assertEquals("reference_conflict", e.code()); + assertEquals(409, e.status()); + assertFalse(e.retryable()); + } +}