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
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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`).

Expand All @@ -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"
```


Expand Down Expand Up @@ -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é
Expand Down
6 changes: 5 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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é
Expand Down
2 changes: 1 addition & 1 deletion src/technas_pay/_version.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.4.0"
__version__ = "0.4.2"
2 changes: 1 addition & 1 deletion src/technas_pay/app_routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)],
})

Expand Down
2 changes: 1 addition & 1 deletion src/technas_pay/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]:
Expand Down
17 changes: 13 additions & 4 deletions src/technas_pay/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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]
Expand All @@ -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
Expand Down
7 changes: 7 additions & 0 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading