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
23 changes: 16 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Même API, mêmes règles que le SDK TypeScript `@technas/pay-next` : seuls les
## Installer

```bash
pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.6.0"
pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.7.0"
```


Expand All @@ -34,7 +34,7 @@ Créez UNE instance au niveau du module (`pay = TechnasPay()`) : elle lit `TECHN
| Savoir qu'elle est payée | webhook, `WebhookHandlers(on_completed=...)` |
| Rattraper un webhook manqué | `pay.get_payment_by_reference(reference)` |
| Savoir si on peut relancer | `on_expired`, ou `can_retry(pay.get_payment(id))` |
| Le client change d'offre ou revient plus tard | nouvel essai `retry_reference(facture_id, n + 1)` ; au retour, `pay.get_payment(dernier_paiement_id)` d'abord |
| Le client change d'offre ou revient plus tard | `pay.cancel_payment(ancien_id)`, puis nouvel essai `retry_reference(facture_id, n + 1)` ; au retour, `pay.get_payment(dernier_paiement_id)` d'abord (voir la section dédiée) |
| Rembourser | `pay.refund(payment_id, amount=?, fees=?, reference=?)` |
| Noter un remboursement fait hors Technas | `pay.record_external_refund(payment_id, amount=..., method="Flooz")` |
| Savoir que le remboursement est arrivé | `on_refund` (`refund.completed`, `refund.failed`, `refund.recorded`) |
Expand All @@ -58,7 +58,7 @@ Créez UNE instance au niveau du module (`pay = TechnasPay()`) : elle lit `TECHN

## App mobile (Flutter)

Ne réécrivez pas de routes : `pay.app_routes(authorize=..., resolve_order=..., return_url=..., webhooks=...)`, puis `.fastapi_router()`, `.flask_blueprint()` ou `.django_view()`. `resolve_order(order_id, user)` relit la commande EN BASE et rend `None` 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.app_routes(authorize=..., resolve_order=..., return_url=..., webhooks=...)`, puis `.fastapi_router()`, `.flask_blueprint()` ou `.django_view()`. `resolve_order(order_id, user)` relit la commande EN BASE et rend `None` si elle n'est pas à cet utilisateur. N'y mettez jamais un montant reçu de l'app. Routes : `GET /methods?orderId=`, `POST /payments`, `GET /payments/{id}`, `POST /payments/{id}/cancel`, `POST /webhook`. 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 @@ -131,7 +131,8 @@ Le client choisit une offre, arrive sur la page de paiement, ne paie pas, puis r

- **Une référence = un essai.** Nouvelle offre, ou retour après expiration : un NOUVEL essai, avec une nouvelle référence `retry_reference(facture_id, n + 1)` (`n` gardé en base). Réutiliser la référence avec un autre montant lève `reference_conflict` (409) ; celle d'un essai expiré, `payment_expired` (409). Les routes toutes faites (`app_routes`) le font seules.
- **Une facture n'est payée QUE sur `payment.completed`** (avis signé, `on_completed`). Jamais sur `return_url`, jamais à l'ouverture de la page.
- **Un essai non payé ne bloque jamais un nouvel essai.** `pending` ou `failed` et le client change d'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 (`checkout_url`). Autre offre : ANNULEZ l'ancien essai (`pay.cancel_payment(ancien_id)`), puis créez le nouveau avec une NOUVELLE référence ; ne refusez pas. `expired` : marquez la tentative expirée et laissez recommencer.
- **`cancel_payment` 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` (`canceled_at`, `cancel_reason` ; `can_retry` marche tel quel), et son avis `payment.expired` porte `event.payment.reason` = `canceled` (`timeout` pour une échéance passée, `None` dans un avis plus ancien).
- **Au retour du client**, vérifiez avec `pay.get_payment(dernier_paiement_id)` avant de dire quoi que ce soit ; ne vous fiez jamais seulement à votre base.
- **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(payment_id)`.

Expand All @@ -144,8 +145,15 @@ def payer(facture, montant):
dernier = pay.get_payment(facture.dernier_paiement_id) # la vérité est chez Technas
if dernier.status == "completed":
return "deja_payee"
# pending, failed, expired ou autre montant : nouvel essai, jamais un refus
facture.essai += 1
meme_offre = dernier.amount == montant
if meme_offre and dernier.status != "expired" and dernier.checkout_url:
return dernier.checkout_url # pending ou failed : même page, le client peut encore payer
if dernier.status != "expired":
# Autre offre : l'ancien lien est fermé d'abord. payment_in_progress (demande en cours
# chez l'opérateur) ou payment_already_completed (déjà payé) remontent : on ne crée
# alors AUCUN second paiement.
pay.cancel_payment(dernier.id)
facture.essai += 1 # nouvel essai, nouvelle référence, jamais un refus
paiement = pay.ask_for_payment(
amount=montant,
reference=retry_reference(facture.id, facture.essai),
Expand Down Expand Up @@ -199,7 +207,8 @@ Attrapez `TechnasPayError` et testez `error.code` (jamais le message). `error.re
| `fx_mode_unavailable`, `fx_channel_unavailable` | `converted` pas ouvert : proposer `local` (avec accord) ou rester en `none` |
| `quote_expired` | Le client rechoisit son pays sur la page, rien à faire |
| `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_in_progress` | Réessayer dans une minute, même appel. Sur `cancel_payment` : ne créez PAS de second paiement, attendez l'avis de l'issue |
| `payment_already_completed` | `cancel_payment` : le paiement est déjà payé. Relire le paiement ; ne créer aucun nouvel essai |
| `payment_not_found`, `refund_not_found` | Mauvais identifiant ou autre compte |
| `payment_expired` | Essai expiré : NOUVELLE référence (`attempt + 1`), 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 @@
# Changelog

