Skip to content

About

Technas Pay : encaisser du mobile money depuis n'importe quel serveur JS (Express, Fastify, NestJS, Hono, Bun, Deno)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

@technas/pay

Encaissez des paiements mobile money et par carte via Technas depuis n'importe quel serveur JavaScript : Express, Fastify, NestJS, Koa, Hono, node:http, Bun, Deno, fonctions serverless. Sous Next.js App Router, @technas/pay-next ajoute ce qu'il faut à ce même cœur.

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, livré dans le paquet avec llms.txt (node_modules/@technas/pay/AGENTS.md).

Autres langages : Python, Dart.

1. Installer

npm install github:Technas-Organization/technas-pay-node#v0.15.0

Le paquet se compile à l'installation, s'importe sous le nom @technas/pay, et n'a aucune dépendance. Node.js 18.17 ou plus récent.

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.

2. Demander un paiement

// lib/pay.js
import { createTechnasPay } from "@technas/pay";

export const pay = createTechnasPay({ secret: process.env.TECHNAS_PAY_SECRET });
import { retryReference } from "@technas/pay";
import { pay } from "./lib/pay.js";

app.post("/orders/:id/pay", async (req, res, next) => {
  try {
    const order = await db.orders.find(req.params.id); // montant calculé côté serveur
    const { id, checkoutUrl } = await pay.askForPayment({
      amount: order.amount,                                  // entier : 5000 = 5 000 FCFA
      reference: retryReference(order.id, order.attempt),    // "42-1" : une référence = un essai
      customer: { email: order.email, name: order.name },
      returnUrl: "https://votre-site.com/merci",
    });
    await db.orders.update(order.id, { paymentId: id });
    res.redirect(303, checkoutUrl);
  } catch (error) {
    next(error);
  }
});

La devise

