Envoi d'argent (e-commerce)

Le principe

Avec une application classique, DarePay répartit automatiquement chaque paiement entre des bénéficiaires fixés à l'avance. Une boutique en ligne a d'autres besoins : on ne sait pas toujours, au moment du paiement, qui devra recevoir l'argent ni quand. Par exemple, le vendeur n'est payé qu'une fois la commande livrée, ou le client est remboursé si l'article manque.

Le mode e-commerce répond à ce besoin. L'argent payé par vos clients est d'abord conservé sur le compte DarePay. Vous décidez ensuite, avec un simple appel à l'API, à qui envoyer l'argent, combien et à quel moment.

Activer le mode e-commerce

Le mode e-commerce ne s'active pas depuis l'API. C'est l'équipe DarePay qui le met en place pour votre application, après échange avec vous.

Ce qui change pour votre application

Comment circule l'argent

Chaque paiement réussi devient une petite « réserve » d'argent, attachée à sa référence. Vos envois puisent dans cette réserve, jamais au-delà. Cliquez sur une étape pour la situer dans le schéma.

Le montant disponible

Quand un paiement réussit, DarePay prélève ses frais de service (selon le taux convenu avec vous à l'activation). Ce qui reste est le montant disponible : c'est le maximum que vous pouvez envoyer pour ce paiement, en une ou plusieurs fois.

Les conditions à respecter

DarePay vérifie chaque demande avant d'envoyer le moindre franc. Si une seule condition n'est pas respectée, toute la demande est refusée et aucun envoi n'est fait.

• Le paiement doit être réussi (SUCCESS). Un paiement PENDING ou FAILED ne permet aucun envoi.
• Le total demandé ne doit pas dépasser le montant disponible restant pour ce paiement.
• Les destinataires doivent utiliser le même opérateur que le paiement : un paiement Airtel Money ne peut être envoyé que vers des numéros Airtel Money, et un paiement Moov Money vers des numéros Moov Money.
• Le numéro doit correspondre à l'opérateur : numéros Airtel Money en 07…, numéros Moov Money en 06… (9 chiffres, par exemple 074123456).
• De 1 à 20 destinataires par demande.
• Un même numéro ne peut pas apparaître deux fois dans la même demande. Additionnez les montants si besoin.
• Les montants sont en XAF entiers, sans centimes. Un pourcentage accepte jusqu'à 2 décimales.
• Chaque demande porte une référence d'envoi unique (reference_lot), choisie par votre application.
• Vous ne pouvez envoyer que l'argent des paiements de votre propre application.

Envoyer de l'argent

Une seule requête peut envoyer de l'argent à plusieurs destinataires. Le paiement concerné est désigné par sa référence dans l'URL, celle que vous avez utilisée lors de POST /api/payments. Les en-têtes sont les mêmes que pour les autres routes (authentification).

Champs de la requête

Exemple de requête

Le paiement CMD2026001 de 10 000 XAF a réussi (9 500 XAF disponibles). La commande est livrée : on paie le vendeur et le livreur.

{
  "reference_lot": "LIV-CMD2026001",
  "destinataires": [
    {
      "numero": "074123456",
      "operateur": "AIRTEL_MONEY",
      "montant": 8000,
      "type_destinataire": "VENDEUR"
    },
    {
      "numero": "077987654",
      "operateur": "AIRTEL_MONEY",
      "montant": 1000,
      "type_destinataire": "AUTRE"
    }
  ]
}

{
  "reference_lot": "LIV-CMD2026001",
  "destinataires": [
    {
      "numero": "074123456",
      "operateur": "AIRTEL_MONEY",
      "montant": 80,
      "type_montant": "POURCENTAGE"
    },
    {
      "numero": "077987654",
      "operateur": "AIRTEL_MONEY",
      "montant": 10,
      "type_montant": "POURCENTAGE"
    }
  ]
}

Lire la réponse

Les envois sont traités immédiatement : la réponse contient déjà le résultat de chaque destinataire. Il n'y a pas de callback pour les envois.

{
  "success": true,
  "message": "Certaines sorties n’ont pas pu être effectuées. Consultez le détail par destinataire.",
  "data": {
    "reference_paiement": "CMD2026001",
    "reference_lot": "LIV-CMD2026001",
    "statut": "PARTIEL",
    "deja_traite": false,
    "montant_total": 9000,
    "montant_restant": 1500,
    "devise": "XAF",
    "date_demande": "2026-10-02T10:15:04+01:00",
    "date_traitement": "2026-10-02T10:15:07+01:00",
    "destinataires": [
      {
        "position": 1,
        "reference_sortie": "S7KQ2M9XA",
        "numero": "074123456",
        "operateur": "AIRTEL_MONEY",
        "type_destinataire": "VENDEUR",
        "montant": 8000,
        "statut": "SUCCESS",
        "code_erreur": null,
        "message": "Sortie effectuée."
      },
      {
        "position": 2,
        "reference_sortie": "SP3TZ81BD",
        "numero": "077987654",
        "operateur": "AIRTEL_MONEY",
        "type_destinataire": "AUTRE",
        "montant": 1000,
        "statut": "FAILED",
        "code_erreur": "INVALID_RECIPIENT",
        "message": "Ce numéro ne peut pas recevoir le transfert. Vérifiez-le puis réessayez avec une nouvelle reference_lot."
      }
    ]
  }
}

Statuts d'un envoi

Statut global de la demande

Il se lit dans le champ data.statut.

Statut de chaque destinataire

Il se lit dans le champ destinataires[].statut.

Consulter un envoi

Cette route renvoie l'état actuel d'une demande d'envoi, au même format que la réponse ci-dessus. Elle ne déclenche aucun envoi : vous pouvez l'appeler autant de fois que nécessaire, par exemple pour suivre une demande PROCESSING.

Erreurs

Quand une demande est refusée, aucun envoi n'a été fait. La réponse contient un code stable que votre application peut tester, et un message lisible.

{
  "success": false,
  "code": "INSUFFICIENT_BALANCE",
  "message": "Le total demandé (12000 XAF) dépasse le montant disponible (9500 XAF).",
  "details": {
    "montant_demande": 12000,
    "montant_disponible": 9500
  }
}

Demande refusée

Échec d'un destinataire

Quand la demande est acceptée mais qu'un envoi échoue, le motif est dans destinataires[].code_erreur.

Que faire en cas de doute ?

La reference_lot vous protège des doublons : une même référence n'envoie jamais l'argent deux fois. Renvoyer exactement la même requête est donc sans risque.

Simuler une répartition

Saisissez un paiement et vos destinataires : le simulateur applique les mêmes règles de calcul que DarePay. Tout est calculé dans votre navigateur : rien n'est envoyé.

Checklist e-commerce

À valider en plus de la checklist de mise en production. Votre progression est enregistrée dans ce navigateur.