Encaissez du Mobile Money depuis votre code.

Démarrage

Trois minutes suffisent pour encaisser votre premier paiement de test.

1. 1

   Créez votre compte

   L'inscription est immédiate et ne demande aucun document. Votre compte démarre en attente de validation : le mode test est ouvert tout de suite, le mode réel après vérification de votre activité.

2. 2

   Récupérez vos clés

   Tableau de bord → Clés API. Le secret n'est affiché qu'une fois, à sa création : nous n'en gardons qu'une empreinte. Perdu, il se renouvelle ; il ne se retrouve pas.

3. 3

   Appelez l'API en test

   Créez un paiement, ouvrez son checkout_url, payez avec un numéro de test. Rien ne part vers un opérateur, aucun franc ne bouge.

Services et clés

Un compte marchand peut porter plusieurs activités : une boutique en ligne, une application mobile, un site de contenu. Chacune est un service, déclaré et approuvé séparément, avec ses propres clés et ses propres URL de retour et de notification.

Authentification

Toutes les requêtes passent par HTTPS et portent votre clé secrète. La base de l'API :

https://walleopay.com/api/v1

Envoyez le secret dans l'en-tête Authorization :

Authorization: Bearer sk_test_votre_cle

Si votre hébergement mange l'en-tête Authorization — cela arrive encore sur du mutualisé Apache mal configuré — utilisez l'en-tête de repli :

X-WalleoPay-Secret: sk_test_votre_cle

Créer un paiement

Un paiement naît « en attente » : rien n'est encore envoyé à un opérateur. À vous de choisir ensuite comment le client paie.

Champs

Requête

curl -X POST https://walleopay.com/api/v1/payments \
  -H "Authorization: Bearer sk_test_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-1042" \
  -d '{
    "amount": 12500,
    "reference": "A1042",
    "description": "Commande A1042",
    "notify_url": "https://ma-boutique.cm/walleopay/webhook",
    "return_url": "https://ma-boutique.cm/merci"
  }'

Réponse 201 Created

{
    "data": {
        "id": "pay_01k5m3q9zt6r8v2wxyd4n7hpab",
        "object": "payment",
        "mode": "test",
        "status": "pending",
        "amount": 12500,
        "currency": "XAF",
        "fee": 375,
        "net": 12125,
        "description": "Commande A1042",
        "reference": "A1042",
        "operator": null,
        "customer": {
            "name": "Awa Nguema",
            "email": "awa@example.cm",
            "phone": null
        },
        "checkout_url": "https://walleopay.com/pay/8f3c1d0a5b9e4726ac18d5f0b3e71249c6a8047d",
        "failure_code": null,
        "failure_message": null,
        "metadata": {
            "commande_id": 1042
        },
        "paid_at": null,
        "expires_at": "2026-09-20T16:39:56+01:00",
        "created_at": "2026-09-20T16:09:56+01:00"
    }
}

fee est notre commission, calculée à la création et prélevée seulement si le paiement aboutit. net est ce qui atterrira sur votre solde. Les horodatages sont en ISO 8601, avec leur décalage.

Deux façons de faire payer

curl -X POST https://walleopay.com/api/v1/payments \
  -H "Authorization: Bearer sk_test_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500,
    "customer_phone": "699000001",
    "charge": true
  }'

Un paiement déjà créé se déclenche aussi plus tard, avec POST /payments/{id}/charge. Relancer un paiement déjà engagé ne renvoie pas une seconde invite PIN : le client n'aura jamais deux demandes pour une commande.

L'en-tête Idempotency-Key

Le réseau coupe entre votre serveur et le nôtre. Vous ne savez pas si le paiement a été créé. Vous réessayez — et vous risquez de facturer deux fois la même commande. L'en-tête Idempotency-Key supprime ce risque : envoyez-le sur POST /payments et POST /payouts, avec une valeur stable dérivée de votre commande.

POST /api/v1/payments
Authorization: Bearer sk_test_votre_cle
Idempotency-Key: commande-1042
Content-Type: application/json

→ 201  { "data": { "id": "pay_01k5m3…", "status": "pending", … } }

# Le réseau a coupé, vous renvoyez exactement le même corps :

→ 201  Idempotent-Replay: true
       { "data": { "id": "pay_01k5m3…", … } }   ← le même paiement

# Même clé, corps différent :

→ 409  { "error": { "type": "idempotency_conflict", "message": "…" } }

Une clé est propre à votre compte et au point d'entrée appelé : la même valeur chez deux marchands, ou sur deux points d'entrée différents, ne se marche pas dessus. Un bon choix de clé : commande-1042, facture-2026-0117 — quelque chose que votre code recalculera à l'identique au réessai.

Les autres points d'entrée

Statuts d'un paiement

Un statut définitif ne changera plus jamais : vous pouvez classer la commande et cesser d'interroger. Les autres bougeront encore.

Mode code marchand

