Le bouton « Payer avec Alias PI-SPI »

Ajoutez le paiement par alias PI-SPI à votre site en trois morceaux — le bouton, une route, un webhook — avec Node.js, Java ou PHP.

4 min de lecture · Mis à jour le 25/10/2026 · API v1

Le bouton fonctionne comme le paiement par carte d'un site marchand : le client quitte votre site quelques instants pour payer sur pismile.com, puis revient. Vous n'avez rien à afficher ni à sécuriser côté paiement.

Comment ça marche#

Le client clique sur « Payer avec Alias PI-SPI »
Sur votre page commande, panier ou produit. Le bouton mène vers votre serveur (par exemple /commandes/42/payer).
Votre serveur crée une page de paiement
Il appelle pismile avec le montant, votre référence (cmd-42) et l'adresse de retour. pismile répond avec une adresse : https://pismile.com/payer/cs_…
Votre serveur y envoie le client
Simple redirection. Le client paie sur pismile.com : son alias, ou plusieurs comptes.
pismile prévient votre serveur
Un webhook session.payee arrive sur votre serveur : c'est la preuve du paiement. Vous marquez la commande payée.
Le client revient sur votre site
Sur votre adresse de retour, avec ?pismile_session=cs_…&statut=payee. Vous affichez « Merci ».

Avant de commencer : Préparer votre compte (domaine vérifié et application créée).

1. Installez le SDK#

npm install @pismile/node

pom.xml

<repositories>
  <repository><id>jitpack.io</id><url>https://jitpack.io</url></repository>
</repositories>
<dependency>
  <groupId>com.github.getpismile</groupId>
  <artifactId>pismile-java</artifactId>
  <version>0.1.0</version>
</dependency>

composer require pismile/pismile-php

Puis vos identifiants, côté serveur uniquement :

.env

PISMILE_CLIENT_ID=VOTRE_CLIENT_ID
PISMILE_CLIENT_SECRET=votre_secret
PISMILE_WEBHOOK_SECRET=whsec_...   # étape 4

2. Le bouton, sur votre page#

commande.html

<script src="https://pismile.com/kit/v1/pismile-button.js" defer></script>

<pismile-button text="pay" href="/commandes/42/payer"></pismile-button>

Le bouton affiche « Payer avec Alias PI-SPI » et, dessous, « Sécurisé par pismile.com · seul ou à plusieurs comptes ». Options : theme="dark" ou "light", size="lg", width="full". Voir le kit du bouton.

3. La route du bouton : créer la page et y envoyer le client#

routes/paiement.js

import { Pismile } from "@pismile/node"
const pismile = new Pismile()   // lit PISMILE_CLIENT_ID et PISMILE_CLIENT_SECRET

app.get("/commandes/:id/payer", async (req, res) => {
  const commande = await trouverCommande(req.params.id, req.user)   // votre code
  const page = await pismile.sessions.creer({
    montant: commande.total,                                  // F CFA, entier
    reference: `cmd-${commande.id}`,                          // unique : la renvoyer renvoie la même page
    retour: `https://votre-site.com/commandes/${commande.id}/merci`,
    motif: `Commande ${commande.id}`,
  })
  res.redirect(303, page.url)
})

PaiementController.java

@GetMapping("/commandes/{id}/payer")
String payer(@PathVariable long id) {
    Commande c = commandes.duClientConnecte(id);                 // votre code
    SessionPaiement page = pismile.sessions().creer(
            c.getTotalFcfa(),                                    // F CFA
            "cmd-" + id,                                         // unique
            "https://votre-site.com/commandes/" + id + "/merci",
            "Commande " + id);
    return "redirect:" + page.url();
}
// Bean : Pismile pismile = Pismile.depuisEnvironnement();

payer.php

<?php
require 'vendor/autoload.php';
$pismile = Pismile\Pismile::depuisEnvironnement();

