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
14 changes: 13 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Dépendance JitPack (voir le README) :
<dependency>
<groupId>com.github.Technas-Organization</groupId>
<artifactId>technas-pay-java</artifactId>
<version>v0.1.1</version>
<version>v0.2.0</version>
</dependency>
```

Expand All @@ -41,6 +41,7 @@ Dépendance JitPack (voir le README) :
| Numéro de reversement (administrateur) | `pay.getPayoutNetworks("TG")`, `pay.setPayoutDestination("TG", "moov_tg", "+228…", "Nom")` |
| Payer par carte | `.method("card").amount(new BigDecimal("12.50")).currency("EUR")` après `pay.getCardAccount().canAcceptPayments()` |
| Ouvrir le compte carte | `pay.startCardOnboarding(returnUrl, refreshUrl, "TG", null, null)`, rediriger le RESPONSABLE vers `url()` |
| Seuil d'identité (marchand) | `pay.getAccountKyc()` : `stage()`, `collectedXof()`, `thresholdXof()`, `deadline()`, `consoleUrl()` ; avis `onKycRequired` (`event.kyc()`) |
| Tableau de bord carte | `pay.getCardDashboardLink()` (le responsable s'y connecte avec ses identifiants) |
| Tester la route d'avis | `pay.createTestWebhook("payment.completed", "42-1", BigDecimal.valueOf(5000), "XOF")` (corps et en-tête) |
| Jouer le payeur en test | `pay.simulateTestPayment(id, "completed" \| "failed" \| "expired")` |
Expand Down Expand Up @@ -179,6 +180,15 @@ Ce n'est PAS le même parcours que le mobile money. Ne le proposez que si l'util
- N'appelez jamais `refund` pour un remboursement déjà fait à la main : le client serait remboursé deux fois.
- **Total remboursé** : `payment.refundedAmount()` additionne les deux sortes.

## Seuil d'identité

- **La règle** : en réel, un compte sans pièce d'identité vérifiée voit ses NOUVEAUX paiements mobile money refusés (`kyc_required`, 409) au-delà d'un montant encaissé en cumul ou d'un nombre de jours après son premier paiement réel encaissé (aujourd'hui 1 000 000 F CFA ou 30 jours).
- **Les chiffres viennent de l'API** : `pay.getAccountKyc()` (`thresholdXof()`, `graceDays()`, `collectedXof()`, `deadline()`). Ne les écrivez jamais en dur.
- **Rien de ce qui existe n'est bloqué** : paiement en cours, remboursement, reversement, lecture. La carte n'est pas concernée.
- **Montrez l'état au MARCHAND** (réglages, tableau de bord), jamais au client final. `stage()` vaut `ok`, `soon` (préavis), `blocked`, `verified` ou `not_applicable`.
- **Branchez `onKycRequired`** : l'avis `account.kyc_required` arrive à 80 % du seuil (`reason` `amount_80`), 7 jours avant l'échéance (`deadline_7d`), puis au premier refus (`blocked`). Prévenez le responsable avec le lien `event.kyc().consoleUrl()`, où il dépose sa pièce.
- **Sur `kyc_required`** : proposez la carte, ou dites au client que le paiement mobile money n'est pas disponible pour le moment. Ne réessayez pas.

## Erreurs

- `card_account_not_ready` (409) : paiement par carte demandé sans compte carte actif. Voir « Paiement par carte ».
Expand All @@ -201,6 +211,8 @@ Ce n'est PAS le même parcours que le mobile money. Ne le proposez que si l'util
| `fx_mode_unavailable`, `fx_channel_unavailable` | Mode `converted` pas ouvert : proposer `local` (avec l'accord de l'utilisateur sur le risque) ou rester en `none` |
| `quote_expired` | Le client rechoisit son pays sur la page, rien à faire côté code |
| `reference_conflict` | Même référence, autres valeurs : ne pas réutiliser la référence |
| `kyc_required` | Pièce d'identité à déposer : `e.details().get("consoleUrl")`, `reason` (`amount` ou `duration`). Proposer la carte ; ne pas réessayer |
| `contract_required` | Le responsable doit accepter le contrat dans la console (`e.details().get("version")`) ; ne pas réessayer |
| `payment_in_progress` | Réessayer dans une minute, même appel |
| `payment_not_found`, `refund_not_found` | Mauvais identifiant ou autre compte |
| `payment_expired` | Cette référence est un essai expiré : nouveau paiement avec une NOUVELLE référence, jamais le même appel |
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Journal

## 0.2.0 (15/11/2026)

Seuil d'identité : `getAccountKyc()` (`GET /v1/account/kyc`), avis `account.kyc_required` (`onKycRequired`, `event.kyc()`), précisions `consoleUrl` (`kyc_required`) et `version` (`contract_required`) dans `details()`.

## 0.1.1 (15/11/2026)

Installation par JitPack réparée (Maven épinglé par le wrapper). Aucun changement de code.
Expand Down
11 changes: 8 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ Maven :
<dependency>
<groupId>com.github.Technas-Organization</groupId>
<artifactId>technas-pay-java</artifactId>
<version>v0.1.1</version>
<version>v0.2.0</version>
</dependency>
```

