T
T
TrolooPAY
Se Connecter S'inscrire
Documentation Développeur

API Collection / Payment — TROLOOPAY

Cette page explique comment intégrer l'API de collecte (encaissement) dans une application externe : obtention des credentials, initiation de paiement, vérification du statut, IPN / callback signé, codes d'erreurs et exemples complets en plusieurs langages.

Base URL
https://troloo.com
Initier un paiement
POST /initiate-payment-api
Retourne une approvedUrl
Vérifier le statut
GET /api/verification-payment/{grant_id}/{token}/{transuuid}
Polling de statut

Prérequis & sécurité

  • HTTPS obligatoire : toutes les requêtes doivent être faites en HTTPS.
  • Rate limiting : 30 requêtes par minute par IP sur l'endpoint d'initiation.
  • POST uniquement : l'endpoint /initiate-payment-api n'accepte pas les requêtes GET — les credentials ne doivent jamais transiter en URL.
  • ipn_url : doit être HTTPS et pointer vers un hôte public (protection SSRF).
  • Signature IPN : vérifier le header X-TrolooPay-Signature avec votre client_secret.
Bonnes pratiques
Ne logguez jamais votre client_secret en clair. Stockez-le dans une variable d'environnement côté serveur. Vérifiez la signature de chaque IPN reçu avant d'agir sur votre base de données.

Credentials : client_id & client_secret

Pour appeler l'API de collecte, vous avez besoin d'un couple client_id / client_secret associé à votre compte marchand TROLOOPAY.

  1. Créez un compte marchand sur troloo.com/register et complétez votre profil marchand (informations de l'entreprise, logo, devise).
  2. Accédez à la page Credentials depuis votre tableau de bord marchand (Dashboard → Marchand → Applications API).
  3. Créez une application : un couple client_id / client_secret est généré automatiquement.
  4. Attendez l'approbation par l'administrateur TROLOOPAY (état Approved) avant de commencer à collecter.
  5. Stockez le client_secret en sécurité — une fois généré, il ne s'affiche plus en clair. Utilisez une variable d'environnement côté serveur.
Rôle des credentials
Champ Type Usage
client_id Identifiant public Identifie votre application marchande. Peut être visible.
client_secret Secret confidentiel Authentifie chaque requête. Ne jamais exposer côté client.

1) Initier un paiement

Endpoint
POST https://troloo.com/initiate-payment-api
Body (application/x-www-form-urlencoded ou JSON)
Paramètre Requis Description
client_id Oui Identifiant de votre application marchande
client_secret Oui Secret confidentiel (jamais côté client)
amount Oui Montant à collecter (numérique, min 1)
currency Oui Code devise : XOF, USD, EUR…
method Oui Méthode de paiement (ex: TROLOOPAY, MTNMOMO…)
success_url Oui URL de redirection après paiement réussi
cancel_url Oui URL de redirection si l'acheteur annule
ipn_url Non URL HTTPS de callback (recommandé) — reçoit l'IPN signé
Réponse attendue (200)
{
  "code": 200,
  "data": {
    "error": "ok",
    "message": "Payment Initiated. Redirect to url",
    "url": {
      "approvedUrl": "https://troloo.com/merchant/payment?grant_id=12345678&token=AbCdEfGhIjKlMnOpQrSt",
      "grant_id": 12345678,
      "urltoken": "AbCdEfGhIjKlMnOpQrSt",
      "transactionuuid": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}
Conservez transactionuuid, grant_id et urltoken pour vérifier le statut du paiement ultérieurement.

2) Redirection du client

Après avoir reçu l'approvedUrl, redirigez votre acheteur vers cette URL. Il sera accueilli sur la page de paiement sécurisée TROLOOPAY où il choisit sa méthode et confirme le paiement.

Flux complet
1 Votre serveur appelle POST /initiate-payment-api → reçoit approvedUrl
2 Vous redirigez votre acheteur vers approvedUrl
3 L'acheteur paie sur la page TROLOOPAY (Mobile Money, Crypto, Carte…)
4 TROLOOPAY poste l'IPN sur votre ipn_url ET redirige vers success_url (ou cancel_url)

3) Vérifier le statut (polling)

Si votre ipn_url n'est pas disponible ou pour confirmer côté serveur, vous pouvez interroger le statut d'une transaction par polling.

