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: 10 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
version: 2
updates:
- package-ecosystem: maven
directory: /
schedule:
interval: weekly
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
63 changes: 63 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
name: CI

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

# Actions épinglées par empreinte de commit (une étiquette se déplace) ; Dependabot les met à jour.

jobs:
test:
# Dépôt PUBLIC : machines GitHub, gratuites et isolées. Jamais les runners ARC du cluster ici
# (une PR de fork y exécuterait son code ; décision de Jonas, 15/11/2026).
runs-on: ubuntu-latest
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
java: ["17", "21"]
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4
with:
distribution: temurin
java-version: ${{ matrix.java }}
cache: maven
- name: Compilation (avertissements = erreurs) et tests, contrat partagé compris
run: mvn -B install
- name: Les exemples Spring Boot (Java et Kotlin) compilent contre ce SDK
run: |
(cd examples/spring-boot && mvn -B -q compile)
(cd examples/kotlin-spring && mvn -B -q compile)

securite:
# Exigences de sécurité (Jonas, 15/11/2026) : analyse statique au plus strict, dépendances
# vulnérables, secrets.
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
fetch-depth: 0
- uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4
with:
distribution: temurin
java-version: "17"
cache: maven
- name: SpotBugs (effort max, seuil bas) avec FindSecBugs
run: mvn -B -DskipTests verify spotbugs:check
- name: Dépendances vulnérables (OSV-Scanner)
run: |
curl -fsSL -o osv-scanner https://github.com/google/osv-scanner/releases/download/v2.7.1/osv-scanner_linux_amd64
echo "fb7dab19a8bd9bbe5c3189f09d4b7ee1820c9553a23bac202648a56efd2f6ee8 osv-scanner" | sha256sum -c -
chmod +x osv-scanner
./osv-scanner scan source -L pom.xml
- name: Secrets dans l'historique
uses: trufflesecurity/trufflehog@ddc015e5ed99942b2253d8ea16a0586a01ef2ab1 # v3.88.0
with:
version: 3.88.0
extra_args: --only-verified
227 changes: 227 additions & 0 deletions AGENTS.md

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Journal

## 0.1.0 (15/11/2026)

Première version : paiements mobile money et carte, statut, historique, remboursements, recharges, numéro de reversement, change, avis signés, routes toutes faites pour l'app (contrat v1, 23 cas) et adaptateur Servlet (Spring Boot, Quarkus, Tomcat, Jetty).
177 changes: 177 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
# technas-pay-java (Java, Kotlin)

Encaissez des paiements mobile money et par carte via Technas depuis un serveur Java ou Kotlin : Spring Boot, Quarkus, Micronaut, Ktor, ou Java sans 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 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 ? Dites-lui de lire [AGENTS.md](AGENTS.md).

C'est la même API que les SDK [Node](https://github.com/Technas-Organization/technas-pay-node), [Python](https://github.com/Technas-Organization/technas-pay-python), [PHP](https://github.com/Technas-Organization/technas-pay-php) et [Dart](https://github.com/Technas-Organization/technas-pay-dart).

## 1. Installer

