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
17 changes: 12 additions & 5 deletions 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.3.0</version>
<version>v0.4.0</version>
</dependency>
```

Expand All @@ -31,7 +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) |
| Le client change d'offre ou revient plus tard | `pay.cancelPayment(ancienId)`, puis 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 All @@ -56,7 +56,7 @@ Dépendance JitPack (voir le README) :

## 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')`.
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. Le client change d'offre : l'app appelle `POST /payments/{id}/cancel` sur l'essai affiché, puis `POST /payments` ; si la commande a changé de montant, `POST /payments` annule lui-même l'ancien essai encore ouvert. Côté app : `TechnasPayClient(baseUrl: '…/api/technas-pay')`.

## Obligatoire

Expand Down Expand Up @@ -136,7 +136,8 @@ Le client choisit une offre, ouvre la page de paiement, ne paie pas, puis revien

- **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.
- **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 : ANNULEZ l'ancien essai (`pay.cancelPayment(ancienId)`), puis créez le nouveau avec une NOUVELLE référence ; ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer.
- **`cancelPayment` refuse quand c'est trop tard** : `payment_already_completed` (le client a payé l'ancienne offre : relisez le paiement, ne créez rien) ; `payment_in_progress` (une demande est en cours chez l'opérateur : ne créez PAS de second paiement, attendez l'avis de l'issue). Un paiement annulé reste `expired` (`canceledAt()`, `cancelReason()`), et son avis `payment.expired` porte `reason()` = `canceled` (`timeout` pour une échéance passée).
- **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)`.

Expand All @@ -151,6 +152,11 @@ Payment payer(Facture f, long montant) {
if (memeOffre && !"expired".equals(dernier.status()) && dernier.checkoutUrl() != null) {
return dernier; // pending ou failed : même page, le client peut encore payer
}
if (!"expired".equals(dernier.status())) {
// Autre offre : l'ancien lien est fermé d'abord. payment_in_progress ou
// payment_already_completed remontent : on ne crée alors AUCUN second paiement.
pay.cancelPayment(dernier.id());
}
}
int essai = factures.essaiSuivant(f.id()); // n + 1, gardé en base
Payment p = pay.askForPayment(PaymentRequest.builder()
Expand Down Expand Up @@ -257,9 +263,10 @@ Ce n'est PAS le même parcours que le mobile money. Ne le proposez que si l'util
| `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_already_completed` | `cancelPayment` : le paiement est déjà payé. Relire le paiement ; ne créer aucun nouvel essai |
| `kyc_required` | Pièce d'identité à déposer : `e.details().get("consoleUrl")`, `reason` (`amount` ou `duration`). Proposer la carte ; ne pas réessayer |
| `contract_required` | Le responsable doit accepter le contrat dans la console (`e.details().get("version")`) ; ne pas réessayer |
| `payment_in_progress` | Réessayer dans une minute, même appel |
| `payment_in_progress` | Réessayer dans une minute, même appel. Sur `cancelPayment` : ne créez PAS de second paiement, attendez l'avis de l'issue |
| `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 |
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.4.0 (16/11/2026)

`cancelPayment(id)` (`POST /v1/payments/{id}/cancel`) : annule un paiement que personne n'a commencé à payer. `Payment` : `canceledAt()`, `cancelReason()`, `reason()` (avis `payment.expired` : `canceled` ou `timeout`). Routes toutes faites : `POST /payments/{id}/cancel`, et sur `reference_conflict` l'ancien essai est relu puis annulé avant le suivant (aucun second paiement si l'annulation répond `payment_in_progress` ou `payment_already_completed`). Contrat v1 à 30 cas.

## 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.
Expand Down
12 changes: 8 additions & 4 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.3.0</version>
<version>v0.4.0</version>
</dependency>
```

Gradle (Kotlin) :

```kotlin
repositories { maven("https://jitpack.io") }
dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.3.0") }
dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.4.0") }
```

Technas vous remet **un secret**. Mettez-le dans les variables d'environnement du serveur :
Expand Down Expand Up @@ -122,7 +122,7 @@ class TechnasPayRoutes {

Hors Servlet (Ktor, Vert.x, Micronaut Netty) : construisez une `AppRequest(method, path, query, headers, rawBody, original)` et renvoyez `routes.handle(req)` (`status()`, `json()`).

Routes : `GET /methods?orderId=`, `POST /payments` `{orderId, method?}`, `GET /payments/{id}`, `POST /webhook` (adresse à déclarer à Technas). Les essais expirés sont sautés tout seuls (`42-1`, `42-2`…) : rien à stocker. Carte : `.card(true)` et une `currency` dans `AppOrder`, puis `.authorizeAdmin(...)` pour l'écran du marchand (`GET /card/account`, `POST /card/onboarding`). Contrat : [`contract/app-contract.v1.json`](contract/app-contract.v1.json), rejoué par ce paquet, les autres SDK et le client Flutter.
Routes : `GET /methods?orderId=`, `POST /payments` `{orderId, method?}`, `GET /payments/{id}`, `POST /payments/{id}/cancel` (le client change d'offre), `POST /webhook` (adresse à déclarer à Technas). Les essais expirés sont sautés tout seuls (`42-1`, `42-2`…) : rien à stocker. Carte : `.card(true)` et une `currency` dans `AppOrder`, puis `.authorizeAdmin(...)` pour l'écran du marchand (`GET /card/account`, `POST /card/onboarding`). Contrat : [`contract/app-contract.v1.json`](contract/app-contract.v1.json), rejoué par ce paquet, les autres SDK et le client Flutter.

Exemples complets, compilés en CI : [`examples/spring-boot`](examples/spring-boot) (Java) et [`examples/kotlin-spring`](examples/kotlin-spring) (Kotlin).

Expand All @@ -131,6 +131,7 @@ Exemples complets, compilés en CI : [`examples/spring-boot`](examples/spring-bo
| Méthode | Rôle |
|---|---|
| `getPayment(id)`, `getPaymentByReference(ref)` | Statut ; rattraper un avis manqué |
| `cancelPayment(id)` | Annuler un paiement que personne n'a commencé à payer (le client change d'offre) |
| `listTransactions(limit, status, cursor)` | Historique paginé (`nextCursor()`) |
| `refund(paymentId)`, `refund(paymentId, amount, fees, reference)` | Rembourser au numéro ou à la carte qui a payé |
| `recordExternalRefund(paymentId, amount, method, note, recordedBy, reference)` | Noter un remboursement fait hors Technas |
Expand Down Expand Up @@ -175,7 +176,7 @@ Le client choisit une offre, ouvre la page de paiement, ne paie pas, puis revien

- **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.
- **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 : ANNULEZ l'ancien essai (`pay.cancelPayment(ancienId)`), puis créez le nouveau avec une NOUVELLE référence ; ne refusez pas. Si l'annulation répond `payment_in_progress` ou `payment_already_completed`, ne créez aucun second paiement. `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)`.

Expand All @@ -190,6 +191,9 @@ Payment payer(Facture f, long montant) {
if (memeOffre && !"expired".equals(dernier.status()) && dernier.checkoutUrl() != null) {
return dernier; // pending ou failed : même page, le client peut encore payer
}
if (!"expired".equals(dernier.status())) {
pay.cancelPayment(dernier.id()); // autre offre : l'ancien lien est fermé d'abord
}
}
int essai = factures.essaiSuivant(f.id()); // n + 1, gardé en base
Payment p = pay.askForPayment(PaymentRequest.builder()
Expand Down
Loading
Loading