Donnez seulement le montant, en francs CFA : chaque client paie dans la monnaie de son pays. Le XOF (Afrique de l'Ouest) et le XAF (Afrique centrale) sont à parité fixe, donc le montant ne change pas.

La devise se choisit dans cet ordre :

  1. currency, si vous la passez à l'appel ;
  2. sinon celle du pays du client, customer.country (code ISO à deux lettres) ;
  3. sinon defaultCurrency, passé à createTechnasPay ;
  4. sinon le client choisit son pays sur la page de paiement, qui lui propose ensuite les opérateurs de ce pays. Son numéro (customer.phone, format international) préremplit ce choix.
Pays Devise
Bénin BJ, Burkina Faso BF, Côte d'Ivoire CI, Mali ML, Niger NE, Sénégal SN, Togo TG XOF
Cameroun CM, Congo CG, Gabon GA XAF
Guinée-Bissau GW, Centrafrique CF, Guinée équatoriale GQ, Tchad TD Pas encore d'opérateur ouvert : affichés « bientôt »
  • Votre solde et le webhook suivent la devise réellement payée. Un client camerounais crédite votre solde en XAF, et event.payment.currency vaut "XAF". Il vous faut un numéro de reversement par devise (voir plus bas).
  • Tant que le client n'a pas choisi son pays, payment.currency vaut null.
  • Hors zone franc CFA (Ghana, Nigeria, Kenya…) : voir la section suivante.
  • currencyForCountry("CM") rend "XAF", pour afficher le prix avec la bonne devise.

Choisir où vous vendez

Tout est facultatif. Sans réglage, vos clients de toute la zone franc CFA peuvent payer.

Vous voulez… Faites
Que le client choisisse son pays Rien : sans currency ni pays, la page le lui demande
Fixer le pays vous-même customer: { country: "TG" }
Vendre seulement dans certains pays, pour tout votre compte pay.setCountryRules({ allowed: ["TG", "BJ"] })
Ne pas vendre dans certains pays pay.setCountryRules({ excluded: ["NG"] })
Restreindre un seul paiement allowedCountries: [...] ou excludedCountries: [...] dans askForPayment
Imposer la devise currency: "XAF" : le paiement part directement dans cette devise
Imposer la devise et laisser choisir le pays currency: "XAF", askCountry: true : la page ne propose que les pays du XAF

Un pays refusé donne l'erreur country_not_allowed. Sur la page, il n'apparaît tout simplement pas.

Clients hors zone franc CFA : une option, à vos risques

Vous donnez toujours le montant en francs CFA. Faire payer un client du Ghana, du Nigeria ou du Kenya est une option que vous choisissez vous-même. Technas ne couvre aucun risque de change et prend sa commission sur chaque paiement.

Option Ce que paie le client Ce que vous recevez Votre risque
none (au départ) — : seuls les pays de la zone CFA sont proposés — Aucun
local Votre montant au cours du jour, dans sa monnaie Un solde dans sa monnaie (cedis…), reversé sur votre numéro de reversement dans cette monnaie La valeur de ce solde suit le cours : si la monnaie baisse, vous perdez
converted (pas encore ouvert) Votre montant au cours du jour, dans sa monnaie Un solde dans sa monnaie, puis changé en francs CFA par Technas, plus tard, au cours réellement obtenu et moins le coût réel du change Tout l'écart entre le cours du paiement et le cours du change, plus le coût du change
const fx = await pay.getFxMode();
console.log(fx.risks.local); // le risque, en clair : lisez-le avant d'activer
await pay.setFxMode({ mode: "local", acceptRisk: true, markupPct: 2 });
  • Options ouvertes aujourd'hui : none et local (fx.availableModes). converted est refusé (fx_mode_unavailable) tant que Technas n'a aucune filière de change : rien n'est promis qui ne soit prêt.
  • Le cours : lu chaque jour sur ExchangeRate-API et vérifié contre une seconde source ; si elles diffèrent de plus de 2 %, la monnaie est fermée le temps de comprendre. Un cours vaut 24 h (72 h s'il a été publié un vendredi ou le week-end). Technas ne prend aucune marge de change.
  • Accepter le risque : sans acceptRisk: true, l'activation est refusée (risk_not_accepted) et l'erreur rend le texte du risque.
  • Supplément de change (markupPct, de 0 à 20 %, facultatif) : il est payé par le client, affiché avant qu'il paie, et vous revient. Il peut vous protéger d'une baisse du cours.
  • Pays ouverts : un pays n'apparaît que si tout est prêt. Sinon, getFxMode() dit ce qui manque (reason) :
    • no_payout_number : en local, il faut un numéro de reversement confirmé dans la monnaie de ce pays ; en converted, un numéro en francs CFA. Sans lui, votre argent n'aurait nulle part où aller ;
    • no_fresh_rate : pas de cours frais (24 h, 72 h le week-end), ou les deux sources de cours ne concordent pas ;
    • no_operator : pas d'opérateur ouvert dans ce pays ;
    • no_fx_channel : personne ne sait encore changer cette monnaie. Le mode converted ne s'active pas tant qu'il n'existe aucune filière de change.
  • Ce que voit le client : avant de payer, la page lui montre le montant exact dans sa monnaie, le cours, votre supplément et la source du cours. Le montant est garanti 30 minutes.
  • Dans le webhook :
    • event.payment.amount et event.payment.currency : ce que le client a payé (121.96 GHS) ;
    • event.payment.originalAmount : votre montant en francs CFA ;
    • event.payment.fx : le cours, le supplément et la source.
  • Mode converted : chaque change vous est annoncé par onBalanceConverted, avec le cours réellement obtenu et le coût retiré.
  • Sécurité : chaque changement d'option vous est annoncé par onFxModeUpdated. Si ce n'est pas vous, prévenez Technas.
  • Montants à centimes : hors zone, un montant peut avoir des centimes (cedis…). Ne l'arrondissez pas.

Pour une app mobile : les routes toutes faites

Votre app Flutter (technas_pay_flutter) appelle ces routes sans aucune glue. Vous ne fournissez que votre authentification et la lecture de la commande en base :

const routes = pay.appRoutes({
  authorize: (req) => verifierSession(req.headers.authorization), // votre utilisateur, ou null → 401
  resolveOrder: async (orderId, user) => {                         // relue EN BASE, null → 404
    const o = await db.orders.find({ id: orderId, userId: user.id });
    return o && { amount: o.total, customer: { email: user.email, name: user.name } };
  },
  returnUrl: "https://votre-app.com/paiement/retour",
  webhooks: { onCompleted: (e) => db.orders.markPaid(e.payment.reference) },
});
app.use("/api/technas-pay", routes.node);                          // Express / Nest, AVANT express.json()
// Next.js, app/api/technas-pay/[...path]/route.ts :
// export const { GET, POST } = routes.nextHandlers("/api/technas-pay");

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

Carte dans l'app : ajoutez card: true et, pour l'écran d'administration du marchand, authorizeAdmin: (req) => adminOuNull(req). /methods n'ouvre la carte que si le compte carte est prêt et que resolveOrder rend une currency. Le marchand dispose alors de GET /card/account et POST /card/onboarding ({country, returnUrl, refreshUrl}). Les essais expirés sont sautés tout seuls (42-1, 42-2…) : rien à stocker. Un essai d'un autre montant (le client a changé d'offre) est relu, annulé s'il est encore ouvert, puis le suivant est créé ; s'il vient d'être payé (payment_already_completed) ou qu'une demande est en cours chez l'opérateur (payment_in_progress), aucun second paiement n'est créé et l'erreur (409) est rendue à l'app. Contrat : contract/app-contract.v1.json, rejoué par ce paquet et par le client Flutter.

Paiement par carte bancaire

Le mobile money arrive sur votre solde Technas, reversé ensuite sur votre numéro. La carte suit un autre chemin : vous avez votre propre compte carte, le client le paie directement, et la commission Technas est retirée au passage. Technas ne détient pas cet argent : il n'apparaît pas dans getBalance().

1. Ouvrir le compte carte, une seule fois. C'est le responsable du compte qui le fait, depuis vos réglages :

// app/reglages/carte/actions.ts
"use server";
import { redirect } from "next/navigation";
import { pay } from "@/lib/pay";

export async function activerLaCarte() {
  const { url } = await pay.startCardOnboarding({
    country: "FR", // VOTRE pays, pas celui de vos clients
    returnUrl: "https://votre-site.com/reglages/carte?fin=1",
    refreshUrl: "https://votre-site.com/reglages/carte?relance=1", // lien expiré : rappelez activerLaCarte
  });
  redirect(url); // page sécurisée du partenaire carte : identité et banque ; Technas ne voit pas l'IBAN
}

Le responsable s'inscrit sur la page sécurisée de notre partenaire carte (Stripe), qui vous fera accepter son contrat.

Ensuite, await pay.getCardAccount() dit où il en est :

status Ce que ça veut dire
not_started Jamais ouvert
onboarding Inscription commencée, pas finie : rappelez startCardOnboarding
under_review Tout est donné, vérification en cours
restricted Il manque quelque chose (requirements) ou le compte est suspendu (disabledReason)
enabled La carte est ouverte (canAcceptPayments: true)

Le webhook onCardAccountUpdated vous prévient de chaque changement. Une fois l'inscription finie, getCardDashboardLink() rend l'adresse du tableau de bord de votre compte carte : le responsable s'y connecte avec SES identifiants du compte carte, choisis à l'inscription, pour régler ses virements et suivre ses litiges. Ce n'est pas un lien à usage unique.

2. Faire payer par carte, seulement si canAcceptPayments est vrai :

const { checkoutUrl } = await pay.askForPayment({
  method: "card",
  amount: 49.9, // 49,90 € : les décimales sont permises par carte
  currency: "EUR", // obligatoire par carte
  reference: commandeId,
  customer: { email, name },
  returnUrl: "https://votre-site.com/merci",
});
redirect(checkoutUrl);

Tout le reste ne change pas : webhook onCompleted, une référence = un essai, payment.expired au bout d'une heure, refund pour rembourser (sur la carte, depuis votre compte carte ; la commission n'est pas rendue). Sans compte prêt, l'appel lève card_account_not_ready (409) : proposez alors le mobile money.

