Encaissez des paiements mobile money et par carte via Technas depuis un serveur PHP : Laravel, Symfony, Slim, ou PHP 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.
Une boutique WordPress / WooCommerce ? L'extension technas-pay-woocommerce s'installe sans développeur.
C'est la même API que les SDK Node, Python et Dart.
PHP 8.1 ou plus récent, extension curl. Aucune autre dépendance.
composer config repositories.technas-pay vcs https://github.com/Technas-Organization/technas-pay-php
composer require technas/pay:^0.5.0Technas 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.
use TechnasPay\Status;
use TechnasPay\TechnasPay;
$pay = new TechnasPay(); // lit TECHNAS_PAY_SECRET au premier appel
$payment = $pay->askForPayment([
'amount' => 5000, // entier : 5 000 FCFA
'reference' => Status::retryReference($order->id, $order->attempt), // "42-1" : une référence = un essai
'customer' => ['email' => 'client@exemple.com', 'name' => 'Awa Mensah'],
'returnUrl' => 'https://votre-site.com/merci',
]);
$order->update(['payment_id' => $payment->id]);
header('Location: ' . $payment->checkoutUrl, true, 303);Calculez le montant côté serveur. Ne passez pas currency si vous vendez en francs CFA : la devise suit le pays du client (customer.country), ou le client choisit son pays sur la page. Par carte : 'method' => 'card', une currency (EUR, XOF…), décimales permises.
Technas signe chaque avis (X-Technas-Payment-Signature: t=…,s=…). Le SDK vérifie la signature sur le corps brut, puis appelle votre fonction.
use TechnasPay\Webhook\Event;
use TechnasPay\Webhook\WebhookHandlers;
$result = $pay->handleWebhook(
file_get_contents('php://input'), // Laravel/Symfony : $request->getContent()
$_SERVER['HTTP_X_TECHNAS_PAYMENT_SIGNATURE'] ?? null,
new WebhookHandlers(
onCompleted: fn (Event $e) => marquerPayee($e->payment->reference), // idempotent
onExpired: fn (Event $e) => essaiSuivant($e->payment->reference), // seul moment où relancer
),
);
http_response_code($result['status']); // 400 si la signature est refusée
echo json_encode($result['body']);Fonctions disponibles : onCompleted, onFailed (pas définitif), onExpired (définitif), onRefund, onTopUp, onPayoutDestination, onBalanceConverted, onFxModeUpdated, onCardAccountUpdated, onKycRequired (seuil d'identité, voir plus bas), onSettlement (reversement de votre solde vers votre numéro mobile money : settlement.completed ou settlement.failed, contenu dans $e->settlement). Une exception dans votre fonction doit remonter : Technas relivrera. Exemples : examples/.
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 (Laravel ici) :
Route::any('technas-pay/{path}', fn (Request $request, string $path) => SymfonyBridge::handle(
(new TechnasPay())->appRoutes(
authorize: fn () => auth('sanctum')->user(), // null → 401
resolveOrder: fn (string $id, $user) => ($o = $user->orders()->find($id)) // relue EN BASE, null → 404
? ['amount' => $o->total, 'customer' => ['email' => $user->email, 'name' => $user->name]] : null,
returnUrl: 'https://votre-app.com/paiement/retour',
webhooks: new WebhookHandlers(onCompleted: fn (Event $e) => Order::markPaid($e->payment->metadata['order_id'])),
),
$request,
$path,
))->where('path', '.*');Symfony : SymfonyBridge::handle($routes, $request, $path) dans un contrôleur (examples/symfony-controller.php). Slim, Mezzio : new Psr15Handler($routes, $psr17, $psr17, '/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). Les essais expirés sont sautés tout seuls (42-1, 42-2…) : rien à stocker. Carte : card: true, et 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.
| 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, amount: ?, fees: 'partner'|'customer', reference: ?) |
Rembourser au numéro ou à la carte qui a payé |
recordExternalRefund($paymentId, $amount, $method) |
Noter un remboursement fait hors Technas |
getRefund($id) |
Statut d'un remboursement |
topUpBalance($amount, $currency) |
Recharger le solde (ouvrir checkoutUrl) |
getBalance(), getSettlements() |
Solde par devise, reversements |
getFxMode(), setFxMode($mode, acceptRisk:) |
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 (puis le tableau de bord de votre compte carte) |
getAccountKyc() |
Seuil d'identité du compte (à montrer au marchand) |
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([...]);
} catch (TechnasPayException $e) {
if ($e->errorCode === 'payment_expired') { $order->increment('attempt'); } // nouvelle référence
elseif ($e->retryable()) { /* refaire le même appel */ }
else { throw $e; }
}kyc_required(409) : seuil d'identité atteint, nouveaux paiements mobile money refusés.$e->details['consoleUrl']et$e->details['reason'](amountouduration). Proposez la carte ou dites au client que le mobile money n'est pas disponible pour le moment ; ne réessayez pas.contract_required(409) : un contrat est à accepter dans la console.$e->details['consoleUrl']et$e->details['version']. Ne réessayez pas.
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à 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 (consoleUrl).
$kyc = $pay->getAccountKyc(); // à montrer au marchand, jamais au client final
// $kyc->stage : ok | soon | blocked | verified | not_applicable
// $kyc->collectedXof, $kyc->thresholdXof, $kyc->graceDays, $kyc->deadline, $kyc->consoleUrlLes chiffres viennent de l'API : ne les écrivez jamais en dur. L'avis account.kyc_required (onKycRequired, contenu dans $e->kycRequired) arrive à 80 % du seuil, 7 jours avant l'échéance, puis au premier refus : prévenez le responsable. Il porte aussi, quand l'API les envoie, stage, blockReason (amount ou duration), daysElapsed, graceDays et firstCollectedAt (null sur un avis plus ancien). Sur l'erreur 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.
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 change d'offre ou revient plus tard ? Un essai non payé ne bloque jamais un nouvel essai : nouvelle offre, ou essai expiré, c'est un nouvel essai avec une nouvelle référence (Status::retryReference($factureId, $n + 1), $n gardé en base). Autre offre : ANNULEZ d'abord l'ancien essai (cancelPayment), puis créez le nouveau. Si l'annulation répond payment_in_progress (une demande est 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-la et ne créez rien. Un paiement annulé reste expired (canceledAt, cancelReason) ; son avis payment.expired porte reason = canceled (timeout pour une échéance passée). Réutiliser la référence d'un autre montant lève reference_conflict, celle d'un essai expiré payment_expired ; les routes toutes faites annulent l'ancien essai encore ouvert et passent seules à l'essai suivant. Au retour du client, relisez le dernier essai avec getPayment avant de répondre. La facture n'est payée que sur l'avis payment.completed, jamais sur returnUrl. Si le client a payé deux pages, remboursez l'essai en trop avec refund.
use TechnasPay\Status;
use TechnasPay\Webhook\Event;
use TechnasPay\Webhook\WebhookHandlers;
// Clic sur « Payer » (première fois, nouvelle offre, ou retour plus tard).
function payer(Facture $facture, int $montant): string
{
global $pay;
if ($facture->dernier_payment_id !== null) {
$dernier = $pay->getPayment($facture->dernier_payment_id); // jamais seulement sa propre base
if ($dernier->status === 'completed') {
return '/facture/' . $facture->id . '/deja-payee';
}
if ($dernier->status !== 'expired' && $dernier->amount === $montant && $dernier->checkoutUrl !== null) {
return $dernier->checkoutUrl; // même offre, essai en cours : la même page
}
if ($dernier->status !== 'expired') {
// Autre offre : l'ancien lien est fermé d'abord. payment_in_progress (demande en cours chez
// l'opérateur : attendre l'avis) ou payment_already_completed (payé : relire) remontent,
// et AUCUN second paiement n'est créé.
$pay->cancelPayment($dernier->id);
}
}
$facture->tentative += 1; // n + 1, gardé en base
$payment = $pay->askForPayment([
'amount' => $montant,
'reference' => Status::retryReference($facture->id, $facture->tentative),
'customer' => ['email' => $facture->email, 'name' => $facture->nom],
'returnUrl' => 'https://votre-site.com/merci',
]);
$facture->dernier_payment_id = $payment->id;
$facture->save();
return (string) $payment->checkoutUrl;
}
// Seul l'avis signé payment.completed marque la facture payée.
$handlers = new WebhookHandlers(onCompleted: function (Event $e) use ($pay): void {
$facture = Facture::parReference($e->payment->reference);
if ($facture->paye_par !== null && $facture->paye_par !== $e->payment->id) {
$pay->refund($e->payment->id); // l'ancienne page payée aussi : on rend l'essai en trop
return;
}
$facture->paye_par = $e->payment->id; // n'activer qu'une fois
$facture->save();
});composer install
vendor/bin/phpunitLes tests tournent contre un faux transport (aucun appel réseau) et rejouent le contrat partagé.
MIT.