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.
Sommaire
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.
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.
- Créez un compte marchand sur troloo.com/register et complétez votre profil marchand (informations de l'entreprise, logo, devise).
- Accédez à la page Credentials depuis votre tableau de bord marchand (Dashboard → Marchand → Applications API).
- Créez une application : un couple client_id / client_secret est généré automatiquement.
- Attendez l'approbation par l'administrateur TROLOOPAY (état Approved) avant de commencer à collecter.
- 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.
| 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
| 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é |
{
"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"
}
}
}
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.
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.
{
"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.
{
"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. |
$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'];
// ...
}
Méthodes de paiement supportées
- MTNMOMO (Bénin, Ghana, Uganda, CI…)
- MOOVMONEY (Bénin)
- Orangesenegal
- Coinpayments
- Binance
- Perfectmoney
- Payeer
- 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 -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"