En mode test, payez avec la carte 4242 4242 4242 4242, une date future et n'importe quel code.

3. Recevoir la confirmation

Technas signe chaque webhook (X-Technas-Payment-Signature: t=…,s=…). Le SDK vérifie la signature sur le corps brut, puis appelle la bonne fonction. Choisissez la forme qui va avec votre framework :

// Express : AVANT app.use(express.json())
app.post(
  "/api/technas-pay",
  express.raw({ type: "application/json" }),
  pay.nodeHandler({
    async onCompleted(event) {
      await db.orders.markPaid(event.payment.reference); // idempotent
    },
    async onExpired(event) {
      await db.orders.nextAttempt(event.payment.reference); // seul moment où relancer
    },
  }),
);
// NestJS : NestFactory.create(AppModule, { rawBody: true })
const technasWebhook = pay.nodeHandler({ onCompleted, onExpired });

@Controller("api/technas-pay")
export class TechnasPayController {
  @Post() hook(@Req() req, @Res() res) {
    return technasWebhook(req, res);
  }
}
// Fastify : garder le corps brut dans un scope dédié
app.register(async (scope) => {
  scope.addContentTypeParser("application/json", { parseAs: "string" }, (_r, body, done) => done(null, body));
  scope.post("/api/technas-pay", async (request, reply) => {
    const r = await pay.handleWebhook(request.body, request.headers["x-technas-payment-signature"], { onCompleted });
    return reply.code(r.status).send(r.body);
  });
});
// Hono, Bun, Deno, Remix… (norme fetch : Request → Response)
app.post("/api/technas-pay", (c) => pay.webhookHandler({ onCompleted })(c.req.raw));

