Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 47 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Dépendance JitPack (voir le README) :
<dependency>
<groupId>com.github.Technas-Organization</groupId>
<artifactId>technas-pay-java</artifactId>
<version>v0.2.1</version>
<version>v0.3.0</version>
</dependency>
```

Expand All @@ -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)` |
Expand Down Expand Up @@ -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()`.
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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).
Expand Down
50 changes: 48 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ Maven :
<dependency>
<groupId>com.github.Technas-Organization</groupId>
<artifactId>technas-pay-java</artifactId>
<version>v0.2.1</version>
<version>v0.3.0</version>
</dependency>
```

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 :
Expand Down Expand Up @@ -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
Expand Down
83 changes: 81 additions & 2 deletions contract/app-contract.v1.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -1088,4 +1167,4 @@
}
}
]
}
}
2 changes: 1 addition & 1 deletion examples/kotlin-spring/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
<dependency>
<groupId>fr.technas</groupId>
<artifactId>technas-pay</artifactId>
<version>0.2.1</version>
<version>0.3.0</version>
</dependency>
</dependencies>
<build>
Expand Down
2 changes: 1 addition & 1 deletion examples/spring-boot/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
<dependency>
<groupId>fr.technas</groupId>
<artifactId>technas-pay</artifactId>
<version>0.2.1</version>
<version>0.3.0</version>
</dependency>
</dependencies>
</project>
4 changes: 3 additions & 1 deletion llms.txt
Original file line number Diff line number Diff line change
@@ -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")`.
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<modelVersion>4.0.0</modelVersion>
<groupId>fr.technas</groupId>
<artifactId>technas-pay</artifactId>
<version>0.2.1</version>
<version>0.3.0</version>
<name>Technas Pay</name>
<description>Encaisser du mobile money et des paiements par carte via Technas Pay depuis Java ou Kotlin (Spring Boot, Jakarta Servlet).</description>
<url>https://github.com/Technas-Organization/technas-pay-java</url>
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/fr/technas/pay/TechnasPay.java
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@
* }</pre>
*/
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 « . »
Expand Down
4 changes: 3 additions & 1 deletion src/main/java/fr/technas/pay/app/AppRoutes.java
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion src/test/java/fr/technas/pay/AppContractTest.java
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Stream<DynamicTest> 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();
}

Expand Down
43 changes: 43 additions & 0 deletions src/test/java/fr/technas/pay/ChangementDOffreTest.java
Original file line number Diff line number Diff line change
@@ -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());
}
}
Loading