pismile

Référence de l'API paiements

Endpoints, champs, statuts et codes d'erreur des pages de paiement et des demandes de paiement.

3 min de lecture · Mis à jour le · API v1

Connectez-vous pour voir vos propres identifiants sandbox dans les exemples.

Pour les développeurs qui n'utilisent pas de SDK, ou qui veulent tout savoir. Les SDK Node.js, Java et PHP font ces appels pour vous.

Authentification#

Chaque appel s'authentifie avec les identifiants de votre application, en HTTP Basic :

Terminal
curl https://pismile.com/api/v1/sessions-paiement/cs_… -u "VOTRE_CLIENT_ID:VOTRE_SECRET"

Appels serveur à serveur uniquement. Format : JSON en UTF-8. Montants : entiers en F CFA (XOF). Dates : ISO 8601 en UTC.

Pages de paiement#

Créer — POST /api/v1/sessions-paiement#

Terminal
curl -X POST https://pismile.com/api/v1/sessions-paiement \
  -u "VOTRE_CLIENT_ID:VOTRE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"montant": 25000, "reference": "cmd-42", "motif": "Commande 42",
       "retour": "https://votre-site.com/commandes/42/merci"}'

Champ

Obligatoire

Description

montant

oui

Entier, en F CFA

reference

oui

Votre identifiant unique, 1 à 64 caractères : lettres, chiffres, . _ : -

retour

oui

Adresse HTTPS sur un domaine vérifié (en test : http://localhost accepté). Reçoit ?pismile_session=…&statut=…

annulation

non

Adresse si le payeur abandonne (défaut : retour)

motif

non

100 caractères au plus, sans émoji. Affiché : « Nom de l'application - motif »

Réponse 201 (ou 200 si la référence existait déjà : même page, même montant) :

JSON
{
  "id": "cs_Hq2…",
  "url": "https://pismile.com/payer/cs_Hq2…",
  "reference": "cmd-42",
  "montant": 25000,
  "devise": "XOF",
  "motif": "Ma Boutique - Commande 42",
  "statut": "OUVERTE",
  "montantPaye": 0,
  "creeLe": "2026-10-25T10:38:51Z",
  "expireLe": "2026-10-25T11:08:51Z",
  "test": false
}

Lire — GET /api/v1/sessions-paiement/{id} ou ?reference=cmd-42#

Statuts d'une page#

Statut

Signification

OUVERTE

En attente du payeur (ou de la validation de ses demandes)

PAYEE

Entièrement payée (payeLe renseigné)

EXPIREE

30 minutes sans paiement complet ; voir montantPaye

ANNULEE

Le payeur a annulé avant tout paiement

Demandes de paiement#

Créer — POST /api/v1/paiements#

Champ

Obligatoire

Description

sub

oui

Identifiant de l'utilisateur reçu à la connexion (scope pismile:payment accordé)

montant

oui

Entier, en F CFA

reference

oui

Votre identifiant unique

motif

non

100 caractères au plus

Réponse 201 : id, reference, sub, montant, devise, motif, statut (EN_ATTENTE, PAYE, REFUSE, ANNULE, EXPIRE, ECHEC), compte (masqué), creeLe, expireLe, payeLe, raison, test.

Lire — GET /api/v1/paiements/{id} ou ?reference=…#

Erreurs#

Toujours le même format, avec un code stable à tester dans votre code :

JSON
{ "erreur": "retour_domaine_non_verifie", "message": "retour : « autre.com » n'est pas un domaine vérifié de votre organisation (console → Domaines)." }

HTTP

Code

Signification

400

corps_invalide · montant_invalide · reference_invalide · motif_invalide · retour_invalide · sub_manquant

Requête incorrecte

400

retour_domaine_non_verifie

Adresse de retour hors de vos domaines vérifiés

401

authentification

client_id ou client_secret incorrect

403

module_encaissement_requis · organisation_non_verifiee · application_inactive · scope_non_autorise

Compte pas encore prêt (voir la console)

403

autorisation_absente

(demandes) L'utilisateur n'a pas accordé pismile:payment

404

session_introuvable · paiement_introuvable

Identifiant inconnu

409

reference_deja_utilisee

Référence déjà prise avec un autre montant (ou un autre utilisateur)

409

acces_participant_non_verifie · quota_atteint · compte_absent

Voir le message

429

trop_de_demandes_en_attente · limite_journaliere

Limites des demandes de paiement

502

participant_refus

Votre participant PI-SPI a refusé : réessayez, puis testez votre accès dans la console

Cette page vous a-t-elle aidé ?