Exemples complets, testés : Express, Fastify.

Fonctions disponibles : onCompleted, onFailed (pas définitif), onExpired (définitif), onRefund, onTopUp, onSettlement (reversement arrivé ou échoué), onPayoutDestination, onBalanceConverted, onFxModeUpdated, onCardAccountUpdated, onKycRequired (seuil d'identité, voir plus bas). Signature refusée : réponse 400, aucune fonction appelée. Une erreur dans votre fonction remonte (500, ou next(error) sous Express) : Technas relivrera. Un type inconnu est acquitté.

La règle de relance

Relancez avec une NOUVELLE référence seulement après payment.expired (ou getPayment → expired), jamais sur failed.

Statut Définitif ? Que faire
pending Non Attendre
failed Non Rien : le client peut réessayer sur la même page pendant une heure, et onCompleted arriver ensuite
completed Oui Livrer
expired Oui Relancer le client, avec une nouvelle référence
amount_mismatch Oui Rien n'est crédité ; contacter Technas
  • Le lien vit une heure (payment.expiresAt). Ensuite Technas vérifie chez l'opérateur que la page est fermée et qu'aucune transaction n'a réussi ni n'est en cours, puis passe le paiement en expired et envoie payment.expired. Comptez quelques minutes après expiresAt.
  • canRetry(payment) vaut true seulement pour expired ; isFinal(payment) dit si le statut ne changera plus (failed : jamais final).
  • Une référence = un essai. Rejouer la référence d'un paiement expiré est refusé : TechnasPayError payment_expired (409), qui dit de créer un nouveau paiement avec une NOUVELLE référence. Changez-la (par exemple CMD-42-2) et gardez le nouveau payment.id.
  • checkoutUrl est la page Technas : elle mène à l'opérateur tant que le lien est payable et affiche « Lien expiré » ensuite. Un paiement expired a checkoutUrl: null.
  • Un paiement expired ne sera jamais crédité. Si, par un cas qui ne devrait pas arriver, de l'argent arrivait après coup, Technas le rend au payeur et vous prévient.
import { canRetry } from "@technas/pay";

const p = await pay.getPaymentByReference(commande.referencePaiement);
if (canRetry(p)) {
  const nouvelle = `${commande.id}-${commande.tentatives + 1}`;
  const { checkoutUrl } = await pay.askForPayment({ ...demande, reference: nouvelle });
}

Le client change d'offre ou revient plus tard

Une référence = un essai : une autre offre, ou un retour après expiration, c'est un NOUVEL essai avec retryReference(factureId, n + 1). Réutiliser la référence d'un autre montant lève reference_conflict (409), celle d'un essai expiré payment_expired (409) ; les routes toutes faites le font seules. Un essai pending ou failed ne bloque jamais un nouvel essai demandé par le client : même offre, renvoyez-le sur la même page ; autre offre, ANNULEZ l'ancien essai (cancelPayment), puis créez le nouveau avec une NOUVELLE référence. Si l'annulation répond payment_in_progress (demande en cours chez l'opérateur), ne créez PAS de second paiement : attendez l'avis de l'issue. payment_already_completed : le client a payé l'ancienne offre, relisez le paiement et ne créez rien. Un paiement annulé reste expired (canRetry vaut true), avec canceledAt ; son avis payment.expired porte reason = canceled (timeout pour un lien expiré). La facture n'est payée que sur payment.completed (jamais sur returnUrl). Au retour du client, relisez le dernier essai avec getPayment avant de répondre. Si le client a payé deux pages, n'activez rien deux fois et remboursez l'essai en trop avec refund.

