API Reference

Documentation complète de l'API REST YengaPay.

Base URL

Environnement	URL
Production	https://api.yengapay.com/api/v1
Sandbox	https://api.sandbox.yengapay.com/api/v1

Authentification

Toutes les requêtes API nécessitent une clé API dans le header x-api-key :

curl -X GET "https://api.yengapay.com/api/v1/groups/{groupId}/project/current/{projectId}" \
  -H "x-api-key: votre_cle_api"

Méthodes acceptées (par ordre de préférence) :

• Header x-api-key (recommandé) : -H "x-api-key: {apiKey}"
• Header Authorization : -H "Authorization: {apiKey}"
• Query param : ?api_key={apiKey}

Récupérez vos clés API depuis la Console YengaPay.

Format des requêtes

• Content-Type : application/json
• Encoding : UTF-8

Format des réponses

Succès

{
  "id": "YPPO20250113.1538.38055.7265",
  "amount": 5000,
  "status": "PENDING",
  "destNumber": "+22670123456",
  "paymentMethod": "ORANGE_MONEY",
  "createdAt": "2024-01-15T10:30:00Z"
}

Erreur

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le montant doit être supérieur à 100 XOF",
    "details": {
      "field": "amount",
      "reason": "amount must not be less than 100"
    },
    "requestId": "req_xyz789abc"
  }
}

Codes de statut HTTP

Code	Description
200	Succès
201	Ressource créée
400	Requête invalide (paramètres manquants ou incorrects)
401	Non authentifié (clé API manquante ou invalide)
403	Non autorisé (permissions insuffisantes)
404	Ressource non trouvée
405	Méthode non autorisée
429	Trop de requêtes
500	Erreur interne du serveur

Pagination

Les endpoints de liste supportent la pagination via query params :

GET /groups/{groupId}/project/{projectId}/payout?page=1&perPage=20

Paramètres

Paramètre	Type	Défaut	Description
page	integer	1	Numéro de page
perPage	integer	20	Éléments par page (max: 100)

Réponse paginée

{
  "data": [...],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 150,
    "lastPage": 8
  }
}

Rate Limiting

Environnement	Limite
Sandbox	100 req/min
Production	1000 req/min

Headers de réponse :

• X-RateLimit-Limit : Limite totale
• X-RateLimit-Remaining : Requêtes restantes
• X-RateLimit-Reset : Timestamp de réinitialisation (Unix)

Endpoints

Payment Intent

Flux d'intégration via page de paiement (Checkout). Créez un PaymentIntent puis redirigez le client vers checkoutPageUrlWithPaymentToken.

Méthode	Endpoint	Description
POST	/groups/{groupId}/payment-intent/{projectId}	Créer un PaymentIntent
GET	/groups/{groupId}/payment-intent/project/{projectId}/intent/{id}	Récupérer un PaymentIntent

Direct Payment

Paiements API-to-API sans redirection. Supporte les opérateurs ONE_STEP (OTP immédiat) et TWO_STEP (OTP différé).

Méthode	Endpoint	Description
POST	/groups/{groupId}/projects/{projectId}/direct-payment/init	Initialiser un paiement
POST	/groups/{groupId}/projects/{projectId}/direct-payment/init-and-pay	Initialiser et payer en un seul appel
POST	/groups/{groupId}/projects/{projectId}/direct-payment/pay	Déclencher le paiement
POST	/groups/{groupId}/projects/{projectId}/direct-payment/send-otp	Envoyer l'OTP (opérateurs TWO_STEP)
GET	/groups/{groupId}/projects/{projectId}/direct-payment/status/{paymentIntentId}	Vérifier le statut d'un paiement

Payout

Envoi d'argent vers des bénéficiaires mobile money depuis un projet de type PAYOUT. Détail complet (frais, cycle de vie, erreurs) : guide Transferts.

Méthode	Endpoint	Description
POST	/groups/{groupId}/project/{projectId}/payout	Créer un payout
GET	/groups/{groupId}/project/{projectId}/payout	Lister les payouts
GET	/groups/{groupId}/project/{projectId}/payout/stats	Statistiques des payouts
GET	/groups/{groupId}/project/{projectId}/payout/{payoutId}	Récupérer un payout
POST	/groups/{groupId}/project/{projectId}/payout/{payoutId}/retry	Réessayer un payout échoué
GET	/groups/{groupId}/project/{projectId}/payout/configs	Frais/limites par opérateur
GET	/groups/{groupId}/project/{projectId}/payout/aggregate, /group-by	Agrégations pour tableaux de bord

