Aller au contenu principal

🚀 Démarrage Rapide

Bienvenue dans la documentation développeur d'Efaina. Cette page rassemble en un seul endroit les actions indispensables pour tester l'intégration : récupérer un token, créer un wallet puis lancer un paiement.

Prérequis​

Avant de commencer, vérifiez que vous disposez de :

  • Un compte Efaina actif avec les droits dĂ©veloppeur
  • Un environnement de dĂ©veloppement (Node.js, Python, PHP, etc.)
  • Un outil de test API (Postman, Insomnia, curl…)
  • Une URL HTTPS accessible pour recevoir les webhooks (un tunnel type ngrok convient pour les tests)

Étape 1 : Génération du Token d'Accès​

Important

La majorité des endpoints nécessitent un token d'accès porteur du scope adéquat (Sandbox ou Production).

  1. Connectez-vous Ă  votre tableau de bord Efaina.
  2. Rendez-vous dans Développeur > Clé API.
  3. Générez un token (sandbox ou production).
  4. Stockez-le dans votre gestionnaire de secrets, en dehors du dépôt Git.

Étape 2 : Création de votre Premier Wallet​

Un wallet (portefeuille virtuel) est nécessaire pour recevoir et gérer vos paiements.

Via l'Interface Web​

  1. Dans votre tableau de bord > Wallets
  2. Cliquez sur Créer un wallet et remplissez les informations requises

Via l'API​

curl --request POST \
    "https://efn.efaina.com/api/public/v1/wallets/store" \
    --header "Authorization: Bearer VOTRE_TOKEN" \
    --header "Accept: application/json" \
    --form "phone=034----------" \
    --form "last_name=Randria" \
    --form "first_name=Lova" \
    --form "city=Antananarivo" \
    --form "address=Lot II B 23" \
    --form "company=MyCompany SARL" \
    --form "cash_out[info][name]=Randria Lova" \
    --form "cash_out[info][phone]=0341234567" \
    --form "cash_out[info][first_choice]=mobile_money"

L'objet cash_out définit où partiront les fonds lors d'un retrait : renseignez-le avec soin. Les champs non listés dans la référence sont ignorés.

Étape 3 : Premier Paiement de Test​

Création d'un Checkout​

curl --request POST \
    "https://efn.efaina.com/api/public/v1/pay/create-checkout" \
    --header "Authorization: Bearer VOTRE_TOKEN" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"amount\": \"125000\",
    \"comment\": \"Invoice #INV-2024-001\",
    \"wallet_id\": \"a3bb189e-b1be-49d4-aec2-a9b02d7a5c20\",
    \"company\": \"MyCompany SARL\",
    \"return_urls\": {
        \"return_to_merchant_url\": \"https:\\/\\/merchant.example.com\\/payment\\/callback\"
    }
}"
{
  "statusHttp": "success",
  "message": "Success",
  "response": {
    "status": "success",
    "checkout_url": "https://pay.example.com/checkout?token=eyJ0b2tlbiI6...",
    "transaction": "72b46ff8-1bc2-4a33-bc63-022eb743a4a5"
  }
}

Redirigez votre client vers checkout_url, et conservez transaction : c'est l'identifiant que vous retrouverez dans les webhooks et sur GET /details-transaction/{transaction}. Le lien de paiement expire au bout d'une heure.

Étape 4 : Configuration des Webhooks​

Pour recevoir les notifications en temps réel :

  1. Dans votre tableau de bord > DĂ©veloppeur > Webhook
  2. Ajoutez votre URL d'endpoint (ex: https://api.votresite.com/webhooks/efaina)
  3. Renseignez un token de sécurité et stockez-le côté serveur : nous le renverrons dans l'en-tête Webhook-Token
  4. Répondez rapidement (idéalement sous quelques secondes) et traitez en asynchrone : un endpoint lent finit par expirer côté appelant
Audit

Logguez systématiquement les payloads reçus (masquez les données sensibles) pour faciliter le support.

Étape 5 : Test Complet​

  1. Initiez un paiement via le checkout_url récupéré.
  2. Validez la transaction avec les identifiants de test.
  3. Confirmez la réception du webhook : checkout.completed puis transaction.completed.
  4. VĂ©rifiez l'historique dans votre dashboard.
  5. Consultez GET /api/public/v1/details-transaction/{transaction} pour vérifier la cohérence avec votre base.
Ne livrez jamais sur le seul retour navigateur

Le client peut fermer son onglet avant la redirection. Seul l'événement transaction.completed — ou une relecture de la transaction — atteste du paiement.

Prochaines Étapes​

Maintenant que vous avez les bases :

Conseil

Commencez toujours par l'environnement de test (sandbox) avant la production.

Besoin d'aide ?

Notre Ă©quipe support est joignable via le chat du dashboard ou Ă  l'adresse contact@efaina.com.