## 0.7.0 — 2026-11-16

Annuler un paiement : `cancel_payment(id)` (`POST /v1/payments/{id}/cancel`, client sync et async) annule DÉFINITIVEMENT un paiement que personne n'a commencé à payer ; rend le paiement (`status` `expired`, `checkout_url` `None`). Idempotent. `Payment` : `canceled_at`, `cancel_reason` ; `Payment` et `EventPayment` : `reason` (avis `payment.expired` : `canceled` ou `timeout`, `None` dans un avis plus ancien). Nouvelle erreur `payment_already_completed` (409, non rejouable). Routes toutes faites : `POST /payments/{id}/cancel` (même contrôle de propriété que `GET /payments/{id}`), et sur `reference_conflict` l'ancien essai est relu par sa référence puis annulé avant l'essai suivant ; payé ou demande en cours chez l'opérateur : aucun second paiement, l'erreur est rendue à l'app. Si l'annulation répond 404 (serveur qui ne l'a pas encore), le démarrage passe à l'essai suivant comme avant. Contrat v1 : 31 cas (`query_includes` vérifié).

## 0.6.0 — 2026-11-15

Le client change d'offre ou revient plus tard. Routes toutes faites (`app_routes`) : un `reference_conflict` (la référence d'un essai existe avec un autre montant : le client a changé d'offre) fait passer à l'essai suivant, comme `payment_expired`, dans la même borne `max_attempts` : jamais un refus. Contrat v1 : 24 cas. Documentation : nouvelle section « Le client change d'offre ou revient plus tard » (AGENTS.md, README, llms.txt) avec un exemple ; test de scénario (essai expiré, puis nouvel essai d'un autre montant).
Expand Down
20 changes: 15 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ C'est la même API que le SDK TypeScript [`@technas/pay-next`](https://github.co
## 1. Installer

```bash
pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.6.0"
pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.7.0"
```

