Callbacks

DarePay notifie votre application du résultat final de chaque paiement. Voici comment le recevoir, le confirmer et le traiter une seule fois.

Recevoir le callback

Votre application doit fournir une URL de callback accessible en HTTPS. DarePay appelle cette URL en POST lorsqu'un paiement atteint un état final.

Exemple d'URL

POST https://votre-application.example.com/api/darepay/callback

Payload envoyé par DarePay

JSON

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

Champ	Description
`payment_id`	Identifiant interne du paiement dans DarePay.
`reference`	Référence métier fournie par votre application.
`transaction_id`	Identifiant unique de la transaction.
`status`	Résultat final : `SUCCESS` ou `FAILED`.
`amount`	Montant du paiement.
`currency`	Devise du paiement.
`failure_reason`	Motif de l'échec lorsqu'il est disponible. `null` en cas de succès.

Confirmer la réception

DarePay attend une confirmation explicite après chaque callback final. Une réponse HTTP 200 seule ne suffit pas : votre endpoint doit répondre rapidement, en HTTP 200, avec un JSON conforme au contrat ci-dessous.

Élément	Valeur attendue
HTTP	200 OK
`received`	`true`
`reference`	La même référence métier que celle reçue dans le callback
`transaction_id`	Le même identifiant de transaction que celui reçu dans le callback

Réponse attendue

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

{
  "received": true,
  "reference": "CMD20264AK",
  "transaction_id": "PAY1109261276813"
}

Validation de la réponse

DarePay considère le callback comme confirmé uniquement si votre serveur répond en HTTP 200.
La réponse JSON doit contenir received à true.
reference doit correspondre exactement à la référence envoyée par DarePay.
transaction_id doit correspondre exactement à l'identifiant de transaction envoyé par DarePay.
Toute autre réponse, y compris un HTTP 200 avec un JSON incorrect, est considérée comme non confirmée.

Attention aux espacesLa correspondance est exacte : " CMD2026001" (avec une espace initiale) n'est pas "CMD2026001". Renvoyez les valeurs reçues telles quelles, sans les retaper.

Nouvelles tentatives en cas d'échec

Si DarePay ne reçoit pas de confirmation valide, il renvoie le callback. Il effectue au maximum trois envois au total.

1Tentative 1Envoi initial du callback.

2Tentative 2Si la première n'est pas confirmée.

3Tentative 3Dernière tentative si la deuxième n'est pas confirmée.

ArrêtAprès la troisième tentative, DarePay arrête automatiquement les envois.

Si aucun callback n'a pu être confirmé, le paiement reste consultable : utilisez GET /api/payments/{reference}/status pour connaître son statut.

Idempotence

Votre application peut recevoir plusieurs fois le même callback. Elle ne doit jamais effectuer deux fois la même opération métier (livraison, crédit de compte, envoi de reçu…).

La méthode la plus sûre : ne mettre à jour la commande que si elle est encore PENDING, dans une seule requête atomique, puis confirmer la réception dans tous les cas.

Un callback déjà traité doit tout de même recevoir la réponse de confirmation : sinon DarePay le considère comme non confirmé et le renvoie.

Contrôles de sécurité et de cohérence

Avant de modifier le paiement et de notifier votre application, DarePay vérifie côté Gateway les informations essentielles du résultat reçu :

Présence de transactionId, merchantReferenceId, status et code.
Statut final limité à SUCCESS ou FAILED.
Correspondance du paiement avec la référence et l'identifiant de transaction.
Correspondance du montant avec le montant du paiement.
Correspondance du compte d'opération utilisé pour le paiement.
Correspondance de l'opérateur et du type d'opération PAYMENT.
Correspondance du numéro client lorsque celui-ci est fourni.
Protection contre le remplacement d'un statut final SUCCESS par FAILED, ou de FAILED par SUCCESS.
Gestion idempotente des callbacks déjà traités.

Ces contrôles sont effectués par DarePay. Ils ne nécessitent aucune information technique sur l'infrastructure de paiement sous-jacente de la part de votre application.

Tester votre réponse

Collez la réponse que renvoie votre endpoint au callback ci-dessous. Le validateur applique les règles de confirmation de DarePay et simule les envois.

Scénarios :

Callback envoyé par DarePay POST

{
  "payment_id": 18,
  "reference": "CMD20264AK",
  "transaction_id": "PAY1109261276813",
  "status": "SUCCESS",
  "amount": "1000.00",
  "currency": "XAF",
  "failure_reason": null
}

Réponse de votre serveur

Code HTTP

1Tentative 1Envoi initial

2Tentative 2Si non confirmé

3Tentative 3Dernière tentative

FinDarePay cesse les envois pour ce callback.