curl -X POST https://app.getkonbit.com/api/v1/payment_intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-123" \
  -H "Content-Type: application/json" \
  -d '{"amountMinor":10000,"description":"Order 123","metadata":{"orderId":"order-123"},"returnUrl":"https://mon-site.com/merci"}'

{
  "id": "5Qx0u5gexpnqsw6qQhks",       // konbitRef — gardez-le
  "status": "REQUIRES_PAYMENT",
  "amountMinor": 10000,               // 100,00 DOP
  "currency": "DOP",
  "feeMinor": 200,                    // notre commission
  "code": "562183",                   // saisie manuelle / QR
  "checkoutUrl": "https://app.getkonbit.com/pay/5Qx0u5gexpnqsw6qQhks",
  "expiresAtMs": 1783710307539        // millisecondes
}

checkoutUrl : la page où le client paie. code : saisie manuelle / QR. feeMinor : notre commission, déjà déduite de votre solde (le client paie amountMinor). expiresAtMs : après quoi l'intention passe EXPIRED.

Impossible de générer une clé pour le moment. Réessayez.

Payer une intention de test (sandbox)

Pas besoin de compte Konbit : appelle POST /v1/test/pay avec l'id de l'intention. Konbit simule un payeur sandbox, passe l'intention à SUCCEEDED, envoie le webhook signé (si tu as fourni une URL) et crédite ton solde marchand. Tu testes ainsi tout le cycle en autonomie.

curl -X POST https://app.getkonbit.com/api/v1/test/pay \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"intentId":"<id renvoyé par /payment_intents>"}'
# -> l'intention passe à SUCCEEDED, le webhook signé part (si configuré),
#    et ton solde marchand augmente (testable par GET /balance + payouts).

curl -X POST https://app.getkonbit.com/api/v1/payment_intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-123" \
  -H "Content-Type: application/json" \
  -d '{"amountMinor":10000,"description":"Order 123","returnUrl":"https://mon-site.com/merci"}'

{
  "id": "5Qx0u5gexpnqsw6qQhks",
  "status": "REQUIRES_PAYMENT",
  "amountMinor": 10000,
  "currency": "DOP",
  "feeMinor": 200,
  "code": "562183",
  "checkoutUrl": "https://app.getkonbit.com/pay/5Qx0u5gexpnqsw6qQhks",
  "expiresAtMs": 1783710307539
}

{ "id": "5Qx0...", "status": "SUCCEEDED", "amountMinor": 10000, "feeMinor": 200 }

curl -X POST https://app.getkonbit.com/api/v1/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"payment_intent":"5Qx0u5gexpnqsw6qQhks"}'

{ "object": "balance", "balanceMinor": 9800, "totalFeesMinor": 200, "currency": "DOP" }

curl -X POST https://app.getkonbit.com/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: driver-42-2026-W27" \
  -H "Content-Type: application/json" \
  -d '{"konbitCode":"K7M2P9QRS","amountMinor":85000,"metadata":{"driverId":"drv_42"}}'

{ "id":"p_8Kd...", "object":"payout", "status":"SUCCEEDED", "amountMinor":85000, "feeMinor":0, "currency":"DOP", "konbitCode":"K7M2P9QRS" }

Statuts d'un paiement

REQUIRES_PAYMENT : en attente · SUCCEEDED : payé · EXPIRED : expiré · CANCELED : annulé par vous · REFUNDED : remboursé.

Codes d'erreur

Toute erreur renvoie le même objet : un code stable (à tester) et un message lisible.

{ "error": { "code": "amount_out_of_bounds", "message": "..." } }

POST (votre webhookUrl)
Konbit-Signature: t=1720000000000,v1=<hmac_sha256>

{
  "id": "evt_9f2c...",                 // id de l'ÉVÉNEMENT — dédup
  "type": "payment_intent.succeeded",  // .refunded · .canceled · .expired · .payment_failed (data.failureCode)
  "createdAtMs": 1720000000000,        // millisecondes
  "data": {
    "id": "5Qx0...",                   // id de l'intention (= konbitRef)
    "status": "SUCCEEDED",
    "amountMinor": 10000,
    "currency": "DOP",
    "feeMinor": 200,
    "metadata": { "orderId": "order-123" }
  }
}

Vérifier la signature, pas à pas

1. Lisez le corps BRUT (non parsé). 2. Extrayez t et v1 de l'en-tête. 3. Rejetez si |maintenant − t| > 5 min. 4. Calculez HMAC-SHA256(secret_webhook, "."). 5. Comparez à v1 en temps constant. 6. Dédupliquez sur id (l'identifiant de l'ÉVÉNEMENT, pas data.id).

Vérification — extraits prêts à copier

