DocumentationAPI

Documentation API

CareWallet Payment Gateway

CareWallet Payment Gateway API

Intégrez CareWallet comme solution de paiement

Simple & Rapide

3 endpoints, 5 minutes d'intégration

Sécurisé

PIN + Webhooks signés

Multi-plateforme

JS, Python, PHP, etc.

🚀 Démarrage Rapide
Configuration de base en 3 étapes
1

Obtenez vos identifiants

Contactez l'équipe CareWallet pour obtenir votre merchant_id et api_key

2

Configurez votre backend

Ajoutez l'appel API pour créer des paiements

3

Recevez les notifications

Configurez votre webhook pour être notifié des paiements

Authentification

Toutes les requêtes API nécessitent une API Key dans le header :

X-API-Key: votre_api_key
Content-Type: application/json

⚠️ Important : Ne jamais exposer votre API Key côté client (frontend). Utilisez toujours votre backend.

📡 Endpoints API

POST
/functions/initiateMerchantPayment
Créez une demande de paiement et obtenez un lien sécurisé

Body (JSON)

{
  "merchant_id": "votre_merchant_id",
  "amount": 50000,
  "currency": "CDF",
  "reference": "ORDER-2024-001",
  "description": "Consultation médicale",
  "callback_url": "https://votre-app.com/success",
  "webhook_url": "https://votre-app.com/webhook",
  "metadata": {
    "order_id": "12345",
    "customer_email": "patient@example.com"
  }
}

Paramètres

merchant_id
Requis
amount
Requis
reference
Requis
description
Requis
callback_url
Optionnel
webhook_url
Optionnel
GET
/functions/checkPaymentStatus
Vérifiez le statut actuel d'un paiement

Query Parameters

GET /functions/checkPaymentStatus?payment_id=pay_xxx

Réponse

{
  "success": true,
  "payment": {
    "payment_id": "pay_1234567890_abc",
    "merchant_reference": "ORDER-2024-001",
    "amount": 50000,
    "status": "paye",
    "created_at": "2024-05-24T14:00:00Z",
    "paid_at": "2024-05-24T14:05:32Z",
    "transaction_id": "tx_9876543210"
  }
}

Statuts possibles

en_attente
En attente du paiement
paye
Paiement réussi
expire
Lien expiré (30 min)
annule
Paiement annulé
Webhooks
Recevez des notifications en temps réel

CareWallet vous notifie automatiquement lorsqu'un paiement est complété :

Événement : payment.completed

POST https://votre-app.com/webhooks/payment
Content-Type: application/json
X-CareWallet-Signature: sha256=...

{
  "event": "payment.completed",
  "payment_id": "pay_1234567890_abc",
  "merchant_reference": "ORDER-2024-001",
  "amount": 50000,
  "commission": 1250,
  "net_amount": 48750,
  "transaction_id": "tx_9876543210",
  "status": "completed",
  "paid_at": "2024-05-24T14:05:32Z",
  "metadata": {
    "order_id": "12345"
  }
}

Gérer le webhook (Node.js)

app.post('/webhooks/payment', (req, res) => {
  const { payment_id, status, merchant_reference, metadata } = req.body;
  
  if (status === 'completed') {
    // Marquer la commande comme payée
    updateOrderStatus(metadata.order_id, 'paid');
    console.log(`✅ Paiement ${payment_id} réussi`);
  }
  
  res.status(200).json({ received: true });
});
❌ Codes d'Erreur
200
Succès
400
Paramètres manquants ou invalides
401
API Key manquante ou invalide
403
Marchand inactif ou suspendu
404
Paiement non trouvé
500
Erreur serveur
Sécurité - Bonnes Pratiques
  • Toujours faire les appels API depuis votre backend
  • Ne jamais exposer votre API Key côté client
  • Vérifier les signatures des webhooks
  • Utiliser HTTPS pour tous vos endpoints
  • Valider le statut via checkPaymentStatus avant de livrer un service
  • Stocker les payment_id pour la traçabilité

Besoin d'aide ou de vos identifiants marchands ?

Contacter l'équipe CareWallet