Seule dépendance : `httpx`. Python 3.9 ou plus récent.
Expand Down Expand Up @@ -93,13 +93,14 @@ app.include_router(routes.fastapi_router()) # FastAPI → /api/technas-
# Django : path("api/technas-pay/<path:rest>", routes.django_view())
```

Routes : `GET /methods?orderId=`, `POST /payments` `{orderId}`, `GET /payments/{id}`, `POST /webhook` (adresse à déclarer à Technas). Les crochets peuvent être sync ou async. Les essais expirés sont sautés tout seuls (`42-1`, `42-2`…) : rien à stocker. Contrat : [`contract/app-contract.v1.json`](contract/app-contract.v1.json), rejoué par ce paquet et par le client Flutter.
Routes : `GET /methods?orderId=`, `POST /payments` `{orderId}`, `GET /payments/{id}`, `POST /payments/{id}/cancel` (le client change d'offre : l'essai affiché est annulé), `POST /webhook` (adresse à déclarer à Technas). Les crochets peuvent être sync ou async. Les essais expirés sont sautés tout seuls (`42-1`, `42-2`…) : rien à stocker. Si la commande a changé de montant, `POST /payments` annule lui-même l'ancien essai encore ouvert avant d'en créer un autre ; s'il est déjà payé (`payment_already_completed`) ou qu'une demande est en cours chez l'opérateur (`payment_in_progress`), aucun second paiement n'est créé et l'erreur est rendue à l'app. Contrat : [`contract/app-contract.v1.json`](contract/app-contract.v1.json), rejoué par ce paquet et par le client Flutter.

## 4. Tout le reste

| Méthode | Rôle |
|---|---|
| `get_payment(id)`, `get_payment_by_reference(ref)` | Statut ; rattraper un webhook manqué |
| `cancel_payment(id)` | Annuler un paiement que personne n'a commencé à payer (le client change d'offre) |
| `list_transactions(limit=, status=, cursor=)` | Historique paginé (`next_cursor`) |
| `refund(payment_id, amount=?, fees="partner"\|"customer", reference=?)` | Rembourser au numéro qui a payé |
| `record_external_refund(payment_id, amount=, method=, note=?, recorded_by=?)` | Noter un remboursement fait hors Technas |
Expand Down Expand Up @@ -128,6 +129,8 @@ try:
except TechnasPayError as e:
if e.code == "payment_expired":
order.attempt += 1 # nouvelle référence, jamais le même appel
elif e.code == "payment_already_completed":
... # cancel_payment : déjà payé, relire, ne rien créer
elif e.retryable:
... # refaire le même appel, mêmes valeurs
else:
Expand All @@ -154,7 +157,7 @@ Les chiffres (seuil, délai) viennent de l'API (`threshold_xof`, `grace_days`) :

**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 (`retry_reference(order_id, attempt + 1)`).

Le client change d'offre ou revient plus tard : c'est un NOUVEL essai (`retry_reference(facture_id, n + 1)`), jamais un refus, même si l'essai précédent est encore `pending` ou `failed`. Réutiliser une référence avec un autre montant lève `reference_conflict` ; les routes toutes faites passent seules à l'essai suivant. Au retour du client, relisez le dernier essai (`get_payment`) avant de dire quoi que ce soit. La facture n'est payée que sur `payment.completed` ; si le client a payé deux pages, remboursez l'essai en trop (`refund`).
Le client change d'offre ou revient plus tard : c'est un NOUVEL essai (`retry_reference(facture_id, n + 1)`), jamais un refus, même si l'essai précédent est encore `pending` ou `failed`. Autre offre : ANNULEZ d'abord l'ancien essai (`pay.cancel_payment(ancien_id)`), puis créez le nouveau avec une NOUVELLE référence. Si l'annulation répond `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 ; `payment_already_completed` : le client a payé l'ancienne offre, relisez le paiement et ne créez rien. Un paiement annulé reste `expired` (`can_retry` marche tel quel), avec `canceled_at` et `cancel_reason` ; son avis `payment.expired` porte `reason` = `canceled` (`timeout` pour une échéance passée). Réutiliser une référence avec un autre montant lève `reference_conflict` ; les routes toutes faites annulent l'ancien essai et passent seules à l'essai suivant. Au retour du client, relisez le dernier essai (`get_payment`) avant de dire quoi que ce soit. La facture n'est payée que sur `payment.completed` ; si le client a payé deux pages, remboursez l'essai en trop (`refund`).

```python
from technas_pay import retry_reference
Expand All @@ -165,8 +168,15 @@ def payer(facture, montant):
dernier = pay.get_payment(facture.dernier_paiement_id) # la vérité est chez Technas
if dernier.status == "completed":
return "deja_payee"
# pending, failed, expired ou autre montant : nouvel essai, jamais un refus
facture.essai += 1
meme_offre = dernier.amount == montant
if meme_offre and dernier.status != "expired" and dernier.checkout_url:
return dernier.checkout_url # pending ou failed : même page, le client peut encore payer
if dernier.status != "expired":
# Autre offre : l'ancien lien est fermé d'abord. payment_in_progress (demande en cours
# chez l'opérateur) ou payment_already_completed (déjà payé) remontent : on ne crée
# alors AUCUN second paiement.
pay.cancel_payment(dernier.id)
facture.essai += 1 # nouvel essai, nouvelle référence, jamais un refus
paiement = pay.ask_for_payment(
amount=montant,
reference=retry_reference(facture.id, facture.essai),
Expand Down
Loading
Loading