Skip to content

About

Technas Pay pour PHP : mobile money et carte, Laravel, Symfony, PSR-15 (composer technas/pay)

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

technas/pay (PHP)

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.

1. Installer

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

Technas vous remet un secret. Mettez-le dans les variables d'environnement du serveur :

TECHNAS_PAY_SECRET=tps_test_...

Un secret tps_test_ ne déplace aucun argent. Un secret tps_live_ encaisse pour de vrai. Le code est le même.

2. Demander un paiement

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.

3. Recevoir l'avis de paiement

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

4. Pour une app mobile : les routes toutes faites

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.

5. Tout le reste

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

Erreurs

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'] (amount ou duration). 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.

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à 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->consoleUrl

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

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.

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();
});

Développer

composer install
vendor/bin/phpunit

Les tests tournent contre un faux transport (aucun appel réseau) et rejouent le contrat partagé.

Licence

MIT.

About

Technas Pay pour PHP : mobile money et carte, Laravel, Symfony, PSR-15 (composer technas/pay)

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages