API v2 (compatibilité)

Paramètres

Aucun paramètre.

Corps de la requête application/json

• receiverWalletIdstringobligatoire

  Wallet (compte d'encaissement) qui reçoit le paiement. receiverWallet est accepté comme alias.

• amountintegerobligatoire

  Montant en unités mineures : millimes pour le TND (120000 vaut 120,000 TND).

  • min: 100
  • max: 30000000
• tokenstring

  Devise. Seul le TND est servi par la nouvelle plateforme.

  • enum: "TND"
• descriptionstring

  Affichée à l'acheteur sur la page de paiement.

  • minLength: 3
  • maxLength: 280
• lifespaninteger

  Minutes avant l'expiration du paiement.

  • min: 1
  • max: 60
• acceptedPaymentMethodsstring[]

  bank_card et e-DINAR désignent les prestataires de carte actifs sur votre compte, flouci désigne Flouci. Les anciennes valeurs (wallet, konnect, MCOIN, wire_transfer, Paypal) sont ignorées.

• webhookstring (uri)

  Appelée avec ?payment_ref=<paymentRef> à la fin du paiement. Non signée : confirmez avec GET /api/v2/payments/{paymentId}.

• silentWebhookboolean

  Si vrai, Konnect appelle le webhook de serveur à serveur et envoie l'acheteur vers successUrl ou failUrl.

• successUrlstring (uri)

  Page de retour de l'acheteur après un paiement réussi (payment_ref est ajouté).

• failUrlstring (uri)

  Page de retour de l'acheteur après un échec ou une annulation (payment_ref est ajouté).

• themestring

  Thème de la page de paiement.

  • enum: "light", "dark"
• checkoutFormboolean

  Demander nom, e-mail et téléphone à l'acheteur sur la page de paiement.

• addPaymentFeesToAmountboolean

  Obsolète : accepté et ignoré (aucun frais Konnect sur le flux).

• orderIdstring

  Votre référence de commande, renvoyée sur le paiement.

• typestring

  partial permet de payer en plusieurs fois.

  • enum: "immediate", "partial"
• receiverPhoneNumberstring
• firstNamestring
• lastNamestring
• emailstring (email)
• phoneNumberstring

Réponses

• 200Paiement créé.

  • payUrlstring (uri)obligatoire

    Page de paiement hébergée : redirigez l'acheteur ici.

  • paymentRefstringobligatoire

    24 caractères hexadécimaux ; conservez-le avec votre commande.

• 400Erreur de validation : une entrée par champ invalide.

  • errorsobject[]
    • msgstring
    • paramstring

• 401x-api-key absent ou invalide.

  • messagestring

• 422Une règle métier refuse le paiement (par exemple une devise non servie par la plateforme).

  • messagestring

Exemples de code

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",
  "token": "TND",
  "amount": 120000,
  "description": "Order 1001",
  "acceptedPaymentMethods": [
    "bank_card",
    "e-DINAR",
    "flouci"
  ],
  "lifespan": 20,
  "checkoutForm": false,
  "webhook": "https://shop.example.com/konnect/webhook",
  "successUrl": "https://shop.example.com/checkout/success",
  "failUrl": "https://shop.example.com/checkout/failure",
  "theme": "light",
  "orderId": "order-1001",
  "firstName": "Salma",
  "lastName": "Example",
  "email": "buyer@example.com",
  "phoneNumber": "22000000"
}'

Exemple : corps de la requête

{
  "receiverWalletId": "5f7a209aeb3f76490ac4a3d1",
  "token": "TND",
  "amount": 120000,
  "description": "Order 1001",
  "acceptedPaymentMethods": [
    "bank_card",
    "e-DINAR",
    "flouci"
  ],
  "lifespan": 20,
  "checkoutForm": false,
  "webhook": "https://shop.example.com/konnect/webhook",
  "successUrl": "https://shop.example.com/checkout/success",
  "failUrl": "https://shop.example.com/checkout/failure",
  "theme": "light",
  "orderId": "order-1001",
  "firstName": "Salma",
  "lastName": "Example",
  "email": "buyer@example.com",
  "phoneNumber": "22000000"
}

Exemple : 200

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

Exemple : 400

{
  "errors": [
    {
      "msg": "amount must be between 100 and 30000000",
      "param": "amount"
    }
  ]
}

Paramètres

• paymentIdstringpathobligatoire

  Le paymentRef renvoyé par init-payment (24 caractères hexadécimaux).

  • pattern: ^[a-f0-9]{24}$

Réponses

• 200Le paiement.

  • paymentPayment
    • idstring
    • statusstring

      completed quand le montant est entièrement payé ; seul ce statut signifie payé.

      • enum: "pending", "completed", "failed", "canceled", "expired", "refunded", "partial"
    • amountinteger
    • tokenstring
    • descriptionstring
    • acceptedPaymentMethodsstring[]
    • linkstring (uri)
    • expirationDatestring (date-time)
    • orderIdstring
    • transactionsTransaction[]
      • idstring
      • amountinteger
      • methodstring
      • statusstring
        • enum: "pending_payment", "success", "failed_payment", "expired", "canceled", "refunded"
      • typestring
      • tokenstring
      • ext_payment_refstring

        Référence chez le prestataire.

      • fromstring

        Code du prestataire.

• 401x-api-key absent ou invalide.

  • messagestring

• 404Aucun paiement avec cette référence.

  • messagestring

Exemples de code

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

Exemple : 200

{
  "payment": {
    "id": "665f1c2e8b3a4d0012ab34cd",
    "status": "completed",
    "amount": 120000,
    "token": "TND",
    "description": "Order 1001",
    "acceptedPaymentMethods": [
      "bank_card",
      "e-DINAR",
      "flouci"
    ],
    "link": "https://checkout.konnect.example/pay?payment_ref=665f1c2e8b3a4d0012ab34cd",
    "expirationDate": "2026-10-01T09:50:00.000Z",
    "orderId": "order-1001",
    "transactions": [
      {
        "id": "665f1c4a8b3a4d0012ab34ce",
        "amount": 120000,
        "method": "bank_card",
        "status": "success",
        "type": "payment",
        "token": "TND",
        "ext_payment_ref": "TEST-000001",
        "from": "clictopay"
      }
    ]
  }
}

Exemple : 401

{
  "message": "Unauthorized"
}