Java 17 ou plus récent. Une seule dépendance : `jackson-databind`. Installation depuis GitHub, par [JitPack](https://jitpack.io/#Technas-Organization/technas-pay-java).

Maven :

```xml
<repositories>
<repository><id>jitpack.io</id><url>https://jitpack.io</url></repository>
</repositories>

<dependency>
<groupId>com.github.Technas-Organization</groupId>
<artifactId>technas-pay-java</artifactId>
<version>v0.1.0</version>
</dependency>
```

Gradle (Kotlin) :

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

Technas vous remet **un secret**. Mettez-le dans les variables d'environnement du serveur :

```bash
TECHNAS_PAY_SECRET=tps_test_...
```

Un secret `tps_test_` ne déplace aucun argent. Un secret `tps_live_` encaisse pour de vrai. Le code est le même.

## 2. Demander un paiement

```java
import fr.technas.pay.Status;
import fr.technas.pay.TechnasPay;
import fr.technas.pay.model.Customer;
import fr.technas.pay.model.Payment;
import fr.technas.pay.model.PaymentRequest;

TechnasPay pay = TechnasPay.fromEnv(); // lit TECHNAS_PAY_SECRET au premier appel ; un seul client pour l'application

Payment payment = pay.askForPayment(PaymentRequest.builder()
.amount(5000) // entier : 5 000 FCFA
.reference(Status.retryReference(order.id(), order.attempt())) // "42-1" : une référence = un essai
.customer(Customer.of("client@exemple.com", "Awa Mensah"))
.returnUrl("https://votre-site.com/merci")
.metadata(Map.of("order_id", order.id()))
.build());
order.setPaymentId(payment.id());
return ResponseEntity.status(303).location(URI.create(payment.checkoutUrl())).build(); // Spring
```

Calculez le montant côté serveur. Ne passez pas `currency` si vous vendez en francs CFA : la devise suit le pays du client (`new Customer(email, name, phone, "TG")`), ou le client choisit son pays sur la page. Par carte : `.method("card")`, une `.currency("EUR")`, décimales permises (`.amount(new BigDecimal("12.50"))`). Les montants sont des `BigDecimal`, jamais des `double`.

## 3. Recevoir l'avis de paiement

Technas signe chaque avis (`X-Technas-Payment-Signature: t=…,s=…`). Le SDK vérifie la signature sur le **corps brut**, puis appelle votre fonction.

```java
@PostMapping("/technas/webhook")
ResponseEntity<Map<String, Object>> webhook(@RequestBody String raw, // corps BRUT, en String
@RequestHeader(value = Signature.HEADER, required = false) String signature) {
WebhookResult r = pay.handleWebhook(raw, signature, WebhookHandlers.builder()
.onCompleted(e -> orders.markPaid(e.payment().metadata().get("order_id"))) // idempotent
.onExpired(e -> orders.nextAttempt(e.payment().reference())) // seul moment où relancer
.build());
return ResponseEntity.status(r.status()).body(r.body()); // 400 si la signature est refusée
}
```

Fonctions disponibles : `onCompleted`, `onFailed` (pas définitif), `onExpired` (définitif), `onRefund`, `onTopUp`, `onPayoutDestination`, `onBalanceConverted`, `onFxModeUpdated`, `onCardAccountUpdated`. Une exception dans votre fonction doit remonter : Technas relivrera.

Kotlin :

```kotlin
val r = pay.handleWebhook(raw, signature, WebhookHandlers.builder()
.onCompleted { e -> orders.markPaid(e.payment().reference()) }
.build())
```

## 4. Pour une app mobile : les routes toutes faites

Votre app Flutter ([`technas_pay_flutter`](https://github.com/Technas-Organization/technas-pay-dart/tree/main/technas_pay_flutter)) appelle ces routes sans glue. Vous ne fournissez que votre authentification et la lecture de la commande en base :

```java
@RestController
class TechnasPayRoutes {
private final AppRoutes routes;

TechnasPayRoutes(TechnasPay pay, OrderRepository orders) {
routes = pay.<Principal>appRoutes(
req -> ((HttpServletRequest) req.original()).getUserPrincipal(), // null → 401
(orderId, user) -> orders.findByIdAndOwner(orderId, user.getName()) // relue EN BASE, null → 404
.map(o -> AppOrder.of(o.total(), Customer.of(o.email(), o.name())))
.orElse(null))
.returnUrl("https://votre-app.com/paiement/retour")
.webhooks(WebhookHandlers.builder().onCompleted(e -> orders.markPaid(e.payment().reference())).build())
.build();
}

@RequestMapping("/api/technas-pay/**")
void handle(HttpServletRequest req, HttpServletResponse res) throws IOException {
TechnasPayServlet.handle(routes, req, res, "/api/technas-pay");
}
}
```

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.

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

## 5. Tout le reste

| Méthode | Rôle |
|---|---|
| `getPayment(id)`, `getPaymentByReference(ref)` | Statut ; rattraper un avis manqué |
| `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 |
| `getRefund(id)` | Statut d'un remboursement |
| `topUpBalance(amount, currency, returnUrl)` | Recharger le solde (ouvrir `checkoutUrl()`) |
| `getBalance()`, `getSettlements()` | Solde par devise, reversements |
| `getFxMode()`, `setFxMode(mode, acceptRisk, markupPct, homeCurrency)` | Clients hors zone franc CFA (option à risque) |
| `setCountryRules(allowed, excluded)` | Où vous vendez |
| `getPayoutNetworks(country)`, `getPayoutDestination()`, `setPayoutDestination(...)` | Numéro de reversement |
| `startCardOnboarding(...)`, `getCardAccount()`, `getCardDashboardLink()` | Compte carte et son tableau de bord |
| `verifyWebhook(raw, sig)`, `handleWebhook(...)`, `createTestWebhook(...)` | Avis signés |
| `simulateTestPayment(id, "completed" \| "failed" \| "expired")` | Jouer le payeur en test |

Aides : `Status.canRetry(status)` (vrai seulement pour `expired`), `Status.isFinal()`, `Status.retryReference()`, `Status.currencyForCountry("TG")`.

## Erreurs

```java
try {
pay.askForPayment(request);
} catch (TechnasPayException e) {
if ("payment_expired".equals(e.code())) order.incrementAttempt(); // nouvelle référence
else if (e.retryable()) { /* refaire le même appel */ }
else throw e;
}
```

Codes et conduite à tenir : [AGENTS.md](AGENTS.md#erreurs).

## La règle de relance

**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.

## Développer

```bash
mvn verify spotbugs:check
```

Les tests tournent contre un faux transport (aucun appel réseau) et rejouent le contrat partagé. Sécurité : [SECURITY.md](SECURITY.md).

## Licence

MIT.
26 changes: 26 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Sécurité

## Signaler une faille

Écrivez à **contact@technas.fr**, objet « Sécurité : technas-pay-java ». N'ouvrez pas d'issue publique.
Nous accusons réception sous 3 jours ouvrés et vous tenons informé jusqu'au correctif.

Merci de ne pas tester sur les comptes d'autres partenaires ni en mode réel (`tps_live_`) : le mode test (`tps_test_`) suffit à tout reproduire.

## Ce que ce SDK garantit, et comment c'est vérifié

| Garantie | Où | Preuve |
|---|---|---|
| Signature des avis vérifiée sur le corps brut, comparaison en temps constant (`MessageDigest.isEqual`) | `webhook/Signature.java` | `SecurityTest.comparaisonEnTempsConstant` |
| Avis falsifié, rejoué, trop vieux (300 s) ou daté du futur : refusé, aucune fonction appelée | idem | `avisFalsifieRefuse`, `avisRejoueOuTropVieuxRefuse` |
| JSON strict : modèle en arbre seulement (aucune classe instanciée depuis la donnée reçue), pas de NaN, pas de clé en double, rien après la valeur, profondeur 64 | `internal/Json.java` | `corpsJsonPiegeRefuse`, `reponseIllisibleNonInterpretee` |
| Montants en `BigDecimal`, jamais en `double` | `model/` | relu ; SpotBugs |
| Casse ASCII seulement sur les adresses, devises et en-têtes (aucune transformation Unicode) | `internal/Ascii.java` | FindSecBugs `IMPROPER_UNICODE` |
| TLS toujours vérifié : aucun `TrustManager`, `HostnameVerifier` ni `SSLContext` dans le code ; aucune redirection suivie ; délais de connexion et de réponse posés | `http/JdkTransport.java` | `tlsJamaisDesactive`, `aucuneRedirectionSuivieEtDelaiPose` |
| La clé ne part que dans l'en-tête `Authorization`, jamais vers une adresse en clair, jamais dans une URL | `TechnasPay.java` | `cleJamaisVersUneAdresseEnClair`, `leSecretNApparaitNullePart` |
| Le secret n'apparaît dans aucun message, `toString` ni exception ; le client ne se sérialise pas | idem | `leSecretNApparaitNullePart`, `leClientNeSeSerialisePas` |
| Jamais de désérialisation Java, de réflexion sur la donnée reçue ni de typage polymorphe Jackson | tout `src/main` | `tlsJamaisDesactive` (liste des appels interdits) |
| Corps reçu par l'adaptateur Servlet borné à 64 Ko, lu brut | `servlet/TechnasPayServlet.java` | `ServletTest.parametresDeRequeteEtCorpsTropGrand` |
| Une dépendance d'exécution : `jackson-databind` | `pom.xml` | OSV-Scanner en CI, Dependabot |

En CI, à chaque modification : compilation avec tous les avertissements en erreur (`-Xlint:all -Werror`), SpotBugs au plus strict (effort max, seuil bas) avec FindSecBugs, OSV-Scanner sur les dépendances, recherche de secrets dans l'historique (TruffleHog). Dependabot surveille les dépendances Maven et les actions.
Loading
Loading