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, selon le pays : environ 1,5 % + 0,25 € en Europe). 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.
Vous intégrez avec un assistant de code ? Dites-lui de lire AGENTS.md.
C'est la même API que les SDK Node, Python, PHP et Dart.
Java 17 ou plus récent. Une seule dépendance : jackson-databind. Installation depuis GitHub, par JitPack.
Maven :
<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.5.0</version>
</dependency>Gradle (Kotlin) :
repositories { maven("https://jitpack.io") }
dependencies { implementation("com.github.Technas-Organization:technas-pay-java:v0.5.0") }Technas vous remet un secret. Mettez-le dans les variables d'environnement du serveur :
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.
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(); // SpringCalculez 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.
Technas signe chaque avis (X-Technas-Payment-Signature: t=…,s=…). Le SDK vérifie la signature sur le corps brut, puis appelle votre fonction.
@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, onKycRequired, onSettlement. Une exception dans votre fonction doit remonter : Technas relivrera.
onSettlement reçoit settlement.completed et settlement.failed, l'issue d'un reversement de votre solde vers votre numéro mobile money. event.settlement() donne amount() (sorti du solde), fee() (frais du versement, à votre charge) et netAmount() (arrivé sur le numéro). Sur settlement.failed, amount() est recrédité sur le solde.
Kotlin :
val r = pay.handleWebhook(raw, signature, WebhookHandlers.builder()
.onCompleted { e -> orders.markPaid(e.payment().reference()) }
.build())Votre app Flutter (technas_pay_flutter) appelle ces routes sans glue. Vous ne fournissez que votre authentification et la lecture de la commande en base :
@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 /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, rejoué par ce paquet, les autres SDK et le client Flutter.
Exemples complets, compilés en CI : examples/spring-boot (Java) et examples/kotlin-spring (Kotlin).
| 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 |
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 |
getAccountKyc() |
Seuil d'identité : encaissé, seuil, échéance, lien de la console |
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").
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.
En réel, un compte sans pièce d'identité vérifiée voit ses NOUVEAUX paiements mobile money refusés (kyc_required) au-delà d'un montant encaissé ou d'un nombre de jours après son premier paiement réel (aujourd'hui 1 000 000 F CFA ou 30 jours : lisez-les dans getAccountKyc(), ne les écrivez pas en dur). Rien de ce qui existe n'est bloqué, et la carte n'est pas concernée. getAccountKyc() donne l'état à montrer au marchand ; l'avis account.kyc_required (onKycRequired, contenu event.kyc() : reason() est son déclencheur, stage() et blockReason() l'état, comme getAccountKyc()) arrive à 80 % du seuil, 7 jours avant l'échéance, puis au premier refus. Le responsable dépose sa pièce dans la console (consoleUrl()).
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.
Le client choisit une offre, ouvre la page de paiement, ne paie pas, puis revient choisir une AUTRE offre, ou revient le lendemain. Rien n'est payé : ne répondez jamais « un paiement existe déjà ».
- Une référence = un essai. Nouvelle offre, ou retour après expiration : un NOUVEL essai,
Status.retryReference(factureId, n + 1),ngardé en base. Réutiliser la référence d'un autre montant lèvereference_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 surreturnUrl, jamais à l'ouverture de la page. - Un essai non payé ne bloque jamais un nouvel essai. Même offre et essai
pendingoufailed: 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épondpayment_in_progressoupayment_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).
Payment payer(Facture f, long montant) {
if (f.dernierPaymentId() != null) {
Payment dernier = pay.getPayment(f.dernierPaymentId()); // jamais la base seule
if ("completed".equals(dernier.status())) {
throw new DejaPayee(f.id());
}
boolean memeOffre = dernier.amount().compareTo(BigDecimal.valueOf(montant)) == 0;
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()
.amount(montant)
.reference(Status.retryReference(f.id(), essai))
.customer(Customer.of(f.email(), f.nom()))
.returnUrl("https://votre-site.com/merci")
.metadata(Map.of("facture_id", f.id()))
.build());
factures.retenirPaiement(f.id(), p.id());
return p;
}
// Dans onCompleted : la facture déjà payée par un AUTRE paiement → rembourser celui-ci.
.onCompleted(e -> {
String id = e.payment().metadata().get("facture_id").toString();
if (factures.estPayeePar(id, e.payment().id()) || !factures.estPayee(id)) {
factures.marquerPayee(id, e.payment().id()); // idempotent
} else {
pay.refund(e.payment().id()); // second paiement : rien n'est activé deux fois
}
})mvn verify spotbugs:checkLes tests tournent contre un faux transport (aucun appel réseau) et rejouent le contrat partagé. Sécurité : SECURITY.md.
MIT.