Callbacks

1. Configuration

Renseignez votre Callback URL depuis votre tableau de bord partenaire (onglet Callback URL). Il doit s'agir d'une URL publique accessible depuis internet (HTTPS recommandé).

2. Politique de relance

Si votre endpoint ne répond pas avec un HTTP 200, OPENPAY relance automatiquement la notification selon le calendrier suivant :

Après 4 tentatives infructueuses, la livraison est abandonnée. Vous pouvez toujours vérifier manuellement le statut d'une transaction via l'endpoint Statut de paiement.

3. Format du payload

OPENPAY envoie une requête POST avec le header Content-Type: application/json et le corps suivant :

{
  "reference": "PTXN26042237B99A5D9",
  "amount": "5000",
  "currency": "XAF",
  "paymentPhoneNumber": "242066203420",
  "provider": "MTN",
  "type": "payment",
  "status": "success",
  "message": "Paiement effectué avec succès."
  "customer": {
    "name": "Jean Dupont",
    "phone": "242066203420"
  },
  "metadata": {
    "order_id": "123456",
    "id_cv": "dc769729-78f6-4ae9-a882-ee5830f156d9"
  }
}

4. Réponse attendue

Votre endpoint doit retourner un HTTP 200 dans les 10 secondes. Le corps de la réponse n'est pas obligatoire, mais un JSON est conseillé pour faciliter le débogage.

{ "success": true }

5. Exemples d'implémentation

app.post('/webhook/openpay', (req, res) => {
  const data = req.body;

  if (data.status === 'success') {
    // Livrer le produit / activer le service
    console.log('Paiement reçu :', data.reference, data.amount, data.currency);

    // Exemple : utiliser vos metadata personnalisées
    const { order_id } = data.metadata || {};
    if (order_id) {
      // Marquer la commande comme payée dans votre BDD
    }
  }

  // Toujours retourner 200 pour confirmer la réception
  res.status(200).json({ success: true });
});

<?php
$payload = json_decode(file_get_contents('php://input'), true);

if ($payload['status'] === 'success') {
    $orderId = $payload['metadata']['order_id'] ?? null;
    // Marquer la commande comme payée
}

http_response_code(200);
echo json_encode(['success' => true]);

@app.route('/webhook/openpay', methods=['POST'])
def openpay_webhook():
    data = request.get_json()

    if data.get('status') == 'success':
        order_id = data.get('metadata', {}).get('order_id')
        # Traiter la commande...

    return jsonify({"success": True}), 200

6. Bonnes pratiques

• Répondre toujours avec HTTP 200 dès réception, avant tout traitement métier long.
• Vérifier le champ status avant de délivrer un service (success uniquement).
• Utiliser le champ metadata pour passer vos identifiants internes (ex : order_id, user_id) lors de la création du paiement.
• Utiliser la page de paramètres partenaire pour tester votre callback URL avant la mise en production.
• En cas de doute, vous pouvez toujours interroger l'endpoint Statut de paiement pour confirmer l'état d'une transaction.