Endpoint
GET https://troloo.com/api/verification-payment/{grant_id}/{token}/{transactionuuid}
Réponses possibles
203 — Transaction en attente ou expirée (l'acheteur n'a pas encore payé ou a annulé)
200 + status: SUCCESSFUL — Paiement confirmé
200 + status: FAILED — Paiement échoué ou bloqué
Exemple de réponse (paiement confirmé)
{
  "StatusCode": 200,
  "message": "Your transaction is done...",
  "status": "success",
  "data": {
    "id": 42,
    "amount": "97.50",
    "total": "100.00",
    "status": "SUCCESSFUL",
    "created_at": "2026-05-28T14:30:00.000000Z",
    "updated_at": "2026-05-28T14:31:05.000000Z"
  }
}

IPN / Callback & signature

Si vous fournissez le paramètre ipn_url lors de l'initiation, TROLOOPAY enverra une requête POST sur cette URL dès que le paiement est confirmé ou échoué. L'IPN remplace les redirections pour les intégrations serveur-à-serveur.

Payload IPN (POST JSON)
{
  "method": "MTNMOMO",
  "status": "SUCCESSFUL",
  "transuuid": "550e8400-e29b-41d4-a716-446655440000",
  "gateway_reference": "uuid-interne-gateway",
  "currency": "XOF",
  "amount": 5000.00,
  "paid_amount": 4900.00
}
Champ Description
method Méthode de paiement : MTNMOMO, MOOVMONEY, TROLOOPAY, Coinpayments…
status SUCCESSFUL ou FAILED
transuuid UUID de la transaction (retourné à l'initiation)
amount Montant total payé par l'acheteur (avec frais)
paid_amount Montant net crédité au marchand (après déduction des frais). 0 en cas d'échec.
Signature IPN
TROLOOPAY signe chaque IPN avec votre client_secret (HMAC-SHA256 du body JSON). Le résultat est transmis dans le header X-TrolooPay-Signature: sha256=<hash>.
PHP — vérifier la signature IPN
$clientSecret = getenv('TROLOOPAY_CLIENT_SECRET');
$rawBody      = file_get_contents('php://input');
$signature    = $_SERVER['HTTP_X_TROLOOPAY_SIGNATURE'] ?? '';

// Extraire le hash (format: "sha256=<hash>")
$receivedHash = str_starts_with($signature, 'sha256=') ? substr($signature, 7) : $signature;
$expectedHash = hash_hmac('sha256', json_encode(json_decode($rawBody, true)), $clientSecret);

if (!hash_equals($expectedHash, $receivedHash)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Signature valide — traiter le paiement
$payload = json_decode($rawBody, true);

if ($payload['status'] === 'SUCCESSFUL') {
    // Créditer la commande dans votre système
    $transactionUuid = $payload['transuuid'];
    $paidAmount      = $payload['paid_amount'];
    // ...
}
Important : votre ipn_url doit être HTTPS et ne doit pas résoudre vers des IPs privées (ex: 10.x, 192.168.x, 127.x). Répondez avec un code 2xx pour accuser réception.

Méthodes de paiement supportées

Mobile Money
  • MTNMOMO (Bénin, Ghana, Uganda, CI…)
  • MOOVMONEY (Bénin)
  • Orangesenegal
Crypto / Wallets
  • Coinpayments
  • Binance
  • Perfectmoney
  • Payeer
Carte / Wallet interne
  • TROLOOPAY (wallet interne)
  • Stripe
  • FLUTTERWAVE

Passez le nom de la méthode dans le champ method lors de l'initiation. La liste des méthodes actives dépend de la devise sélectionnée.

Erreurs & codes

HTTP Code Message Cause fréquente
400 400 Champ requis manquant ou invalide amount, currency, method, success_url ou cancel_url absent
400 400 Currency not valid or not active La devise n'est pas activée dans le système
401 401 Invalid client_id or client_secret Credentials incorrects ou application non approuvée
403 403 Merchant account is not approved Compte marchand en attente d'approbation ou suspendu
404 404 Merchant not found Aucun marchand associé à ces credentials
429 429 Too Many Requests Rate limiting : 30 req/min dépassé
500 500 Internal error Erreur serveur interne (contacter le support)

Exemples d'intégration

Exemples prêts à copier/coller pour initier un paiement. Choisissez votre langage.

cURL — initier un paiement
curl -X POST https://troloo.com/initiate-payment-api \
  -d "client_id=VOTRE_CLIENT_ID" \
  -d "client_secret=VOTRE_CLIENT_SECRET" \
  -d "amount=5000" \
  -d "currency=XOF" \
  -d "method=TROLOOPAY" \
  -d "success_url=https://votre-site.com/paiement/succes" \
  -d "cancel_url=https://votre-site.com/paiement/annule" \
  -d "ipn_url=https://votre-site.com/webhook/payment"