Gestion des Paiements

Vue d'ensemble

Cette section présente l'API de traitement des paiements, qui gère l'exécution effective des transactions financières. Elle constitue le cœur opérationnel du système de paiement, orchestrant les sessions de paiement et leur exécution sécurisée.

Fonctionnalités couvertes

Notre API de paiements offre un système complet d'exécution des transactions :

Préparation des sessions

Initialisation des sessions de paiement pour des ordres spécifiques
Configuration des méthodes de paiement (Orange Money, MTN Money, etc.)
Gestion des informations client (nom, email, adresse, téléphone)
Paramétrage des timeouts et configurations OTP

Exécution sécurisée

Traitement des paiements avec validation OTP
Support des modes réel et test pour les environnements de développement
Gestion des tentatives et limitation des échecs
Redirection automatique selon le statut de transaction

Gestion des sessions

Suivi en temps réel des sessions actives
Configuration des codes USSD manuels
Gestion des timeouts de session et OTP
Récupération d'état des sessions par slug d'ordre

Workflow de paiement

Le processus suit un workflow en deux étapes critiques :

Préparation (POST /api/v1/payment/prepare) :
- Validation de l'ordre et du montant
- Initialisation de la session avec le fournisseur de paiement
- Génération des paramètres OTP et timeouts
Exécution (POST /api/v1/payment/execute/{real}) :
- Validation du code OTP client
- Traitement de la transaction auprès du fournisseur
- Confirmation et redirection selon le résultat

Cette architecture garantit la sécurité et la traçabilité de chaque transaction tout en offrant une expérience utilisateur fluide.

| Action | Endpoint | |---|---| | POST | /api/v1/payment/prepare | | POST | /api/v1/payment/execute/{real}|

Préparation d'une session de paiement

Endpoint: POST /api/v1/payment/prepare

Prépare une session de paiement pour une commande spécifique.

Corps de la Requête

{
  "orderSlug": "commande-123",
  "paymentMethod": "ORANGE_MONEY",
  "phoneNumber": {
    "indicator": "+225",
    "telephone": "0701020304"
  },
  "amount": 5000,
  "paymentInformation": {
    "firstname": "Jean",
    "lastname": "Dupont",
    "email": "jean.dupont@example.com",
    "address": "Abidjan, Côte d'Ivoire",
    "metaData": "Client régulier"
  }
}

Réponse

{
  "message": "OK",
  "body": {
    "otpTimeout": 300,
    "otpManualGenerationRequired": false,
    "otpManualUSSDCode": "*123#",
    "sessionId": "session-xyz",
    "sessionTimeout": 600
  }
}

Exécution d'un paiement

Endpoint: POST /api/v1/payment/execute/{real}

Exécute un paiement avec le code OTP reçu par l'utilisateur.

Paramètre de chemin

real: booléen indiquant si le paiement est réel (true) ou en mode test (false).

Corps de la Requête

{
  "orderSlug": "commande-123",
  "otp": "123456"
}

Réponse

{
  "message": "OK",
  "body": {
    "transactionId": "txn-456",
    "successRedirectURL": "https://marchand.com/succes",
    "failureRedirectURL": "https://marchand.com/echec",
    "status": "SUCCESS",
    "remainingRetries": 0
  }
}

Récupération d'une session de paiement par slug

Endpoint: GET /api/v1/payment/session/by-slug/{orderSlug}

Récupère les informations d'une session de paiement en utilisant le slug de la commande.

Paramètre de chemin

orderSlug: identifiant unique de la commande

{
  "message": "OK",
  "body": {
    "otpTimeout": 300,
    "otpManualGenerationRequired": true,
    "otpManualUSSDCode": "*123#",
    "sessionId": "session-abc",
    "sessionTimeout": 600
  }
}

Réponse

{
  "message": "OK",
  "body": {
    "otpTimeout": 300,
    "otpManualGenerationRequired": true,
    "otpManualUSSDCode": "*123#",
    "sessionId": "session-abc",
    "sessionTimeout": 600
  }
}

Ordres de paiements

Plateformes