$commande = trouverCommande((int) $_GET['commande']);          // votre code
$page = $pismile->sessions()->creer(
    $commande['total'],                                        // F CFA
    'cmd-' . $commande['id'],                                  // unique
    'https://votre-site.com/merci.php?commande=' . $commande['id'],
    'Commande ' . $commande['id'],
);
header('Location: ' . $page->url, true, 303);

4. Le webhook : la preuve du paiement#

Dans la console → Applications → votre application → Paiements :

indiquez l'adresse de votre webhook, par exemple https://votre-site.com/webhooks/pismile ;
copiez le secret whsec_… affiché (une seule fois) dans PISMILE_WEBHOOK_SECRET ;
cliquez sur Envoyer un test.

routes/webhook.js

// express.raw : on garde le corps BRUT pour vérifier la signature
app.post("/webhooks/pismile", express.raw({ type: "application/json" }), (req, res) => {
  let evenement
  try {
    evenement = pismile.webhooks.verifier(req.body, req.headers["pismile-signature"])
  } catch {
    return res.sendStatus(400)
  }
  if (evenement.type === "session.payee") {
    marquerPayee(evenement.donnees.reference)   // « cmd-42 »
  }
  res.sendStatus(200)
})

PismileWebhook.java

@PostMapping("/webhooks/pismile")
ResponseEntity<Void> recevoir(@RequestBody String corps,
                              @RequestHeader(Webhooks.ENTETE) String signature) {
    Evenement e;
    try {
        e = pismile.webhooks().verifier(corps, signature);
    } catch (PismileException refus) {
        return ResponseEntity.badRequest().build();
    }
    if (e.estSessionPayee()) {
        commandes.marquerPayee(e.reference());   // « cmd-42 »
    }
    return ResponseEntity.ok().build();
}
// Sécurité : http.csrf(c -> c.ignoringRequestMatchers("/webhooks/pismile"))

webhook.php

<?php
require 'vendor/autoload.php';
$pismile = Pismile\Pismile::depuisEnvironnement();

try {
    $e = $pismile->webhooks()->verifier(file_get_contents('php://input'),
                                        $_SERVER['HTTP_PISMILE_SIGNATURE'] ?? null);
} catch (Pismile\PismileException $refus) {
    http_response_code(400);
    exit;
}
if ($e->estSessionPayee()) {
    marquerPayee($e->reference());   // « cmd-42 »
}
http_response_code(200);

Tout savoir sur les webhooks (événements, nouvelles tentatives) : Être prévenu : webhooks.

5. La page de retour#

Le client revient sur votre adresse de retour. Affichez un message selon l'état de la commande dans votre base (mise à jour par le webhook) :

commande payée : « Merci, paiement reçu » ;
pas encore : « Confirmation en cours… » et rechargez la page toutes les 3 secondes (le webhook arrive en général en quelques secondes).

Ce qui se passe dans les cas particuliers#

Situation	Ce qui se passe
Le client ferme la page avant de payer	Rien n'est débité. La page expire après 30 minutes (webhook `session.expiree`).
Le client clique « Annuler et retourner sur le site »	Il revient sur votre adresse (ou `annulation` si vous l'avez fournie), avec `statut=annulee`.
Le client refuse dans sa banque	La page le lui indique et lui propose de payer avec un autre compte.
Le client partage sur plusieurs comptes	Le webhook `session.payee` arrive quand tout est payé.
Une partie seulement est payée et la page expire	Webhook `session.expiree` avec `montantPaye` : vous complétez la commande autrement ou remboursez cette partie depuis votre compte.

Tester#

Utilisez une application de test (sandbox) : l'adresse de retour peut être http://localhost.
Ouvrez votre page, cliquez sur le bouton, payez avec un alias de test.
Vérifiez dans la console → Encaissement → Pages de paiement, et dans l'historique des webhooks de votre application.

Puis : Tester et passer en production.

Cette page vous a-t-elle aidé ?