Aller au contenu
konnect
English

Environnement de développement : contenu en cours de rédaction, rien ne pointe vers la production.

Sommaire de la documentation

Changelog

Les changements de l'API et du portail, du plus récent au plus ancien.

Chaque modification de l'OpenAPI v3 est relevée ici avant publication : la CI refuse un portail dont la référence est plus ancienne que l'OpenAPI du dépôt.

API v3 : chronologie des paiements et historique des webhooks (lot 2.1b)

  • GET /payments/{reference}/timeline (session ou clé API) : chaque fait du paiement dans l'ordre (création, ouvertures du checkout, choix du prestataire, tentatives et changements de statut, callbacks, retours du payeur, statut final, anomalies, e-mails, webhooks et chaque appel HTTP), pagination par curseur, filtre category (répétable). La réponse donne aussi les tentatives avec leur résultat normalisé et les envois de webhooks avec chaque essai.
  • GET /admin/payments/{reference}/timeline (administration Konnect uniquement) : la même vue avec les réponses brutes des prestataires, masquées.
  • GET /payments/{reference} gagne result : statut final, prestataire, failureCode (liste fermée), code d'autorisation, moyen de paiement masqué, tentatives, durée et merchantConfirmation avec sa raison. Le corps des webhooks ne porte pas result.
  • GET /checkout/{reference} accepte view (payment par défaut, result, attempt) : seul payment compte comme une ouverture du checkout.
  • GET /checkout/{reference}/return?outcome=success|fail (public) enregistre le retour du payeur et le redirige vers l'URL de succès ou d'échec du marchand.
  • POST /payments/{reference}/cancel accepte un reason facultatif. POST /organisations/{id}/webhooks/deliveries/{deliveryId}/retry rejoue désormais tout envoi qui n'est pas en attente, une fois, comme essai manuel (409 webhook_delivery_not_failed avant ; 409 webhook_delivery_pending maintenant). Les envois gagnent lastOutcome, nextRetryAt et manualTries.

API v3 : checkout hébergé sur le moteur (lot 2.2)

  • Checkout (public) : GET /checkout/{reference}/attempts/{attemptId} réaffiche une tentative (type, statut, URL de redirection, QR code ou paramètres de formulaire) ; GET /checkout/{reference}/logo sert le logo du compte de paiement, vers lequel pointe merchant.logoUrl.
  • Le retour navigateur d'un prestataire (GET /callbacks/{provider}/{attemptId}) redirige désormais vers la page de résultat avec ?attempt=<attemptId>.
  • Les routes publiques du checkout et des retours prestataires sont limitées par adresse IP et par référence de paiement (par tentative pour les retours) et répondent 429 rate_limited avec Retry-After.

API v3 : console d'administration, organisations (lot 1.7)

  • GET /admin/organisations et GET /admin/organisations/{id} : liste et fiche des organisations avec leur statut (KYB, contrat, canCollect), réservées à l'équipe Konnect (administration, support, conformité).

API v3 : paiements, tentatives et webhooks (lot 2.1)

  • Paiements : POST /payments (clé API, ou session avec organisationId ; en-tête Idempotency-Key pris en charge) renvoie la référence (24 caractères hexadécimaux) et payUrl ; GET /payments, GET /payments/{reference}, POST /payments/{reference}/cancel, GET /payments/{reference}/attempts avec la chronologie de chaque tentative.
  • Checkout (public) : GET /checkout/{reference}, POST /checkout/{reference}/attempts, GET /checkout/{reference}/status. Retours des prestataires sur GET|POST /callbacks/{provider}/{attemptId}.
  • Webhooks : URL sous /organisations/{id}/webhooks avec un secret de signature affiché une seule fois, journal des envois et renvoi. La signature Konnect-Signature: t=<unix>,v1=<hex> est définitive (ADR 0008) ; le guide n'est plus prévisionnel. Événements payment.succeeded, payment.failed, payment.expired, payment.canceled, attempt.duplicate_success.

API v3 : affiliations (lot 1.6)

  • Affiliations sous /organisations/{organisationId}/affiliations : liste et lecture avec secrets masqués (quatre derniers caractères), création avec vérification par le connecteur, nouvelle vérification, rotation des identifiants (PUT /{affiliationId}/credentials), suspension, reprise, révocation, journal d'audit de l'affiliation.
  • Création et rotation exigent une réauthentification récente pour une session (403 reauth_required) ; une clé API de l'organisation passe. Permissions affiliations.view et affiliations.manage.
  • Chaque affiliation liste les comptes de paiement qui l'utilisent (paymentAccounts), à afficher avant une révocation.
  • Support Konnect : GET /admin/affiliations avec filtres organisation, provider, status.

API v3 : comptes de paiement (lot 1.14)

  • Comptes de paiement sous /organisations/{id}/payment-accounts : liste, lecture, création, modification (nom, slug, habillage, URL, pause et reprise, compte par défaut), archivage.
  • Routage : GET et PUT /organisations/{id}/payment-accounts/{accountId}/routing choisissent, par fournisseur et par label, l'affiliation utilisée par chaque compte (partagée ou propre).
  • Les membres peuvent être limités à certains comptes ; permissions accounts.view et accounts.manage.

2026-10-03 : portail développeurs (lot 1.15)

  • Référence API v3 générée depuis packages/sdk/openapi.json, avec exemples en cURL, PHP, Node (@konnect/sdk) et Python.
  • Référence de compatibilité v2 : init-payment, GET /payments/{paymentId}, authentification x-api-key.
  • Guides : démarrage rapide, webhooks, erreurs et idempotence, migration v2 vers v3, sandbox, mise en production.
  • Page Plugins : WooCommerce 2.8.3, PrestaShop 2.0.3, avec sommes SHA-256 ; WHMCS bientôt disponible.

API v3 : identité, organisations, prestataires (lots 1.2, 1.3, 1.13, 1.4)

  • Authentification : /auth/* (connexion, double authentification, mot de passe) pour le tableau de bord, et GET /auth/api-key pour vérifier une clé API.
  • Clés API : GET, POST et DELETE /organisations/{id}/api-keys ; en-tête x-api-key, nouvelles clés kpk_<prefix>:<secret> affichées une seule fois.
  • Organisations, membres, invitations, rôles, documents et transfert de propriété sous /organisations/{id}.
  • Catalogue des prestataires : GET /providers, GET /providers/{code}.

API v3 0.1.0 (lot 1.1)

  • GET /health : état de l'API, de la base, du fournisseur de secrets et de l'outbox.
  • GET /organisations/{organisationId}/audit : journal d'audit d'une organisation, pagination par curseur. Fermé (401) jusqu'au lot 1.2.
  • GET /admin/outbox : événements de l'outbox, pour le support Konnect. Fermé (401) jusqu'au lot 1.2.
  • En-tête Idempotency-Key pris en charge par les routes POST qui l'activent.

API v2 (compatibilité)

  • Aucun changement : les routes v2 sont servies telles quelles par la nouvelle plateforme pour les organisations migrées, et relayées pour les autres.
  • addPaymentFeesToAmount est accepté et ignoré ; les anciens moyens de paiement (wallet, konnect, MCOIN, wire_transfer, Paypal) sont ignorés.