Documentation de l'API de Paiement

Prérequis pour les Marchands

Création de Compte Marchand

Avant de pouvoir accepter des paiements, les marchands doivent :

1. Création de Compte
   • S'inscrire sur la plateforme
   • Fournir les informations commerciales de base
   • Accepter les conditions d'utilisation
2. Configuration des Informations de Paiement
   • Configurer les méthodes de retrait:
     • Mobile Money
     • Compte bancaire
   • Vérifier et valider les coordonnées bancaires
3. Processus KYB (Know Your Business)
   • Vérification d'identité de l'entreprise
   • Soumission de documents officiels
   • Validation par l'équipe de conformité

Environnements

1. Environnement de production

   https://api.elyonpay.org/api

2. Environnement de test

   https://api.elyonpay.net/api

Pour pouvoir effectuer des requêtes sur l'environnement de test, il faut pour cela utiliser l'utilisateur suivant pour se connecter :

{
  "username": "test@test.com",
  "password": "TestPassword1",
  "role": "ROLE_CUSTOMER"
}

Authentification

Point de terminaison de Connexion

Endpoint

POST /api/login

Description

Authentifiez-vous et recevez un Token Web JSON (JWT) pour accéder aux points de terminaison protégés.

En-têtes de la requête

Corps de la requête

Exemple de requête

curl --location 'http://localhost:8000/api/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "jhon.doe@user.com",
    "password": "ThisIsMyPassword1234",
    "role": "ROLE_MERCHANT_ADMIN"
}'

Réponse de succès

Code de statut: 200 OK

Exemple de réponse de succès

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...."
}

Réponses d'erreur

Détails du Token

Le token JWT retourné contient :

• iat (Émis À : Horodatage de création du token): Émis À : Horodatage de création du token
• exp (Expiration : Horodatage d'expiration du token): Expiration : Horodatage d'expiration du token
• roles: Tableau des rôles utilisateur
• phoneNumber: Numéro de téléphone associé à l'utilisateur

Instructions d'utilisation

1. Envoyer une requête de connexion avec les identifiants corrects
2. Recevoir le token JWT
3. Inclure le token dans l'en-tête Authorization pour les points de terminaison protégés
   • Authorization: Bearer <token>

Recommandations de sécurité

• Stocker le token de manière sécurisée côté client
• Implémenter un mécanisme de rafraîchissement du token
• Vérifier l'expiration du token avant de faire des requêtes
• Ne jamais partager votre token publiquement

Lien de Paiement

Endpoint

POST /api/request-to-pay/payment/link

Description

Ce point de terminaison génère un lien de transaction de paiement qui peut être ouvert dans une nouvelle page ou dans un iframe.

En-têtes de la requête

Corps de la requête

Exemple de requête

curl --location 'http://localhost:8000/api/request-to-pay/payment/link' \
--header 'language: en' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3NDMwMDU2NjgsImV4cCI6MTc0MzE4NTY2OCwicm9sZXMiOlsiUk9MRV9D...' \
--data '{
    "amount": 1.00,
    "user_lang": "en",
    "msisdn": "+22507377932",
    "success": "https://www.success.com",
    "error": "https://www.error.com"
}'

Réponse de succès

Code de statut: 200 OK

Exemple de réponse de succès

{
  "url": "http://app.elyonpay.org/t/CI032667e43abf11?success=https://www.success.com&error=https://www.error.com"
}

Réponses d'erreur

Flux d'Intégration de Paiement

Diagramme de Flux

sequenceDiagram
  participant Customer
  participant Merchant
  participant ElyonPay

  Customer->>Merchant: Finalizes cart
  Customer->>Merchant: Selects "Pay"
  Merchant->>ElyonPay: POST /api/login
  ElyonPay-->>Merchant: Returns JWT token
  Merchant->>ElyonPay: POST /api/request-to-pay/payment/link
  ElyonPay-->>Merchant: Returns payment URL
  Merchant->>Customer: Displays payment page (iframe or redirect)
  Customer->>ElyonPay: Selects payment method
  Customer->>ElyonPay: Completes transaction
  ElyonPay-->>Customer: Shows confirmation popup
      

Étapes Détaillées

1. Sur le Site du Marchand
   • Le client finalise son panier
   • Sélectionne "Payer"
2. Côté Serveur du Marchand
   • Appel de l'endpoint /api/login /api/login
   • Obtention d'un token JWT
3. Génération du Lien de Paiement
   • Appel de POST /api/request-to-pay/payment/link POST /api/request-to-pay/payment/link
   • Réception d'un lien avec ID unique (ex: CM0130679b857c09)
4. Affichage du Paiement
   • Intégration dans une iframe
   • Ou ouverture dans une nouvelle page
5. Processus de Paiement
   • Client sélectionne un moyen de paiement
   • Complète la transaction
   • Popup de confirmation à la fin du paiement

Gestion des Résultats de Paiement

sequenceDiagram
  participant Customer
  participant Merchant
  participant ElyonPay

  Customer->>ElyonPay: Transaction completed
  alt Successful payment
      ElyonPay->>Merchant: Redirect to success URL
  else Failed payment
      ElyonPay->>Merchant: Redirect to error URL
  end
  Merchant->>ElyonPay: GET /api/transactions/[ID_TRANSACTION]
  ElyonPay-->>Merchant: Returns transaction status
  Merchant->>Merchant: Updates order status
  Merchant->>Customer: Shows order confirmation
      

6. Redirections
   • URL de succès en cas de paiement réussi
   • URL d'erreur en cas de problème
   • Important : Doit être une URL côté serveur
7. Vérification Finale
   • Appel GET /api/transactions/[ID_TRANSACTION] GET /api/transactions/[ID_TRANSACTION]
   • Récupération du statut final
   • Mise à jour du statut de la commande

États des Transactions

Liste des États

Diagramme de Transition d'États

stateDiagram-v2
  [*] --> CREATED
  CREATED --> PENDING: Payment initiated
  PENDING --> WAITING_FOR_PAYMENT: Awaiting customer
  WAITING_FOR_PAYMENT --> ACCEPTED: Payment confirmed
  PENDING --> ACCEPTED: Direct approval
  PENDING --> REJECTED: Validation failed
  PENDING --> DECLINED: Payment issue
  WAITING_FOR_PAYMENT --> DECLINED: Payment issue
  WAITING_FOR_PAYMENT --> CANCELLED: User cancellation
  ACCEPTED --> DELIVERED: Funds transferred
  ACCEPTED --> CANCELLED: Administrative action
  REJECTED --> [*]
  DECLINED --> [*]
  CANCELLED --> [*]
  DELIVERED --> [*]
      

Bonnes Pratiques

Sécurité

• Toujours utiliser HTTPS
• Protéger le token JWT
• Vérifier le statut côté serveur
• Ne jamais se fier uniquement à la redirection client

Gestion des Erreurs

• Implémenter des mécanismes de reprise
• Gérer les cas de timeout
• Prévoir des messages clairs pour l'utilisateur

Recommandations Techniques

• Timeout recommandé : 30 secondes
• Vérifier le statut immédiatement après redirection
• Implémenter une file d'attente de vérification

Codes d'Erreur

Erreurs d'Authentification

Erreurs de Transaction

Support

En cas de problème :

• Vérifiez la documentation
• Consultez les logs
• Contactez le support technique