Gradle (Kotlin) :

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

Technas vous remet **un secret**. Mettez-le dans les variables d'environnement du serveur :
Expand Down Expand Up @@ -83,7 +83,7 @@ ResponseEntity<Map<String, Object>> webhook(@RequestBody String raw, //
}
```

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.
Fonctions disponibles : `onCompleted`, `onFailed` (pas définitif), `onExpired` (définitif), `onRefund`, `onTopUp`, `onPayoutDestination`, `onBalanceConverted`, `onFxModeUpdated`, `onCardAccountUpdated`, `onKycRequired`. Une exception dans votre fonction doit remonter : Technas relivrera.

Kotlin :

Expand Down Expand Up @@ -141,6 +141,7 @@ Exemples complets, compilés en CI : [`examples/spring-boot`](examples/spring-bo
| `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 |

Expand All @@ -160,6 +161,10 @@ try {

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

## Seuil d'identité

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()`) 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()`).

## 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.
Expand Down
2 changes: 1 addition & 1 deletion examples/kotlin-spring/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
<dependency>
<groupId>fr.technas</groupId>
<artifactId>technas-pay</artifactId>
<version>0.1.1</version>
<version>0.2.0</version>
</dependency>
</dependencies>
<build>
Expand Down
2 changes: 1 addition & 1 deletion examples/spring-boot/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
<dependency>
<groupId>fr.technas</groupId>
<artifactId>technas-pay</artifactId>
<version>0.1.1</version>
<version>0.2.0</version>
</dependency>
</dependencies>
</project>
2 changes: 1 addition & 1 deletion llms.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# technas-pay-java (Java, Kotlin)

> SDK Java 17+ et Kotlin (côté serveur : Spring Boot, Quarkus, Micronaut, Ktor) pour encaisser du mobile money en Afrique et des paiements par carte via Technas Pay, rembourser et recharger son solde. Une dépendance (jackson-databind). Montant seul, en F CFA : la devise (XOF ou XAF) suit le pays du client. Installation depuis GitHub par JitPack : com.github.Technas-Organization:technas-pay-java:v0.1.1.
> SDK Java 17+ et Kotlin (côté serveur : Spring Boot, Quarkus, Micronaut, Ktor) pour encaisser du mobile money en Afrique et des paiements par carte via Technas Pay, rembourser et recharger son solde. Une dépendance (jackson-databind). Montant seul, en F CFA : la devise (XOF ou XAF) suit le pays du client. Installation depuis GitHub par JitPack : com.github.Technas-Organization:technas-pay-java:v0.2.0.

