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.
npm install github:Technas-Organization/technas-pay-node#v0.15.0Le 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.
// 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);
}
});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 :
currency, si vous la passez à l'appel ;- sinon celle du pays du client,
customer.country(code ISO à deux lettres) ; - sinon
defaultCurrency, passé àcreateTechnasPay; - 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.currencyvaut"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.currencyvautnull. - Hors zone franc CFA (Ghana, Nigeria, Kenya…) : voir la section suivante.
currencyForCountry("CM")rend"XAF", pour afficher le prix avec la bonne devise.
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.
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 :
noneetlocal(fx.availableModes).convertedest 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: enlocal, il faut un numéro de reversement confirmé dans la monnaie de ce pays ; enconverted, 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 modeconvertedne 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.amountetevent.payment.currency: ce que le client a payé (121.96GHS) ;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é paronBalanceConverted, 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.
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.
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.
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é.
Relancez avec une NOUVELLE référence seulement après
payment.expired(ougetPayment→expired), jamais surfailed.
| 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 enexpiredet envoiepayment.expired. Comptez quelques minutes aprèsexpiresAt. canRetry(payment)vauttrueseulement pourexpired;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é :
TechnasPayErrorpayment_expired(409), qui dit de créer un nouveau paiement avec une NOUVELLE référence. Changez-la (par exempleCMD-42-2) et gardez le nouveaupayment.id. checkoutUrlest la page Technas : elle mène à l'opérateur tant que le lien est payable et affiche « Lien expiré » ensuite. Un paiementexpiredacheckoutUrl: null.- Un paiement
expiredne 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 });
}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 });
}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-
Paiement concerné : seul un paiement
completedde 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 :feesLe client reçoit ( sentAmount)Votre solde perd ( balanceDebit)"partner"(défaut)amountamount+ frais"customer"amount− fraisamount -
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.missingAmountdit combien il manque. Rechargez avecpay.topUpBalance({ amount, currency }): c'est un paiement mobile money sans commission, confirmé par le webhookbalance.topped_up. Ensuite, rappelezrefund.
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 dansonRefund. - Sur le paiement :
payment.refundedAmountadditionne tout ce qui a été remboursé, par Technas ou hors Technas.
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.
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.
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(appliesfaux). 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_requiredarrive dansonKycRequiredà 80 % du seuil, 7 jours avant l'échéance, puis au premier refus :event.kycportereason(amount_80,deadline_7d,blocked),collectedXof,thresholdXof,deadline,blockedetconsoleUrl, puis l'état degetAccountKyc()au moment de l'avis :stage,blockReason(amount,duration),daysElapsed,graceDays,firstCollectedAt(nullsur 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.consoleUrleterror.details.reason(amountouduration) disent où et pourquoi. - Les chiffres (1 000 000, 30) viennent de l'API (
thresholdXof,graceDays) : ne les écrivez pas en dur.
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 |
- 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.idpermet d'ignorer un doublon. - Un refus n'est pas définitif. Le client peut réessayer sur la même page, et
onCompletedarriver aprèsonFailed. Seulexpiredl'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
askForPaymentavec la même référence rend le même essai (utile après une coupure). Pour une nouvelle tentative (aprèspayment.expired, ou quand le client change d'offre), utilisez une NOUVELLE référence ; l'ancienne lèvepayment_expired(essai expiré) oureference_conflict(autre montant). Autre offre :cancelPaymentsur l'ancien essai d'abord ;payment_already_completed(409) dit qu'il est payé, ne créez rien. - Reprise. Si
error.retryableest vrai, refaites le même appel avec la même référence.
| 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 |
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 paronPayoutDestination. - 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.
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.
MIT. Le package est libre ; l'accès au service de paiement dépend de votre contrat avec Technas.