import { retryReference } from "@technas/pay";

// Au clic « Payer » : la facture et l'offre choisie (son montant).
async function payer(facture, montant, customer) {
  if (facture.dernierPaymentId) {
    const dernier = await pay.getPayment(facture.dernierPaymentId); // Technas, pas seulement la base
    if (dernier.status === "completed") return { dejaPayee: true };
    const memeOffre = dernier.amount === montant;
    if (memeOffre && dernier.status !== "expired" && dernier.checkoutUrl) {
      return { checkoutUrl: dernier.checkoutUrl }; // pending ou failed : même page, le client peut encore payer
    }
    if (dernier.status !== "expired") {
      // Autre offre : l'ancien lien est fermé d'abord. payment_in_progress (demande en cours chez
      // l'opérateur) et payment_already_completed (il vient d'être payé) remontent : on ne crée
      // alors AUCUN second paiement.
      await pay.cancelPayment(dernier.id);
    }
  }
  // Ancien essai annulé ou expiré : un NOUVEL essai, avec une nouvelle référence.
  const n = facture.essais + 1;
  const p = await pay.askForPayment({
    amount: montant,
    reference: retryReference(facture.id, n),
    customer,
    returnUrl: `https://exemple.tg/factures/${facture.id}`,
    metadata: { facture_id: facture.id },
  });
  await db.factures.update(facture.id, { essais: n, dernierPaymentId: p.id });
  return { checkoutUrl: p.checkoutUrl };
}

// Webhook : la facture n'est payée QU'ici.
async function onCompleted(event) {
  const facture = await db.factures.get(event.payment.metadata.facture_id);
  if (facture.payeePar && facture.payeePar !== event.payment.id) {
    await pay.refund(event.payment.id); // l'autre page a aussi été payée : rembourser celle-ci
    return;
  }
  await db.factures.update(facture.id, { payeePar: event.payment.id, montantPaye: event.payment.amount });
}

4. Rembourser

L'argent repart au numéro qui a payé, par mobile money. C'est vous qui prévenez votre client : Technas ne lui écrit pas.

const remboursement = await pay.refund(paymentId);                        // tout ce qui reste
const partiel = await pay.refund(paymentId, { amount: 2000 });           // une partie
const net = await pay.refund(paymentId, { amount: 2000, fees: "customer" }); // frais retirés au client

Règles

  • Paiement concerné : seul un paiement completed de votre compte se rembourse.

  • Plafond : le total remboursé ne dépasse jamais le montant payé. Sans amount, vous remboursez tout ce qui reste.

  • Commission : la commission Technas n'est pas rendue.

  • Frais du renvoi, choisis par fees à chaque appel :

    fees Le client reçoit (sentAmount) Votre solde perd (balanceDebit)
    "partner" (défaut) amount amount + frais
    "customer" amount − frais amount
  • Débit du solde : votre solde est débité tout de suite. Si le renvoi échoue (refund.failed), il est recrédité, et vous pouvez refaire le même appel.

  • Idempotence : rejouer le même appel ne rembourse pas deux fois. Pour deux remboursements partiels identiques et voulus, donnez à chacun une reference, par exemple l'identifiant de votre décision.

  • Solde insuffisant : l'appel échoue avec insufficient_balance, sans rien envoyer. error.details.missingAmount dit combien il manque. Rechargez avec pay.topUpBalance({ amount, currency }) : c'est un paiement mobile money sans commission, confirmé par le webhook balance.topped_up. Ensuite, rappelez refund.

