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

Guides

Démarrage rapide

Encaisser un premier paiement en sandbox : clé API, création du paiement, redirection, webhook, vérification du statut.

Ce guide vous mène du compte sandbox au premier paiement confirmé, en cinq étapes. Il utilise l'API v2, celle des plugins, qui reste servie sans changement par la nouvelle plateforme. Les paiements v3 suivront ; le guide Migrer de la v2 à la v3 décrit ce qui changera.

Vos secrets restent sur votre serveur

La clé API ne doit jamais apparaître dans un navigateur, une application mobile, une URL ou un journal. Tous les appels ci-dessous partent de votre serveur.

1. Obtenir une clé API et un Wallet ID

  1. Créez un compte et une organisation sur le tableau de bord sandbox (voir Tester avec la sandbox).
  2. Dans les réglages de l'organisation, générez une clé API. Elle a la forme <organisationId>:<secret> et ne s'affiche qu'une fois.
  3. Notez l'identifiant du wallet qui reçoit les paiements (receiverWalletId).

Rangez la clé dans une variable d'environnement :

export KONNECT_API_KEY="<organisationId>:<secret>"
export KONNECT_V2_URL="https://api.preprod.konnect.network"

2. Créer le paiement

POST /api/v2/payments/init-payment crée le paiement et renvoie l'URL de la page de paiement hébergée. Le montant est en unités mineures (millimes pour le TND).

curl -X POST "$KONNECT_V2_URL/api/v2/payments/init-payment" \
  -H "x-api-key: $KONNECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverWalletId": "5f7a209aeb3f76490ac4a3d1",
    "amount": 120000,
    "token": "TND",
    "description": "Order 1001",
    "orderId": "order-1001",
    "acceptedPaymentMethods": ["bank_card", "e-DINAR"],
    "webhook": "https://shop.example.com/konnect/webhook",
    "successUrl": "https://shop.example.com/checkout/success",
    "failUrl": "https://shop.example.com/checkout/failure"
  }'

La réponse :

{
  "payUrl": "https://checkout.konnect.example/pay?payment_ref=665f1c2e8b3a4d0012ab34cd",
  "paymentRef": "665f1c2e8b3a4d0012ab34cd"
}

3. Rediriger l'acheteur

Redirigez l'acheteur vers payUrl. Il y choisit son moyen de paiement parmi ceux actifs sur votre compte, puis revient sur successUrl ou failUrl, auxquelles Konnect ajoute payment_ref.

4. Recevoir le webhook

À la fin du paiement, Konnect appelle votre URL webhook avec ?payment_ref=<paymentRef>. En v2, cet appel n'est pas signé : il signifie seulement « ce paiement a changé, venez voir ». Ne livrez jamais sur la seule foi de cet appel. Le guide Webhooks détaille la v2 et la signature HMAC prévue en v3.

5. Vérifier le statut

Lisez le paiement et livrez seulement si status vaut completed, que le montant et orderId correspondent à votre commande.

curl "$KONNECT_V2_URL/api/v2/payments/665f1c2e8b3a4d0012ab34cd" \
  -H "x-api-key: $KONNECT_API_KEY"

Rendez cette vérification idempotente : le webhook peut arriver plusieurs fois, et l'acheteur peut revenir sur successUrl avant ou après lui.

Ensuite