MTN et Orange délivrent un code marchand bien avant d'ouvrir l'accès à leur API. Ce mode permet d'encaisser pour de vrai dès aujourd'hui, en attendant la signature du contrat technique — au prix d'une vérification humaine, que nous préférons annoncer plutôt que déguiser.

Ce que voit votre client

À la place du formulaire habituel, la page de paiement affiche le code marchand et cinq instructions :

1. 1. Composez le *126# (MTN) ou le #150# (Orange) sur votre téléphone
2. 2. Choisissez « Paiement marchand »
3. 3. Entrez le code marchand affiché à l'écran
4. 4. Entrez le montant exact de la commande
5. 5. Validez avec votre code secret Mobile Money

Ce qui se passe ensuite

Côté intégration, rien ne change : vous créez le paiement exactement de la même façon et vous redirigez vers checkout_url. Seule différence à prévoir dans votre code : le statut awaiting_confirmation, qu'il faut traiter comme « en attente » et non comme un échec.

Les reversements, eux, ne se pilotent pas dans ce mode : sans API opérateur, il n'y a rien à déclencher. POST /payouts accepte bien la demande et débite votre solde, mais l'envoi échoue ensuite avec le code merchant_code_disbursement_manual et votre solde est recrédité intégralement. Le virement se fait à la main depuis l'application MoMo. Surveillez donc l'état du reversement, pas seulement le 201 de sa création.

Migrer du code marchand vers l'API MoMo

Le jour où le contrat technique MTN est signé, la bascule est une ligne de configuration chez nous : config('walleopay.routing.live.mtn_momo') passe de merchant_code à mtn_momo. Vous n'avez rien à modifier.

Webhooks

Dès qu'un paiement ou un reversement change d'état, nous appelons votre notify_url en POST, avec un corps JSON signé.

Événements émis

En-têtes envoyés

Format de la signature

La signature est un HMAC-SHA256 calculé sur la chaîne horodatage . "." . corps, avec le secret de webhook de votre compte. L'horodatage est inclus dans la chaîne signée : un appel capté ne peut donc pas être rejoué plus tard avec une date fraîche.

X-WalleoPay-Signature: t=1758300000,v1=5f2e91c4a7...c91a

hmac_sha256("1758300000." + corps_brut, whsec_votre_secret)

Vérification côté marchand (PHP)

<?php
// POST https://ma-boutique.cm/walleopay/webhook

$secret = 'whsec_votre_secret';   // Tableau de bord > Webhooks
$body   = file_get_contents('php://input');
$entete = $_SERVER['HTTP_X_WALLEOPAY_SIGNATURE'] ?? '';

// En-tête reçu : « t=1758300000,v1=5f2e...c91a »
$parties = [];
foreach (explode(',', $entete) as $morceau) {
    [$cle, $valeur] = array_pad(explode('=', $morceau, 2), 2, '');
    $parties[$cle] = $valeur;
}

$horodatage = (int) ($parties['t'] ?? 0);
$recue      = (string) ($parties['v1'] ?? '');

// 1. Fenêtre temporelle : sans elle, un appel capté aujourd'hui
//    pourrait être rejoué dans six mois, signature valide à l'appui.
if ($horodatage <= 0 || abs(time() - $horodatage) > 300) {
    http_response_code(400);
    exit('horodatage hors tolerance');
}

// 2. La signature porte sur « horodatage.corps », avec le corps brut :
//    ne le décodez pas avant de l'avoir vérifié.
$attendue = hash_hmac('sha256', $horodatage.'.'.$body, $secret);

// hash_equals, jamais == : la comparaison doit être à temps constant.
if (! hash_equals($attendue, $recue)) {
    http_response_code(400);
    exit('signature invalide');
}

$evenement = json_decode($body, true);

// 3. Le webhook vous dit d'aller voir ; il ne vous dit pas de livrer.
//    On redemande l'état à la source avant de toucher à la commande.
$paiement = walleopay_get('/payments/'.$evenement['data']['id']);

if ($paiement['data']['status'] === 'succeeded') {
    livrer_commande($paiement['data']['reference'], $paiement['data']['amount']);
}

// Répondez 2xx, sinon nous réessaierons.
http_response_code(200);
echo 'ok';

Politique de réessai

Une réponse 2xx vaut accusé de réception. Tout le reste — code d'erreur, délai dépassé, serveur injoignable — déclenche un réessai, jusqu'à 8 tentatives, espacées ainsi :

Chaque appel a 10 secondes pour répondre : répondez vite et traitez ensuite, plutôt que de faire votre travail avant de répondre. Vos livraisons sont consultables et rejouables à la main depuis le tableau de bord. Tolérez les doublons : un même événement peut arriver deux fois, et votre traitement doit rester sans effet la seconde fois.

Mode test

Avec une clé sk_test_…, rien ne sort de nos serveurs. Le sort d'un paiement est décidé par le numéro utilisé, ce qui vous permet de dérouler les chemins d'échec sans attendre un vrai refus d'opérateur. Comptez 6 secondes de délai simulé avant le dénouement : c'est fait exprès, pour que vous voyiez l'écran d'attente que verra votre client.