const crypto = require("crypto");
// IMPORTANT: raw body, pas express.json() sur cette route
app.post("/konbit/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body;                       // Buffer brut
    const sig = req.get("Konbit-Signature") || "";
    const parts = Object.fromEntries(sig.split(",").map(p => p.split("=")));
    const t = Number(parts.t);                  // MILLISECONDES
    if (!t || Math.abs(Date.now() - t) > 5 * 60 * 1000) return res.sendStatus(401);
    const expected = crypto.createHmac("sha256", process.env.KONBIT_WEBHOOK_SECRET)
      .update(t + "." + raw.toString("utf8")).digest("hex");
    const a = Buffer.from(expected), b = Buffer.from(parts.v1 || "");
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);
    const event = JSON.parse(raw.toString("utf8"));
    if (alreadyProcessed(event.id)) return res.sendStatus(200);   // dédup sur event.id
    // re-vérifiez event.data.amountMinor + currency contre VOTRE commande
    markProcessed(event.id);
    fulfill(event.data.metadata.orderId);
    res.sendStatus(200);
  });

<?php
$raw = file_get_contents("php://input");        // corps brut
$sig = $_SERVER["HTTP_KONBIT_SIGNATURE"] ?? "";
parse_str(str_replace(",", "&", $sig), $p);      // t=...&v1=...
$t = (int)($p["t"] ?? 0);                        // MILLISECONDES
if (!$t || abs(round(microtime(true)*1000) - $t) > 300000) { http_response_code(401); exit; }
$expected = hash_hmac("sha256", $t . "." . $raw, getenv("KONBIT_WEBHOOK_SECRET"));
if (!hash_equals($expected, $p["v1"] ?? "")) { http_response_code(401); exit; }
$event = json_decode($raw, true);
if (already_processed($event["id"])) { http_response_code(200); exit; }  // dédup
// re-vérifiez amountMinor + currency contre votre commande
mark_processed($event["id"]);
fulfill($event["data"]["metadata"]["orderId"]);
http_response_code(200);

import hmac, hashlib, time, os
from flask import request, abort

@app.post("/konbit/webhook")
def konbit_webhook():
    raw = request.get_data()                     # bytes bruts
    parts = dict(p.split("=", 1) for p in request.headers.get("Konbit-Signature", "").split(","))
    t = int(parts.get("t", 0))                   # MILLISECONDES
    if not t or abs(time.time() * 1000 - t) > 300000:
        abort(401)
    expected = hmac.new(os.environ["KONBIT_WEBHOOK_SECRET"].encode(),
                        f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(401)
    event = request.get_json()
    if already_processed(event["id"]):           # dédup sur event.id
        return "", 200
    # re-vérifiez amountMinor + currency contre votre commande
    mark_processed(event["id"])
    fulfill(event["data"]["metadata"]["orderId"])
    return "", 200

Politique de relance

Livraison immédiate à l'événement. En cas d'échec (réponse hors 2xx, ou délai de 10 s dépassé), Konbit réessaie 5 fois, avec un backoff de 1, 5, 30, 120 puis 720 minutes — soit 6 tentatives au total sur environ 14,5 heures avant l'abandon (statut « dead », visible pour diagnostic). Chaque tentative est RESIGNÉE avec un t courant : votre fenêtre de 5 min accepte donc les relances. L'id de l'événement reste identique d'une relance à l'autre — dédupliquez dessus.

Ou par interrogation (polling)

Deux façons de savoir qu'un paiement a réussi : recevoir le webhook, ou interroger l'intention jusqu'au statut SUCCEEDED.

curl https://app.getkonbit.com/api/v1/payment_intents/{id} \
  -H "Authorization: Bearer sk_test_..."
# répétez jusqu'à "status": "SUCCEEDED"

Payer une intention de test

En sandbox, le plus simple est POST /v1/test/pay (ci-dessus) : aucun compte Konbit requis. Sinon, ouvre le checkoutUrl connecté à un compte Konbit de test approvisionné. Une fois l'encaissement carte activé pour ton compte (voir plus bas), le même checkoutUrl propose aussi « Payer par carte » (sans compte Konbit) : l'intention est alors marquée paidViaCard, créditée à ton solde USD, et tu reçois card_payment.succeeded + payment_intent.succeeded (déduplique par id).

• Clé sk_ marchande obtenue et stockée côté serveur (gestionnaire de secrets), jamais côté client.
• Idempotency-Key posée sur chaque création (votre orderId).
• Montants en unités mineures, dans les bornes ; devise DOP.
• Corps BRUT préservé pour la vérif HMAC (aucun parsing avant la signature).
• Endpoint webhook en https, répond 2xx en moins de 10 s, traitement lourd en asynchrone.
• Signature vérifiée en temps constant, t traité en millisecondes, requêtes de plus de 5 min rejetées.
• Polling de réconciliation en filet de sécurité, en plus du webhook.
• Statuts EXPIRED / CANCELED / REFUNDED et codes d'erreur gérés proprement.
• Déduplication sur l'id de l'ÉVÉNEMENT (livraison au-moins-une-fois).
• Ré-vérification du montant ET de la devise du webhook contre votre commande — ne faites pas confiance au seul type d'événement.
• Aucun chemin côté client ne marque « payé » : returnUrl n'est pas une preuve, seule la confirmation serveur l'est.