Campaign (Bulk Payout)

Campagnes de payout en masse. Flux : créer → importer fichier → valider → soumettre → approuver → exécuter. Détail complet : guide Transferts en masse.

Méthode	Endpoint	Description
POST	/groups/{groupId}/campaigns/{projectId}	Créer une campagne
GET	/groups/{groupId}/campaigns/{projectId}	Lister les campagnes
GET	/groups/{groupId}/campaigns/{projectId}/{campaignId}	Récupérer une campagne
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/upload	Importer le fichier de bénéficiaires
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/validate	Valider le fichier
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/submit	Soumettre pour approbation
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/approve	Approuver la campagne
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/reject	Rejeter la campagne
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/cancel	Annuler la campagne
GET	/groups/{groupId}/campaigns/{projectId}/{campaignId}/transactions	Transactions de la campagne
GET	/groups/{groupId}/campaigns/{projectId}/{campaignId}/stats	Statistiques de la campagne
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/retry-failed	Réessayer les transactions échouées
DELETE	/groups/{groupId}/campaigns/{projectId}/{campaignId}	Supprimer une campagne (statut non engagé)
POST	/groups/{groupId}/campaigns/{projectId}/{campaignId}/clone	Cloner une campagne
GET	/groups/{groupId}/campaigns/{projectId}/{campaignId}/export, /summary	Export CSV / rapport récapitulatif
PATCH	/groups/{groupId}/campaigns/{projectId}/{campaignId}/sms-notification	Configurer les notifications SMS
GET	/groups/{groupId}/campaigns/{projectId}/fee-schedule, /analytics	Barème de frais / analytics

Cash Out

Retraits de fonds depuis un projet Merchant vers un compte mobile money.

Méthode	Endpoint	Description
POST	/groups/{groupId}/cash-out	Créer un retrait
GET	/groups/{groupId}/cash-out/{projectId}	Lister les retraits
GET	/groups/{groupId}/cash-out/{projectId}/stats	Statistiques des retraits

Project

Gestion des projets, consultation du solde et configuration des webhooks de paiement.

Méthode	Endpoint	Description
POST	/groups/{groupId}/project	Créer un projet
GET	/groups/{groupId}/project	Lister les projets
GET	/groups/{groupId}/project/current/{projectId}	Récupérer les infos du projet (solde inclus)
PATCH	/groups/{groupId}/project/generate-webhook-secret/{projectId}	Générer le secret webhook de paiement

Notifications de paiement (Webhooks)

Les notifications de paiement sont configurées au niveau du projet via PATCH /groups/{groupId}/project/:projectId avec les champs :

• merchantTransactionWebhoookUrl : URL HTTPS de votre endpoint
• isTransactionWebhookActivated : true pour activer les notifications

Lorsqu'un paiement est confirmé (payment.success), YengaPay envoie une requête POST à votre URL avec le payload complet du paiement et le header x-webhook-hash contenant la signature HMAC-SHA256 du payload.

# Vérification de la signature (Node.js)
const hash = crypto.createHmac('sha256', webhookSecret)
  .update(JSON.stringify(payload))
  .digest('hex');
if (hash !== req.headers['x-webhook-hash']) throw new Error('Signature invalide');

Opérateurs supportés

Paiements entrants (PayIn)

Code	Nom	Pays	Type
ORANGE	Orange Money	BF	ONE_STEP
MOOV	Moov Money	BF	TWO_STEP
TELECEL	Telecel Money	BF	ONE_STEP
SANKM	Sank Money	BF	TWO_STEP
CORISM	Coris Money	BF	TWO_STEP

Paiements sortants (Payout)

Valeur	Nom
ORANGE_MONEY	Orange Money
MOOV_MONEY	Moov Money
TELECEL_MONEY	Telecel Money
SANK_MONEY	Sank Money
CORIS_MONEY	Coris Money
WAVE	Wave
MTN_MOMO	MTN Mobile Money

La disponibilité de chaque valeur dépend du countryCode du destinataire — voir la matrice pays/opérateurs du guide Transferts.

Documentation interactive

Testez les endpoints directement via Swagger :

• Swagger UI (Production)

SDKs

Nous recommandons d'utiliser nos SDKs officiels :

• Node.js SDK
• React Button