Référence API

L'API DarePay est organisée autour de routes REST simples. Elle accepte des corps JSON, renvoie des réponses JSON et utilise les codes HTTP standards.

Les routes protégées exigent l'en-tête X-API-Key. Chaque paiement est identifié par votre référence métier : elle sert à l'initier, à consulter son statut et à le rapprocher du callback.

X-API-Key: VOTRE_CLE_API
Content-Type: application/json
Accept: application/json

Erreurs

DarePay utilise les codes de réponse HTTP pour indiquer le résultat d'une requête. Les codes 2xx signalent un succès, les 4xx une erreur liée aux données envoyées, et 500 une erreur interne.

Initialiser un paiement

Cette route permet à votre application d'initier une nouvelle transaction de paiement. DarePay valide la requête, initialise la transaction et renvoie son statut initial.

• X-API-KeystringObligatoire

  Clé d'authentification attribuée à votre application. Renseignez-la dans le panneau de requête.

• Content-TypestringObligatoire

  Utiliser application/json.

• AcceptstringRecommandé

  Utiliser application/json.

• referencestringObligatoire

  Référence métier unique de votre application. Maximum 10 caractères.
• amountnumberObligatoire

  Montant du paiement. La valeur doit être supérieure ou égale à 200.
• currencystringFacultatif

  Devise du paiement. Exemple : XAF.

  Laisser vide pour l'omettre
• customer_msisdnstringObligatoire

  Numéro de téléphone du client à débiter.

  Numéro du client
• operator_codeenumObligatoire

  Opérateur de paiement. Valeurs acceptées : AIRTEL_MONEY ou MOOV_MONEY.

  AIRTEL_MONEY MOOV_MONEY Autre (tester une erreur)

• successboolean

  Indique que la requête a été traitée.

• messagestring

  Message lisible, par exemple « Paiement initié avec succès. »

• paymentobject

  Le paiement créé.

  • idinteger

    Identifiant interne du paiement dans DarePay.

  • referencestring

    Référence métier fournie par votre application.

  • transaction_idstring

    Identifiant unique de la transaction. À conserver.

  • statusenum

    Statut initial, souvent PENDING.

  • amountstring

    Montant du paiement, au format décimal ("10000.00").

  • currencystring

    Devise du paiement.

Consulter le statut d'un paiement

Cette route récupère le statut actuel d'un paiement à partir de la référence métier utilisée lors de l'initiation. Utilisez-la en cas de doute : après une erreur réseau, une erreur 500 ou un callback attendu qui tarde.

• referencestringObligatoire

  La référence métier transmise dans POST /api/payments.

  Référence du paiement

• successboolean

  Indique que la requête a été traitée.

• paymentobject

  Le paiement, avec les mêmes champs que la réponse d'initiation : id, reference, transaction_id, status, amount, currency.

Callback de résultat

Votre application fournit une URL de callback accessible en HTTPS. DarePay appelle cette URL lorsqu'un paiement atteint un état final. C'est la notification principale du résultat.

• payment_idinteger

  Identifiant interne du paiement dans DarePay.

• referencestring

  Référence métier fournie par votre application.

• transaction_idstring

  Identifiant unique de la transaction.

• statusenum

  Résultat final : SUCCESS ou FAILED.

• amountstring

  Montant du paiement.

• currencystring

  Devise du paiement.

• failure_reasonstring | null

  Motif de l'échec lorsqu'il est disponible. null en cas de succès.

• HTTP200 OK

  Répondez rapidement après réception et traitement de la notification.

• receivedboolean

  Doit valoir true.

• referencestring

  La même référence métier que celle reçue dans le callback, à l'identique.

• transaction_idstring

  Le même identifiant de transaction que celui reçu dans le callback.

{
  "payment_id": 15,
  "reference": "CMD2026001",
  "transaction_id": "PAY1009261274771",
  "status": "SUCCESS",
  "amount": "10000.00",
  "currency": "XAF",
  "failure_reason": null
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true,
  "reference": "CMD2026001",
  "transaction_id": "PAY1009261274771"
}

Envoyer de l'argent e-commerce

Réservée aux applications en mode e-commerce. L'argent d'un paiement réussi est conservé sur le compte DarePay : cette route l'envoie, en une seule requête, sur le mobile money d'un ou plusieurs destinataires (vendeur, livreur, client…). Comprendre le principe et activer le mode

• referencestringObligatoire

  La référence du paiement d'où vient l'argent, celle utilisée dans POST /api/payments.

• reference_lotstringObligatoire

  Votre référence unique pour cette demande. Lettres, chiffres, - et _, 100 caractères maximum. Renvoyer la même requête avec la même référence ne renvoie jamais l'argent une deuxième fois.

• destinatairesarrayObligatoire

  De 1 à 20 destinataires, chacun avec un numéro différent.

  • numerostringObligatoire

    Numéro mobile money, par exemple 074123456. Airtel Money en 07…, Moov Money en 06….

  • operateurenumObligatoire

    AIRTEL_MONEY ou MOOV_MONEY, le même que celui du paiement.

  • montantnumberObligatoire

    Montant en XAF entiers, ou un pourcentage du montant payé si type_montant vaut POURCENTAGE.

  • type_montantenumFacultatif

    MONTANT (par défaut) ou POURCENTAGE.

  • type_destinataireenumFacultatif

    VENDEUR, ACHETEUR ou AUTRE, pour votre suivi.

• HTTP201

  Demande prise en charge. Le résultat est dans data.statut.

• HTTP200

  Cette reference_lot a déjà été traitée : le résultat existant est renvoyé (deja_traite: true).

• dataobject

  Le résultat de la demande.

  • statutenum

    SUCCESS (tout est envoyé), PARTIEL, FAILED (rien n'est envoyé) ou PROCESSING (en vérification, ne pas renvoyer).

  • montant_totalinteger

    Total demandé, en XAF.

  • montant_restantinteger

    Montant encore disponible sur ce paiement.

  • destinatairesarray

    Pour chacun : reference_sortie, numero, montant, statut, code_erreur et message.

{
  "success": true,
  "message": "Toutes les sorties ont été effectuées.",
  "data": {
    "reference_paiement": "CMD2026001",
    "reference_lot": "LIV-CMD2026001",
    "statut": "SUCCESS",
    "deja_traite": false,
    "montant_total": 9000,
    "montant_restant": 500,
    "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": "SUCCESS",
        "code_erreur": null,
        "message": "Sortie effectuée."
      }
    ]
  }
}

Consulter un envoi e-commerce

Renvoie l'état actuel d'une demande d'envoi, au même format que la réponse de POST …/releases. Cette route n'envoie rien : utilisez-la pour suivre une demande PROCESSING ou pour vérifier après une coupure réseau.

• referencestringObligatoire

  La référence du paiement.

• reference_lotstringObligatoire

  La référence de la demande d'envoi.

{
  "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
  }
}