Quick start

This guide takes you from a sandbox account to a first confirmed payment, in five steps. It uses API v2, the one the plugins use, which the new platform keeps serving unchanged. v3 payments come next; Migrating from v2 to v3 describes what will change.

1. Get an API key and a Wallet ID

1. Create an account and an organisation on the sandbox dashboard (see Testing with the sandbox).
2. In the organisation settings, generate an API key. It looks like <organisationId>:<secret> and is shown once.
3. Note the id of the wallet that receives the payments (receiverWalletId).

Keep the key in an environment variable:

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

2. Create the payment

POST /api/v2/payments/init-payment creates the payment and returns the URL of the hosted payment page. The amount is in minor units (millimes for 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"
  }'

The response:

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

3. Redirect the buyer

Redirect the buyer to payUrl. They pick a payment method among those active on your account, then come back to successUrl or failUrl, to which Konnect appends payment_ref.

4. Receive the webhook

When the payment ends, Konnect calls your webhook URL with ?payment_ref=<paymentRef>. In v2 this call is not signed: it only means "this payment changed, come and look". Never deliver on the strength of this call alone. The Webhooks guide covers v2 and the HMAC signature planned for v3.

5. Check the status

Read the payment and deliver only when status is completed and the amount and orderId match your order.

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

Make this check idempotent: the webhook can arrive more than once, and the buyer can land on successUrl before or after it.

Next

• Webhooks: when and how Konnect calls you.
• Errors and idempotency: what to do with each HTTP code.
• API v2 reference: every field of init-payment.
• Plugins: WooCommerce and PrestaShop do all of this for you.