Remboursement fait hors Technas

Vous avez rendu l'argent vous-même, par Flooz, T-Money ou en espèces ? Enregistrez-le :

await pay.recordExternalRefund(paymentId, {
  amount: 2000,
  method: "Flooz",                  // obligatoire : "T-Money", "Espèces", "Virement"…
  note: "Article abîmé, geste du SAV", // facultatif
  recordedBy: "caisse@exemple.tg",    // facultatif : qui l'a fait
});
  • Aucun mouvement : aucun argent ne part, votre solde ne change pas.
  • Plafond commun : il compte dans le plafond. Avec les remboursements de refund, le total ne dépasse jamais le montant payé.
  • Idempotence : rejouer le même appel n'enregistre pas deux fois. Pour deux enregistrements identiques, donnez à chacun une reference.
  • Webhook : refund.recorded, reçu dans onRefund.
  • Sur le paiement : payment.refundedAmount additionne tout ce qui a été remboursé, par Technas ou hors Technas.

Exemple de back-office

La décision → pay.refund → le résultat immédiat ou le webhook → le message au client.

// admin/remboursements.ts — réservé aux administrateurs
import { TechnasPayError } from "@technas/pay";
import { pay } from "./lib/pay.js";

export async function rembourser(decisionId: string) {
  const decision = await db.decision.findUniqueOrThrow({ where: { id: decisionId }, include: { commande: true } });
  try {
    const r = await pay.refund(decision.commande.technasPaymentId, {
      amount: decision.montant,  // absent : tout ce qui reste
      fees: decision.fraisAuClient ? "customer" : "partner",
      reference: decision.id,    // rejouer cette décision ne rembourse pas deux fois
    });
    await db.decision.update({ where: { id: decisionId }, data: { refundId: r.id, statut: r.status } });
    if (r.status === "completed") await prevenirClient(decision, r.sentAmount, r.currency);
    // "pending" : le résultat arrive dans onRefund, ci-dessous.
    return { ok: true, statut: r.status };
  } catch (e) {
    if (e instanceof TechnasPayError && e.code === "insufficient_balance") {
      const recharge = await pay.topUpBalance({ amount: e.details.missingAmount!, currency: e.details.currency! });
      return { ok: false, rechargerIci: recharge.checkoutUrl }; // payez, puis relancez la décision
    }
    if (e instanceof TechnasPayError && e.retryable) return { ok: false, reessayer: true };
    throw e;
  }
}
// route webhook (Express)
app.post("/api/technas-pay", express.raw({ type: "application/json" }), pay.nodeHandler({
  onCompleted: async (event) => { /* … */ },
  onRefund: async (event) => {
    const decision = await db.decision.findUnique({ where: { refundId: event.refund.id } });
    if (!decision || decision.statut === event.refund.status) return; // doublon
    await db.decision.update({ where: { id: decision.id }, data: { statut: event.refund.status } });
    if (event.type === "refund.completed") {
      await prevenirClient(decision, event.refund.sentAmount, event.refund.currency);
    } else {
      await alerterAdministrateur(decision, event.refund.failure); // solde déjà recrédité
    }
  },
  onTopUp: async (event) => {
    await noterRecharge(event.topUp.amount, event.topUp.currency);
  },
  onSettlement: async (event) => {
    // completed : netAmount est arrivé sur votre numéro. failed : amount est revenu sur votre solde.
    await noterReversement(event.type, event.settlement.netAmount, event.settlement.currency);
  },
}));

Gardez payment.id (rendu par askForPayment et présent dans event.payment.id) sur votre commande : c'est lui que refund attend. À défaut, pay.getPaymentByReference(reference) le retrouve.

Erreurs propres au remboursement