Agents de code : lisez d'abord AGENTS.md.

Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<modelVersion>4.0.0</modelVersion>
<groupId>fr.technas</groupId>
<artifactId>technas-pay</artifactId>
<version>0.1.1</version>
<version>0.2.0</version>
<name>Technas Pay</name>
<description>Encaisser du mobile money et des paiements par carte via Technas Pay depuis Java ou Kotlin (Spring Boot, Jakarta Servlet).</description>
<url>https://github.com/Technas-Organization/technas-pay-java</url>
Expand Down
15 changes: 13 additions & 2 deletions src/main/java/fr/technas/pay/TechnasPay.java
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import fr.technas.pay.http.JdkTransport;
import fr.technas.pay.http.Transport;
import fr.technas.pay.internal.Json;
import fr.technas.pay.model.AccountKyc;
import fr.technas.pay.model.CardAccount;
import fr.technas.pay.model.CardOnboardingLink;
import fr.technas.pay.model.Customer;
Expand Down Expand Up @@ -49,7 +50,7 @@
* }</pre>
*/
public final class TechnasPay {
public static final String VERSION = "0.1.1";
public static final String VERSION = "0.2.0";
public static final String DEFAULT_BASE_URL = "https://pay-api.technas.fr";
public static final String SECRET_ENV = "TECHNAS_PAY_SECRET";
private static final Pattern SECRET = Pattern.compile("^tps_(live|test)_([\\x21-\\x2d\\x2f-\\x7e]+)\\.([\\x21-\\x2d\\x2f-\\x7e]+)$"); // ASCII imprimable sans « . »
Expand Down Expand Up @@ -152,7 +153,7 @@ private static TechnasPayException fromResponse(int status, JsonNode d) {
details.put(k[1], n);
}
}
for (String[] k : new String[][] {{"currency", "currency"}, {"reason", "reason"}, {"risk", "risk"}, {"account_status", "accountStatus"}}) {
for (String[] k : new String[][] {{"currency", "currency"}, {"reason", "reason"}, {"risk", "risk"}, {"account_status", "accountStatus"}, {"console_url", "consoleUrl"}, {"version", "version"}}) {
String v = Json.nstr(d, k[0]);
if (v != null) {
details.put(k[1], v);
Expand Down Expand Up @@ -442,6 +443,16 @@ public String getCardDashboardLink() {
return Json.str(call("POST", "/v1/card/dashboard-link", Json.object()), "url");
}

// --- Seuil d'identité ----------------------------------------------------------------------

/**
* Où en est le seuil d'identité du compte : encaissé, seuil, échéance, et la console où
* déposer la pièce. Le même état que la console et que l'avis {@code account.kyc_required}.
*/
public AccountKyc getAccountKyc() {
return AccountKyc.fromJson(call("GET", "/v1/account/kyc", null));
}

// --- Avis signés ---------------------------------------------------------------------------

/** Vérifie la signature sur le corps BRUT et rend l'événement. Lève {@link WebhookVerificationException} (répondez 400). */
Expand Down
3 changes: 2 additions & 1 deletion src/main/java/fr/technas/pay/TechnasPayException.java
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,8 @@ public int status() {

/**
* Précisions selon le code : {@code missingAmount} et {@code currency} ({@code insufficient_balance}),
* {@code refundableAmount}, {@code reason}, {@code risk}, {@code accountStatus}.
* {@code refundableAmount}, {@code reason}, {@code risk}, {@code accountStatus}, {@code consoleUrl}
* ({@code kyc_required}), {@code version} ({@code contract_required}).
*/
public Map<String, Object> details() {
return Map.copyOf(details);
Expand Down
37 changes: 37 additions & 0 deletions src/main/java/fr/technas/pay/model/AccountKyc.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
package fr.technas.pay.model;

import com.fasterxml.jackson.databind.JsonNode;
import fr.technas.pay.internal.Json;
import java.math.BigDecimal;

/**
* Le seuil d'identité du compte ({@code GET /v1/account/kyc}). En réel, un compte sans pièce
* vérifiée voit ses NOUVEAUX paiements mobile money refusés ({@code kyc_required}) au-delà de
* {@code thresholdXof} F CFA encaissés ou de {@code graceDays} jours après son premier paiement réel.
* Rien de ce qui existe n'est bloqué ; la carte n'est pas concernée. Montrez-le au MARCHAND,
* jamais au client final. Les chiffres viennent de l'API : ne les écrivez pas en dur.
*
* @param stage {@code ok}, {@code soon} (préavis), {@code blocked}, {@code verified}, {@code not_applicable}
* @param level {@code none}, {@code identity}, {@code business}
* @param reason {@code amount}, {@code duration}, ou {@code null} tant que rien n'est bloqué
* @param consoleUrl où le responsable dépose sa pièce
*/
public record AccountKyc(
boolean applies, String stage, String level, Integer daysElapsed, BigDecimal warnFromXof, String warnFromDate,
BigDecimal collectedXof, BigDecimal thresholdXof, Integer graceDays, String firstCollectedAt, String deadline,
String waiverUntil, boolean blocked, String reason, String consoleUrl) {

public static AccountKyc fromJson(JsonNode r) {
return new AccountKyc(
Json.bool(r, "applies"), Json.str(r, "stage"), Json.str(r, "level"), integer(r, "days_elapsed"),
Json.num(r, "warn_from_xof"), Json.nstr(r, "warn_from_date"), Json.num(r, "collected_xof"),
Json.num(r, "threshold_xof"), integer(r, "grace_days"), Json.nstr(r, "first_collected_at"),
Json.nstr(r, "deadline"), Json.nstr(r, "waiver_until"), Json.bool(r, "blocked"), Json.nstr(r, "reason"),
Json.nstr(r, "console_url"));
}

static Integer integer(JsonNode r, String k) {
BigDecimal v = Json.nnum(r, k);
return v == null ? null : v.intValue();
}
}
20 changes: 20 additions & 0 deletions src/main/java/fr/technas/pay/model/KycNotice.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
package fr.technas.pay.model;

import com.fasterxml.jackson.databind.JsonNode;
import fr.technas.pay.internal.Json;
import java.math.BigDecimal;

/**
* Contenu de l'avis {@code account.kyc_required} : envoyé à 80 % du seuil, 7 jours avant
* l'échéance, puis au premier refus. Prévenez le responsable du compte.
*
* @param reason {@code amount_80}, {@code deadline_7d} ou {@code blocked}
*/
public record KycNotice(String reason, BigDecimal collectedXof, BigDecimal thresholdXof, String deadline, boolean blocked,
String consoleUrl) {

public static KycNotice fromJson(JsonNode r) {
return new KycNotice(Json.str(r, "reason"), Json.num(r, "collected_xof"), Json.num(r, "threshold_xof"),
Json.nstr(r, "deadline"), Json.bool(r, "blocked"), Json.nstr(r, "console_url"));
}
}
7 changes: 5 additions & 2 deletions src/main/java/fr/technas/pay/webhook/Event.java
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import com.fasterxml.jackson.databind.JsonNode;
import fr.technas.pay.internal.Json;
import fr.technas.pay.model.CardAccount;
import fr.technas.pay.model.KycNotice;
import fr.technas.pay.model.Payment;
import fr.technas.pay.model.Refund;
import java.util.Map;
Expand All @@ -13,7 +14,7 @@
* doublon.
*/
public record Event(String id, String type, String createdAt, Map<String, Object> data,
Payment payment, Refund refund, CardAccount cardAccount) {
Payment payment, Refund refund, CardAccount cardAccount, KycNotice kyc) {

static Event parse(JsonNode raw) {
if (raw == null || !raw.isObject() || Json.nstr(raw, "id") == null || Json.nstr(raw, "type") == null
Expand All @@ -25,6 +26,7 @@ static Event parse(JsonNode raw) {
Payment payment = null;
Refund refund = null;
CardAccount card = null;
KycNotice kyc = null;
switch (type) {
case "payment.completed", "payment.failed", "payment.expired" -> {
if (Json.nstr(d, "id") == null) {
Expand All @@ -34,10 +36,11 @@ static Event parse(JsonNode raw) {
}
case "refund.completed", "refund.failed", "refund.recorded" -> refund = Refund.fromJson(d);
case "card_account.updated" -> card = CardAccount.fromJson(d);
case "account.kyc_required" -> kyc = KycNotice.fromJson(d);
default -> {
// payout_destination.*, balance.*, fx_mode.updated, types inconnus : `data`.
}
}
return new Event(Json.str(raw, "id"), type, Json.nstr(raw, "created_at"), Json.map(raw, "data"), payment, refund, card);
return new Event(Json.str(raw, "id"), type, Json.nstr(raw, "created_at"), Json.map(raw, "data"), payment, refund, card, kyc);
}
}
12 changes: 12 additions & 0 deletions src/main/java/fr/technas/pay/webhook/WebhookHandlers.java
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ public final class WebhookHandlers {
private final Consumer<Event> onBalanceConverted;
private final Consumer<Event> onFxModeUpdated;
private final Consumer<Event> onCardAccountUpdated;
private final Consumer<Event> onKycRequired;

private WebhookHandlers(Builder b) {
onCompleted = b.onCompleted;
Expand All @@ -34,6 +35,7 @@ private WebhookHandlers(Builder b) {
onBalanceConverted = b.onBalanceConverted;
onFxModeUpdated = b.onFxModeUpdated;
onCardAccountUpdated = b.onCardAccountUpdated;
onKycRequired = b.onKycRequired;
}

public static Builder builder() {
Expand Down Expand Up @@ -69,6 +71,9 @@ public Consumer<Event> forType(String type) {
if ("card_account.updated".equals(type)) {
return onCardAccountUpdated;
}
if ("account.kyc_required".equals(type)) {
return onKycRequired;
}
return null;
}

Expand All @@ -82,6 +87,7 @@ public static final class Builder {
private Consumer<Event> onBalanceConverted;
private Consumer<Event> onFxModeUpdated;
private Consumer<Event> onCardAccountUpdated;
private Consumer<Event> onKycRequired;

private Builder() {
}
Expand Down Expand Up @@ -136,6 +142,12 @@ public Builder onCardAccountUpdated(Consumer<Event> f) {
return this;
}

/** Seuil d'identité ({@code event.kyc()}) : prévenez le responsable, lien {@code consoleUrl()}. */
public Builder onKycRequired(Consumer<Event> f) {
onKycRequired = f;
return this;
}

public WebhookHandlers build() {
return new WebhookHandlers(this);
}
Expand Down
Loading
Loading