Tout autre numéro camerounais valide aboutit : c'est le cas que vous voulez voir passer quand vous branchez votre boutique. Les paiements de test alimentent un solde de test, séparé de votre solde réel, et n'apparaissent jamais dans vos chiffres de production.

Codes d'erreur

Un refus métier arrive dans cette enveloppe :

{
    "error": {
        "type": "merchant_not_active",
        "message": "Votre compte n'est pas encore activé pour les paiements réels…"
    }
}

Un refus de validation, lui, arrive au format standard de Laravel, sans error.type. Prévoyez les deux formes :

{
    "message": "Un paiement existe déjà avec cette référence.",
    "errors": {
        "reference": ["Un paiement existe déjà avec cette référence."]
    }
}

Quand le refus concerne un paiement déjà créé, la réponse d'erreur porte en plus une clé data avec l'état du paiement : vous savez ce qui existe de votre côté sans avoir à le relire.

Limites

Au-delà, l'API répond 429 Too Many Requests avec un en-tête Retry-After. Respectez-le : réessayer en boucle ne fera que prolonger le blocage. Si vous sondez l'état d'un paiement, espacez vos appels de quelques secondes plutôt que de marteler — ou laissez le webhook vous prévenir.

Exemples complets

PHP — créer et rediriger

<?php

$secret = 'sk_test_votre_cle';   // jamais dans le code du navigateur
$base   = 'https://walleopay.com/api/v1';

$payload = json_encode([
    'amount'         => 12500,          // 12 500 FCFA : le XAF n'a pas de centimes
    'currency'       => 'XAF',
    'reference'      => 'A1042',        // votre numéro de commande
    'description'    => 'Commande A1042',
    'customer_name'  => 'Awa Nguema',
    'customer_email' => 'awa@example.cm',
    'return_url'     => 'https://ma-boutique.cm/merci',
    'cancel_url'     => 'https://ma-boutique.cm/panier',
    'notify_url'     => 'https://ma-boutique.cm/walleopay/webhook',
    'metadata'       => ['commande_id' => 1042],
]);

$ch = curl_init($base.'/payments');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 20,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer '.$secret,
        'Content-Type: application/json',
        'Accept: application/json',
        // Rejouer cet appel après une coupure réseau ne créera pas
        // un second paiement pour la même commande.
        'Idempotency-Key: commande-1042',
    ],
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$reponse = json_decode($body, true);

if ($status !== 201) {
    // Refus métier : ['error' => ['type' => ..., 'message' => ...]]
    // Refus de validation : ['message' => ..., 'errors' => ['amount' => [...]]]
    throw new RuntimeException($reponse['error']['message'] ?? $reponse['message'] ?? 'Création refusée.');
}

// Rangez l'identifiant à côté de votre commande : c'est lui qui vous
// servira à vérifier le paiement plus tard.
enregistrer_paiement(1042, $reponse['data']['id']);

// Puis envoyez le client payer.
header('Location: '.$reponse['data']['checkout_url']);
exit;

JavaScript — créer et vérifier

// Node.js — le secret ne quitte jamais votre serveur.
const BASE = 'https://walleopay.com/api/v1';
const SECRET = process.env.WALLEOPAY_SECRET; // sk_test_… ou sk_live_…

async function creerPaiement(commande) {
  const reponse = await fetch(`${BASE}/payments`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${SECRET}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
      'Idempotency-Key': `commande-${commande.id}`,
    },
    body: JSON.stringify({
      amount: commande.total,              // entier, en FCFA
      reference: `CMD-${commande.id}`,
      description: `Commande ${commande.id}`,
      customer_phone: commande.telephone,  // 6XXXXXXXX ou +2376XXXXXXXX
      notify_url: 'https://ma-boutique.cm/walleopay/webhook',
      return_url: 'https://ma-boutique.cm/merci',
      metadata: { commande_id: commande.id },
    }),
  });

  const corps = await reponse.json();

  if (!reponse.ok) {
    // 429 : vous cognez trop vite, respectez l'en-tête Retry-After.
    throw new Error(corps.error?.message ?? corps.message ?? 'Création refusée');
  }

  return corps.data; // { id, status, checkout_url, … }
}

async function estPaye(paymentId) {
  const reponse = await fetch(`${BASE}/payments/${paymentId}`, {
    headers: { Authorization: `Bearer ${SECRET}`, Accept: 'application/json' },
  });

  const { data } = await reponse.json();

  // « succeeded » est le seul état qui autorise la livraison.
  // « awaiting_confirmation » veut dire « on ne sait pas encore ».
  return data.status === 'succeeded';
}

// Parcours complet : on crée, puis on envoie le client sur checkout_url.
const paiement = await creerPaiement({ id: 1042, total: 12500, telephone: '699000001' });
reponseHttp.redirect(paiement.checkout_url);