🔗 Intégration API

API Obtenir les détails du paiement

Cet endpoint récupère des informations détaillées sur un paiement spécifique, y compris son statut, ses transactions et les informations associées au portefeuille.

Endpoint

GET /payments/:paymentId

Paramètres d'URL

ParamètreRequisTypeDescriptionExemple
paymentIdOuistringIdentifiant unique du paiement5e68ed190a43a43998c6eeba

Réponse

Exemple

{
  "payment": {
    "id": "87a4c597cb3c15311bdbd547",
    "status": "pending",
    "amountDue": 2000,
    "reachedAmount": 1000,
    "amount": 1000,
    "token": "TND",
    "convertedAmount": 15000,
    "exchangeRate": 1,
    "expirationDate": "2020-10-15",
    "shortId": "-PJfSz90m",
    "link": "https://api.dev.konnect.network/WSlQUtBF8",
    "webhook": "merchant.tech/api/notification_payment",
    "successUrl": "https://dev.konnect.network/gateway/payment-success",
    "failUrl": "https://dev.konnect.network/gateway/payment-failure",
    "orderId": "123456",
    "type": "immediate",
    "details": "paiement de t-shirts",
    "acceptedPaymentMethods": ["wallet", "bank_card", "e-DINAR", "flouci"],
    "receiverWallet": {
      // Détails du portefeuille ici (troncation pour concision)
    },
    "transactions": [
      // Détails des transactions ici (troncation pour concision)
    ]
  }
}

Erreurs courantes

  1. Paiement introuvable

    • Code de statut : 404
    • Cause : paymentId invalide ou inexistant
    • Solution : Vérifiez que l'ID du paiement est correct

  2. Authentification invalide

    • Code de statut : 401
    • Cause : Clé API manquante ou invalide
    • Solution : Assurez-vous que la clé API valide est incluse dans les en-têtes

  3. Paiement expiré

    • Statut : Le paiement existe mais a expiré
    • Solution : Vérifiez le champ expirationDate et initiez un nouveau paiement si nécessaire

Statut du paiement

Vous devez vous fier au statut du paiement, et non au statut de la transaction.

Le statut du paiement peut être déterminé en vérifiant deux champs :

  1. Statut du paiement (payment.status) :

    • completed : Le paiement a été effectué avec succès
    • pending : Le paiement a échoué ou n'a pas encore été tenté

  2. Statut de la transaction (payment.transactions[].status) :

    • success : La transaction a réussi
    • D'autres statuts indiquent divers échecs ou états en attente

Test

Bonnes pratiques

  1. Vérification régulière du statut

    • Implémentez un polling avec des intervalles appropriés
    • Respectez les limites de taux
    • Utilisez des webhooks pour des mises à jour en temps réel

  2. Vérification des transactions

    • Vérifiez toujours payment.status et transaction status
    • Comparez reachedAmount avec le montant attendu pour les paiements partiels
    • Validez la devise et le montant de la transaction

  3. Gestion des erreurs

    • Implémentez une gestion appropriée des erreurs pour toutes les réponses API
    • Enregistrez les identifiants de paiement et de transaction pour le dépannage
    • Surveillez les échecs de transaction pour détecter des tendances

Limites de taux

  • Limite standard : 100 requêtes par minute
  • Implémentez un backoff exponentiel pour le polling
  • Privilégiez les webhooks pour des mises à jour en temps réel plutôt que du polling continu
WebhookOverview