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 página donde paga el cliente. code: entrada manual / QR. feeMinor: nuestra comisión, ya descontada de tu saldo (el cliente paga amountMinor). expiresAtMs: tras lo cual la intención pasa a EXPIRED.

No se pudo generar una clave ahora. Inténtalo de nuevo.

Pagar una intención de prueba (sandbox)

Sin cuenta Konbit: llama a POST /v1/test/pay con el id de la intención. Konbit simula un pagador sandbox, pasa la intención a SUCCEEDED, envía el webhook firmado (si diste una URL) y acredita tu saldo de comercio. Así pruebas todo el ciclo por tu cuenta.

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

Estados de un pago

REQUIRES_PAYMENT: pendiente · SUCCEEDED: pagado · EXPIRED: expirado · CANCELED: cancelado por ti · REFUNDED: reembolsado.

Códigos de error

Todo error devuelve el mismo objeto: un código estable (para comprobar) y un mensaje legible.

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

Verificar la firma, paso a paso

1. Lee el cuerpo CRUDO (sin parsear). 2. Extrae t y v1 de la cabecera. 3. Rechaza si |ahora − t| > 5 min. 4. Calcula HMAC-SHA256(secreto_webhook, "."). 5. Compara con v1 en tiempo constante. 6. Deduplica por id (el id del EVENTO, no data.id).

Verificación — fragmentos para copiar

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

Política de reintentos

Entrega inmediata en el evento. Ante un fallo (respuesta no 2xx, o superado el tiempo de 10 s), Konbit reintenta 5 veces, con un backoff de 1, 5, 30, 120 y 720 minutos — 6 intentos en total durante unas 14,5 horas antes de rendirse (estado «dead», visible para diagnóstico). Cada intento se REFIRMA con un t actual: tu ventana de 5 min acepta los reintentos. El id del evento no cambia entre reintentos — deduplica por él.

O por consulta (polling)

Dos formas de saber que un pago tuvo éxito: recibir el webhook, o consultar la intención hasta el estado SUCCEEDED.

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

Pagar una intención de prueba

Para llegar al pago necesitas una cuenta Konbit con saldo. En sandbox: abre el checkoutUrl con sesión en una cuenta Konbit de prueba, o pídenos una cuenta pagadora de prueba con fondos. Sin eso puedes crear intenciones pero no liquidarlas. Una vez activado el cobro con tarjeta para tu cuenta (ver abajo), el mismo checkoutUrl también ofrece «Pagar con tarjeta» (sin cuenta Konbit): la intención queda marcada paidViaCard, se acredita a tu saldo USD y recibes card_payment.succeeded + payment_intent.succeeded (deduplica por id).

• Clave sk_ de comercio obtenida y guardada en el servidor (gestor de secretos), nunca en el cliente.
• Idempotency-Key puesta en cada creación (tu orderId).
• Montos en unidades menores, dentro de los límites; moneda DOP.
• Cuerpo CRUDO conservado para la verificación HMAC (sin parsear antes de la firma).
• Endpoint de webhook en https, responde 2xx en menos de 10 s, trabajo pesado en asíncrono.
• Firma verificada en tiempo constante, t tratado como milisegundos, solicitudes de más de 5 min rechazadas.
• Polling de conciliación como red de seguridad, además del webhook.
• Estados EXPIRED / CANCELED / REFUNDED y códigos de error gestionados con cuidado.
• Deduplicación por el id del EVENTO (entrega al-menos-una-vez).
• Reverificar el monto Y la moneda del webhook contra tu pedido — no confíes solo en el tipo de evento.
• Ningún camino del lado del cliente marca «pagado»: returnUrl no es prueba, solo lo es la confirmación del servidor.