🔗 API Integration

Initiate Payment API

This endpoint initiates a new payment and returns a payment URL where the client can complete the transaction.

Endpoint

POST /payments/init-payment

Headers

Name	Required	Type	Description
x-api-key	Yes	string	Unique API key identifying your organization (get it here)

Body Example

{
  "receiverWalletId": "5f7a209aeb3f76490ac4a3d1",
  "token": "TND",
  "amount": 10000,
  "type": "immediate",
  "description": "payment description",
  "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"
}

Request Body Parameters

Option	Type	Description
receiverWalletId (required)	string	Konnect wallet ID of the payment receiver (found in dashboard)
token	string	Currency of payment: ⁠TND, ⁠EUR, or ⁠USD. Non-TND payments are automatically converted
amount (required)	number	Payment amount (in Millimes for TND / Centimes for EUR and USD)
type	string	Payment type: ⁠immediate (full payment) or ⁠partial (allows partial payments)
description	string	Payment description visible to payer on gateway page
acceptedPaymentMethods	array	Allowed payment methods: ⁠wallet, ⁠bank_card, ⁠e-DINAR, ⁠flouci. Defaults to ⁠["wallet","bank_card","e-DINAR"]
lifespan	number	Payment link expiration time in minutes
checkoutForm	boolean	Whether payer must fill checkout form before payment
addPaymentFeesToAmount	boolean	If true, adds Konnect fees to payers amount. Defaults to ⁠false
firstName	string	Payers first name
lastName	string	Payers last name
phoneNumber	string	Payers phone number
email	string	Payers email address
orderId	string	Custom order identifier
webhook	string	URL for payment notification (GET request)
silentWebhook	boolean	If true, calls webhook without redirecting payer
successUrl	string	Redirect URL for successful payment (ignored if webhook is active and not silent)
failUrl	string	Redirect URL for failed payment (ignored if webhook is active and not silent)
theme	string	Gateway theme: ⁠light or ⁠dark. Defaults to ⁠light

Response

Example

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

Response Parameters

Parameter	Type	Description
payUrl	string	Payment gateway URL where the client can complete the payment
paymentRef	string	Unique reference ID for the payment

Test

Best Practices

Always implement proper error handling for both API calls and webhook notifications
Set appropriate lifespan for payments based on your business needs
Use silentWebhook when you need to process payment results without user redirection
Store paymentRef for future reference and reconciliation

Rate Limits

Standard rate limit: 100 requests per minute
Contact support for increased limits if needed

Introduction Webhook