error.code Que faire
payment_not_refundable Seul un paiement completed se rembourse
refund_exceeds_payment Rembourser au plus error.details.refundableAmount
refund_conflict Cette reference a déjà servi avec d'autres valeurs
insufficient_balance Recharger error.details.missingAmount avec topUpBalance, puis rappeler
payer_unknown Paiement encaissé avant l'arrivée des remboursements : rembourser autrement, prévenir Technas
refund_network_unavailable Le réseau du client ne reçoit plus de versement : rembourser autrement

En test (tps_test_), un remboursement est terminé aussitôt, avec des frais réalistes, et aucun argent ne part.

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, 409) au-delà de 1 000 000 F CFA encaissés en cumul, ou 30 jours après son premier paiement réel encaissé. Rien de ce qui existe n'est bloqué : paiement en cours, remboursement, reversement, lecture. La carte n'est pas concernée. Le responsable du compte dépose sa pièce dans la console.

const kyc = await pay.getAccountKyc();
// { stage: "soon", collectedXof: 812500, thresholdXof: 1000000, graceDays: 30, deadline: "…", reason: "amount", consoleUrl: "https://…" }
  • stage : ok, soon (seuil proche), blocked, verified, not_applicable (applies faux). Une valeur que cette version ne connaît pas est rendue telle quelle.
  • À montrer au marchand (son tableau de bord), jamais au client final.
  • L'avis account.kyc_required arrive dans onKycRequired à 80 % du seuil, 7 jours avant l'échéance, puis au premier refus : event.kyc porte reason (amount_80, deadline_7d, blocked), collectedXof, thresholdXof, deadline, blocked et consoleUrl, puis l'état de getAccountKyc() au moment de l'avis : stage, blockReason (amount, duration), daysElapsed, graceDays, firstCollectedAt (null sur un avis plus ancien). Prévenez le responsable.
  • Sur kyc_required : ne réessayez pas. Proposez la carte, ou expliquez au client que le paiement mobile money n'est pas disponible pour le moment. error.details.consoleUrl et error.details.reason (amount ou duration) disent où et pourquoi.
  • Les chiffres (1 000 000, 30) viennent de l'API (thresholdXof, graceDays) : ne les écrivez pas en dur.

Erreurs liées au compte

error.code Que faire
kyc_required (409) Pièce d'identité à vérifier : ne pas réessayer ; le responsable la dépose sur error.details.consoleUrl (error.details.reason : amount ou duration)
contract_required (409) Le responsable accepte le contrat error.details.version dans la console (error.details.consoleUrl) ; ne pas réessayer

