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());
+ }
+}