diff --git a/AGENTS.md b/AGENTS.md index 046904f..fabee58 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # technas-pay (Python) : règles pour un agent de code -Consignes pour un assistant de code (Codex, Claude Code…). Appliquez-les dans l'application de l'utilisateur, pas dans ce dépôt. Le README détaille chaque fonction ; des exemples complets sont dans [`examples/`](examples) (FastAPI, Flask, Django). Ce fichier est aussi livré dans le paquet : `python -c "import technas_pay, pathlib; print(pathlib.Path(technas_pay.__file__).with_name('AGENTS.md'))"`. +Consignes pour un assistant de code. Appliquez-les dans l'application de l'utilisateur, pas dans ce dépôt. Le README détaille chaque fonction ; des exemples complets sont dans [`examples/`](examples) (FastAPI, Flask, Django). Ce fichier est aussi livré dans le paquet : `python -c "import technas_pay, pathlib; print(pathlib.Path(technas_pay.__file__).with_name('AGENTS.md'))"`. Même API, mêmes règles que le SDK TypeScript `@technas/pay-next` : seuls les noms passent en snake_case (`askForPayment` → `ask_for_payment`, `checkoutUrl` → `checkout_url`). @@ -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.4.1" +pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.4.2" ``` @@ -87,11 +87,11 @@ Ne réécrivez pas de routes : `pay.app_routes(authorize=..., resolve_order=..., ## Paiement par carte -1. **Compte carte, une fois** : au clic du RESPONSABLE sur « Activer la carte », `link = pay.start_card_onboarding(country="TG", return_url=..., refresh_url=...)`, puis redirigez-le vers `link.url` (il y donne son identité et sa banque ; le lien expire en minutes). `refresh_url` : rappelez la méthode et redirigez de nouveau. +1. **Compte carte, une fois** : au clic du RESPONSABLE sur « Activer la carte », `link = pay.start_card_onboarding(country="TG", return_url=..., refresh_url=...)`, puis redirigez-le vers `link.url` : il y donne son identité et sa banque sur la page sécurisée de notre partenaire carte (Stripe), qui vous fera accepter son contrat (le lien expire en minutes). `refresh_url` : rappelez la méthode et redirigez de nouveau. 2. **Attendez `pay.get_card_account().can_accept_payments`** (ou le webhook `on_card_account_updated`). Avant, `method="card"` lève `card_account_not_ready` (`error.details.account_status`). 3. **Faire payer** : `pay.ask_for_payment(method="card", amount=12.5, currency="EUR", ...)`. Devise obligatoire, décimales permises (jamais × 100). -4. **L'argent va directement sur le compte carte**, commission Technas déjà retirée : il n'apparaît pas dans `get_balance()`. Un remboursement repart sur la carte depuis ce compte (`refund.kind == "stripe"`). -5. **Tableau de bord** (virements, litiges) : `pay.get_card_dashboard_link()` → https://dashboard.stripe.com/, où le responsable se connecte avec SES identifiants Stripe. +4. **L'argent va directement sur le compte carte**, commission Technas déjà retirée : il n'apparaît pas dans `get_balance()`. Un remboursement repart sur la carte depuis ce compte (`refund.kind == "card"`). +5. **Tableau de bord** (virements, litiges) : `pay.get_card_dashboard_link()` → le tableau de bord de votre compte carte, où le responsable se connecte avec SES identifiants. 6. **App mobile** : `pay.app_routes(..., card=True, authorize_admin=...)` ; `/methods` n'ouvre la carte que si le compte est prêt et que `resolve_order` rend une `currency`. ## Sécurité diff --git a/CHANGELOG.md b/CHANGELOG.md index 856e7bc..6398d38 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,12 @@ # Changelog +## 0.4.2 — 2026-11-15 + +Remboursement par carte : `Refund.kind` vaut désormais `"card"` (valeurs : `"payout"` | `"external"` | `"card"`). Pendant la transition, un `"stripe"` encore renvoyé par l'API est lu comme `"card"`. Documentation : carte à 1 % (plus les frais de votre compte carte), mobile money à 2 % (les frais de l'opérateur sont payés par le client). + ## 0.4.0 — 2026-11-15 -Paiement par carte : `ask_for_payment(method="card", currency=...)` (décimales permises), `start_card_onboarding`, `get_card_account`, `get_card_dashboard_link` (https://dashboard.stripe.com/), `card_account_not_ready` (`details.account_status`), `on_card_account_updated`, `Payment.method`, remboursement `kind == "stripe"`. Routes de l'app : `card=True`, `authorize_admin` (`GET /card/account`, `POST /card/onboarding`), `POST /payments {method: "card"}` (références `orderId-card-N`). `to_app_json` porte `method`. Contrat v1 : 23 cas. +Paiement par carte : `ask_for_payment(method="card", currency=...)` (décimales permises), `start_card_onboarding`, `get_card_account`, `get_card_dashboard_link` (tableau de bord du compte carte), `card_account_not_ready` (`details.account_status`), `on_card_account_updated`, `Payment.method`, remboursement par carte (`kind`, voir 0.4.2). Routes de l'app : `card=True`, `authorize_admin` (`GET /card/account`, `POST /card/onboarding`), `POST /payments {method: "card"}` (références `orderId-card-N`). `to_app_json` porte `method`. Contrat v1 : 23 cas. ## 0.3.0 — 2026-11-15 diff --git a/README.md b/README.md index 6c47f82..e6b62cf 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,18 @@ Encaissez des paiements mobile money et par carte via Technas depuis un serveur Python : FastAPI, Django, Flask, ou tout autre framework. -**Technas Pay réunit le mobile money et la carte dans un seul SDK, du serveur jusqu'à l'app Flutter.** Carte : 1 % (plus les frais Stripe de votre compte). Mobile money : 2 % (les frais de l'opérateur sont payés par le client). Sans abonnement, et une clé de test sans papier pour commencer. +**Technas Pay réunit le mobile money et la carte dans un seul SDK, du serveur jusqu'à l'app Flutter.** Carte : 1 % (plus les frais de votre compte carte). Mobile money : 2 % (les frais de l'opérateur sont payés par le client). Sans abonnement, et une clé de test sans papier pour commencer. Devises et pays, pièces demandées, versements, comparaison avec les autres prestataires : [le hub Technas Pay](https://github.com/Technas-Organization/technas-pay). -Vous intégrez avec un assistant de code (Codex, Claude Code…) ? Dites-lui de lire [AGENTS.md](AGENTS.md), livré dans le paquet avec [llms.txt](llms.txt). +Vous intégrez avec un assistant de code ? Dites-lui de lire [AGENTS.md](AGENTS.md), livré dans le paquet avec [llms.txt](llms.txt). C'est la même API que le SDK TypeScript [`@technas/pay-next`](https://github.com/Technas-Organization/technas-pay-next), en snake_case. ## 1. Installer ```bash -pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.4.1" +pip install "technas-pay @ git+https://github.com/Technas-Organization/technas-pay-python@v0.4.2" ``` Seule dépendance : `httpx`. Python 3.9 ou plus récent. @@ -141,11 +141,11 @@ La liste complète des codes et quoi faire est dans [AGENTS.md](AGENTS.md#erreur ## Paiement par carte -1. **Compte carte, une fois** : au clic du RESPONSABLE sur « Activer la carte », `link = pay.start_card_onboarding(country="TG", return_url=..., refresh_url=...)`, puis redirigez-le vers `link.url` (il y donne son identité et sa banque ; le lien expire en minutes). `refresh_url` : rappelez la méthode et redirigez de nouveau. +1. **Compte carte, une fois** : au clic du RESPONSABLE sur « Activer la carte », `link = pay.start_card_onboarding(country="TG", return_url=..., refresh_url=...)`, puis redirigez-le vers `link.url` : il y donne son identité et sa banque sur la page sécurisée de notre partenaire carte (Stripe), qui vous fera accepter son contrat (le lien expire en minutes). `refresh_url` : rappelez la méthode et redirigez de nouveau. 2. **Attendez `pay.get_card_account().can_accept_payments`** (ou le webhook `on_card_account_updated`). Avant, `method="card"` lève `card_account_not_ready` (`error.details.account_status`). 3. **Faire payer** : `pay.ask_for_payment(method="card", amount=12.5, currency="EUR", ...)`. Devise obligatoire, décimales permises (jamais × 100). -4. **L'argent va directement sur le compte carte**, commission Technas déjà retirée : il n'apparaît pas dans `get_balance()`. Un remboursement repart sur la carte depuis ce compte (`refund.kind == "stripe"`). -5. **Tableau de bord** (virements, litiges) : `pay.get_card_dashboard_link()` → https://dashboard.stripe.com/, où le responsable se connecte avec SES identifiants Stripe. +4. **L'argent va directement sur le compte carte**, commission Technas déjà retirée : il n'apparaît pas dans `get_balance()`. Un remboursement repart sur la carte depuis ce compte (`refund.kind == "card"`). +5. **Tableau de bord** (virements, litiges) : `pay.get_card_dashboard_link()` → le tableau de bord de votre compte carte, où le responsable se connecte avec SES identifiants. 6. **App mobile** : `pay.app_routes(..., card=True, authorize_admin=...)` ; `/methods` n'ouvre la carte que si le compte est prêt et que `resolve_order` rend une `currency`. ## Sécurité diff --git a/src/technas_pay/_version.py b/src/technas_pay/_version.py index 6a9beea..df12433 100644 --- a/src/technas_pay/_version.py +++ b/src/technas_pay/_version.py @@ -1 +1 @@ -__version__ = "0.4.0" +__version__ = "0.4.2" diff --git a/src/technas_pay/app_routes.py b/src/technas_pay/app_routes.py index 644fffa..762f3c2 100644 --- a/src/technas_pay/app_routes.py +++ b/src/technas_pay/app_routes.py @@ -212,7 +212,7 @@ async def handle(self, req: AppRequest) -> AppResponse: return AppResponse(200, { "amount": order.amount, "currency": order.currency, - # La carte s'ouvre avec le compte carte du marchand (Stripe Connect) : à venir. + # La carte s'ouvre seulement quand le compte carte du marchand est prêt. "methods": [{"method": "mobile_money", "available": True, "reason": None}, await self._card_method(order)], }) diff --git a/src/technas_pay/client.py b/src/technas_pay/client.py index 459685f..1a8657a 100644 --- a/src/technas_pay/client.py +++ b/src/technas_pay/client.py @@ -517,7 +517,7 @@ def get_card_account(self) -> CardAccount: return self._run(self._get_card_account()) def get_card_dashboard_link(self) -> str: - """https://dashboard.stripe.com/ : le responsable s'y connecte avec SES identifiants Stripe.""" + """Le tableau de bord de votre compte carte : le responsable s'y connecte avec SES identifiants.""" return self._run(self._get_card_dashboard_link()) def get_balance(self) -> List[Balance]: diff --git a/src/technas_pay/models.py b/src/technas_pay/models.py index 38cd528..6e252c8 100644 --- a/src/technas_pay/models.py +++ b/src/technas_pay/models.py @@ -15,6 +15,7 @@ FxModeName = Literal["none", "local", "converted"] RefundFees = Literal["partner", "customer"] +RefundKind = Literal["payout", "external", "card"] PaymentMethod = Literal["mobile_money", "card"] """``mobile_money`` (défaut) ou ``card`` (exige un compte carte actif et une devise).""" Number = Union[int, float] @@ -265,9 +266,10 @@ class Refund: #: ``pending`` | ``completed`` | ``failed`` status: str failure: Optional[str] - #: ``payout`` (renvoyé par Technas sur le numéro qui a payé) | ``stripe`` (paiement par carte, remboursé - #: sur la carte depuis VOTRE compte carte) | ``external`` (fait hors plateforme, seulement enregistré) - kind: str + #: ``payout`` (renvoyé par Technas sur le numéro qui a payé) | ``card`` (paiement par carte, remboursé + #: sur la carte depuis VOTRE compte carte) | ``external`` (fait hors plateforme, seulement enregistré). + #: Une ancienne valeur ``stripe`` renvoyée par l'API est lue comme ``card``. + kind: RefundKind method: Optional[str] note: Optional[str] recorded_by: Optional[str] @@ -279,12 +281,19 @@ def from_api(cls, raw: Dict[str, Any]) -> "Refund": id=raw.get("id"), payment_id=raw.get("payment_id"), payment_reference=raw.get("payment_reference"), amount=raw.get("amount"), sent_amount=raw.get("sent_amount"), fee=raw.get("fee"), fees=raw.get("fees"), balance_debit=raw.get("balance_debit"), currency=raw.get("currency"), - status=raw.get("status"), failure=raw.get("failure"), kind=raw.get("kind") or "payout", + status=raw.get("status"), failure=raw.get("failure"), kind=_refund_kind(raw.get("kind")), method=raw.get("method"), note=raw.get("note"), recorded_by=raw.get("recorded_by"), created_at=raw.get("created_at"), ) +def _refund_kind(raw: Optional[str]) -> RefundKind: + """``payout`` | ``external`` | ``card`` ; l'ancien ``stripe`` (transition) devient ``card``.""" + if not raw: + return "payout" + return "card" if raw == "stripe" else raw # type: ignore[return-value] + + @dataclass(frozen=True) class TopUp: id: str diff --git a/tests/test_client.py b/tests/test_client.py index 9721513..bb6b85e 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -257,3 +257,10 @@ def handler(request): pay.start_card_onboarding(return_url="https://a", refresh_url="https://b", country="fr") assert e.value.code == "card_account_not_ready" and e.value.details.account_status == "onboarding" assert calls[-1]["country"] == "FR" + + +@pytest.mark.parametrize("received, expected", [("stripe", "card"), ("card", "card"), + ("payout", "payout"), ("external", "external"), (None, "payout")]) +def test_refund_kind_stripe_received_is_read_as_card(received, expected): + from technas_pay.models import Refund + assert Refund.from_api({"id": "r1", "kind": received}).kind == expected