API v2 (compatibility)

Parameters

No parameters.

Request body application/json

• receiverWalletIdstringrequired

  Wallet (payment account) that receives the payment. receiverWallet is accepted as an alias.

• amountintegerrequired

  Amount in minor units: millimes for TND (120000 is 120.000 TND).

  • min: 100
  • max: 30000000
• tokenstring

  Currency. Only TND is served by the new platform.

  • enum: "TND"
• descriptionstring

  Shown to the buyer on the payment page.

  • minLength: 3
  • maxLength: 280
• lifespaninteger

  Minutes before the payment expires.

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

  bank_card and e-DINAR map to the card providers active on your account, flouci to Flouci. Legacy values (wallet, konnect, MCOIN, wire_transfer, Paypal) are ignored.

• webhookstring (uri)

  Called with ?payment_ref=<paymentRef> when the payment ends. Not signed: confirm with GET /api/v2/payments/{paymentId}.

• silentWebhookboolean

  When true, Konnect calls the webhook server to server and sends the buyer to successUrl or failUrl.

• successUrlstring (uri)

  Where the buyer lands after a successful payment (payment_ref is appended).

• failUrlstring (uri)

  Where the buyer lands after a failed or cancelled payment (payment_ref is appended).

• themestring

  Theme of the payment page.

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

  Ask the buyer for name, e-mail and phone on the payment page.

• addPaymentFeesToAmountboolean

  Deprecated: accepted and ignored (no Konnect fee on the flow).

• orderIdstring

  Your order reference, returned on the payment.

• typestring

  partial lets the buyer pay in several times.

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

Responses

• 200Payment created.

  • payUrlstring (uri)required

    Hosted payment page: redirect the buyer here.

  • paymentRefstringrequired

    24 hexadecimal characters; keep it with your order.

• 400Validation error: one entry per invalid field.

  • errorsobject[]
    • msgstring
    • paramstring

• 401Missing or wrong x-api-key.

  • messagestring

• 422Business rule refused the payment (for example a currency the platform does not serve).

  • messagestring

Code samples

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"
}'

Example: request body

{
  "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"
}

Example: 200

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

Example: 400

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

Parameters

• paymentIdstringpathrequired

  The paymentRef returned by init-payment (24 hexadecimal characters).

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

Responses

• 200The payment.

  • paymentPayment
    • idstring
    • statusstring

      completed once the amount is fully paid; only this status means paid.

      • 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

        Reference at the provider.

      • fromstring

        Provider code.

• 401Missing or wrong x-api-key.

  • messagestring

• 404No payment with this reference.

  • messagestring

Code samples

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

Example: 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"
      }
    ]
  }
}

Example: 401

{
  "message": "Unauthorized"
}