À savoir

  • Seul le webhook prouve le paiement. Un visiteur peut ouvrir returnUrl à la main : n'y livrez rien.
  • Un même événement peut arriver plusieurs fois. Technas relivre tant que votre route ne répond pas 2xx, pendant environ 3 jours. event.id permet d'ignorer un doublon.
  • Un refus n'est pas définitif. Le client peut réessayer sur la même page, et onCompleted arriver après onFailed. Seul expired l'est (voir « La règle de relance »).
  • Retour au site sur succès seulement. Après un refus ou un abandon, le client reste sur la page de paiement.
  • Une référence = un essai. Relancer askForPayment avec la même référence rend le même essai (utile après une coupure). Pour une nouvelle tentative (après payment.expired, ou quand le client change d'offre), utilisez une NOUVELLE référence ; l'ancienne lève payment_expired (essai expiré) ou reference_conflict (autre montant). Autre offre : cancelPayment sur l'ancien essai d'abord ; payment_already_completed (409) dit qu'il est payé, ne créez rien.
  • Reprise. Si error.retryable est vrai, refaites le même appel avec la même référence.

Autres fonctions

Fonction Rôle
pay.getPayment(id) État d'un paiement
pay.getPaymentByReference(reference) Rattraper un webhook manqué
pay.cancelPayment(id) Annuler un paiement que personne n'a commencé à payer (le client change d'offre) : rendu expired, sans lien ; payment_already_completed ou payment_in_progress (409) sinon
pay.refund(paymentId, { amount?, fees?, reference? }) / pay.getRefund(id) Rembourser au numéro qui a payé (voir plus haut)
pay.recordExternalRefund(paymentId, { amount, method, note?, recordedBy? }) Enregistrer un remboursement fait hors Technas
pay.topUpBalance({ amount, currency }) Recharger votre solde, sans commission
pay.getFxMode() / pay.setFxMode({ mode, acceptRisk, markupPct? }) Votre option hors zone CFA, ses risques, les pays ouverts
pay.setCountryRules({ allowed?, excluded? }) Les pays où vous vendez
pay.startCardOnboarding({ country, returnUrl, refreshUrl }) Ouvrir ou finir votre compte carte (voir « Paiement par carte bancaire »)
pay.getCardAccount() / pay.getCardDashboardLink() État de votre compte carte / son tableau de bord
pay.getAccountKyc() Votre seuil d'identité : état, cumul, seuil, échéance, lien de la console (voir « Seuil d'identité »)
pay.getBalance() Votre solde : ce que Technas vous doit, par devise, après commission
pay.listTransactions({ limit, status, cursor }) L'historique de vos paiements, par pages
pay.getSettlements() Vos reversements : amount quitte votre solde, fee (frais mobile money, à votre charge) en est déduit
pay.getPayoutNetworks(pays) Les réseaux mobile money qui acceptent un reversement dans ce pays
pay.getPayoutDestination() / pay.setPayoutDestination({...}) Votre numéro de reversement (voir ci-dessous)
pay.verifyWebhook(corpsBrut, signature) Vérifier un webhook sans appeler vos fonctions
pay.handleWebhook(corpsBrut, signature, fonctions) Vérifier et dispatcher, pour tout framework : rend { status, body }
pay.nodeHandler(fonctions) / pay.webhookHandler(fonctions) Route prête : style Node (req, res, next) / norme fetch (Request → Response)
pay.createTestWebhookPayload(type, paiement) / pay.createTestWebhook(...) Webhook signé pour vos tests, { body, headers } ou Request (secret tps_test_ seulement)
retryReference(orderId, tentative) Compose la référence d'un essai : "42-2"
pay.simulateTestPayment(id, "completed" | "failed" | "expired") Mode test : jouer le payeur sans navigateur ; le vrai webhook part ensuite
canRetry(paiement) / isFinal(paiement) Relance permise (expired seulement) / statut qui ne changera plus

Votre numéro de reversement

C'est vous qui le fixez, depuis votre serveur, un par devise :

const reseaux = await pay.getPayoutNetworks("TG"); // [{ code: "moov_tg", name: "Moov Money Togo", currency: "XOF" }, …]
await pay.setPayoutDestination({ country: "TG", network: "moov_tg", phone: "+22890000000", beneficiaryName: "Ma Société SARL" });
  • Rien ne change avant la confirmation : le responsable de votre compte (adresse e-mail déclarée à Technas) reçoit un lien, valable 24 h. Une clé d'API volée ne suffit donc pas à détourner vos reversements.
  • Le premier numéro d'une devise est actif dès le clic. Un changement l'est 48 h après ; il vous est annoncé par un webhook payout_destination.change_scheduled, reçu par onPayoutDestination.
  • Reposer le numéro actif annule un changement en attente. Un réseau qui n'accepte pas de reversement dans ce pays est refusé (invalid_payout_network).
  • pay.getPayoutDestination() rend vos numéros par devise et leur état (awaiting_confirmation, scheduled, active).

Technas reverse votre solde chaque semaine dès qu'il atteint 10 000 dans la devise ; les frais du versement mobile money sont déduits de ce qui part. Tant qu'une devise n'a pas de numéro confirmé, son argent attend sur votre solde.

Obtenir un secret

Demandez-le à votre contact Technas : un secret de test pour intégrer, puis un secret réel avec vos conditions commerciales. Pour recevoir les webhooks en test, donnez-lui une adresse joignable depuis internet, par exemple un tunnel vers votre poste.

Licence

MIT. Le package est libre ; l'accès au service de paiement dépend de votre contrat avec Technas.

About

Technas Pay : encaisser du mobile money depuis n'importe quel serveur JS (Express, Fastify, NestJS, Hono, Bun, Deno)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages