🔗 Intégration API

API d'initiation de paiement

Cet endpoint initie un nouveau paiement et retourne une URL de paiement où le client peut finaliser la transaction.

Endpoint

POST /payments/init-payment

En-têtes

Nom	Requis	Type	Description
x-api-key	Oui	string	Clé API unique identifiant votre organisation (obtenez-la ici)

Exemple de corps de requête

{
  "receiverWalletId": "5f7a209aeb3f76490ac4a3d1",
  "token": "TND",
  "amount": 10000,
  "type": "immediate",
  "description": "description du paiement",
  "acceptedPaymentMethods": ["wallet", "bank_card", "e-DINAR"],
  "lifespan": 10,
  "checkoutForm": true,
  "addPaymentFeesToAmount": true,
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "22777777",
  "email": "john.doe@gmail.com",
  "orderId": "1234657",
  "webhook": "https://merchant.tech/api/notification_payment",
  "silentWebhook": true,
  "successUrl": "https://gateway.sandbox.konnect.network/payment-success",
  "failUrl": "https://gateway.sandbox.konnect.network/payment-failure",
  "theme": "dark"
}

Paramètres du corps de requête

Option	Type	Description
receiverWalletId (obligatoire)	string	ID du portefeuille Konnect du bénéficiaire du paiement (disponible sur le tableau de bord)
token	string	Devise du paiement : ⁠TND, ⁠EUR ou ⁠USD. Les paiements non-TND sont automatiquement convertis
amount (obligatoire)	number	Montant du paiement (en millimes pour TND / centimes pour EUR et USD)
type	string	Type de paiement : ⁠immediate (paiement total) ou ⁠partial (autorise les paiements partiels)
description	string	Description du paiement visible par le payeur sur la page de paiement
acceptedPaymentMethods	array	Méthodes de paiement acceptées : ⁠wallet, ⁠bank_card, ⁠e-DINAR, ⁠flouci. Par défaut : ⁠["wallet","bank_card","e-DINAR"]
lifespan	number	Durée d’expiration du lien de paiement en minutes
checkoutForm	boolean	Indique si le payeur doit remplir un formulaire avant le paiement
addPaymentFeesToAmount	boolean	Si vrai, ajoute les frais Konnect au montant payé. Par défaut : ⁠false
firstName	string	Prénom du payeur
lastName	string	Nom du payeur
phoneNumber	string	Numéro de téléphone du payeur
email	string	Adresse e-mail du payeur
orderId	string	Identifiant personnalisé de la commande
webhook	string	URL pour la notification de paiement (requête GET)
silentWebhook	boolean	Si vrai, appelle le webhook sans rediriger le payeur
successUrl	string	URL de redirection en cas de paiement réussi (ignorée si le webhook est actif et non silencieux)
failUrl	string	URL de redirection en cas d’échec du paiement (ignorée si le webhook est actif et non silencieux)
theme	string	Thème du portail de paiement : ⁠light ou ⁠dark. Par défaut : ⁠light

Réponse

Exemple

{
  "payUrl": "https://dev.konnect.network/admin/pay?payment_ref=5e870a611631215d633fe083",
  "paymentRef": "60889219a388f75c94a943ec"
}

Paramètres de réponse

Paramètre	Type	Description
payUrl	string	URL de la passerelle de paiement où le client peut finaliser le paiement
paymentRef	string	Référence unique du paiement

Test

Bonnes pratiques

Implémentez toujours une gestion correcte des erreurs pour les appels API et les notifications webhook
Définissez une durée de vie appropriée pour les paiements en fonction de vos besoins commerciaux
Utilisez silentWebhook lorsque vous devez traiter les résultats de paiement sans redirection utilisateur
Stockez paymentRef pour une référence future et la réconciliation

Limites de taux

Limite standard : 100 requêtes par minute
Contactez le support pour augmenter cette limite si nécessaire

Introduction Webhook