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: the page where the customer pays. code: manual entry / QR. feeMinor: our commission, already deducted from your balance (the customer pays amountMinor). expiresAtMs: after which the intent turns EXPIRED.

Could not generate a key right now. Try again.

Pay a test intent (sandbox)

No Konbit account needed: call POST /v1/test/pay with the intent id. Konbit simulates a sandbox payer, moves the intent to SUCCEEDED, sends the signed webhook (if you provided a URL) and credits your merchant balance. You test the whole cycle on your own.

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

Payment statuses

REQUIRES_PAYMENT: pending · SUCCEEDED: paid · EXPIRED: expired · CANCELED: canceled by you · REFUNDED: refunded.

Error codes

Every error returns the same object: a stable code (to test against) and a readable message.

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

Verify the signature, step by step

1. Read the RAW body (unparsed). 2. Extract t and v1 from the header. 3. Reject if |now − t| > 5 min. 4. Compute HMAC-SHA256(webhook_secret, "."). 5. Compare to v1 in constant time. 6. Deduplicate on id (the EVENT id, not data.id).

Verification — copy-paste snippets

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

Retry policy

Immediate delivery on the event. On failure (non-2xx response, or the 10 s timeout exceeded), Konbit retries 5 times, with a backoff of 1, 5, 30, 120 then 720 minutes — 6 attempts total over about 14.5 hours before giving up ("dead" status, visible for diagnostics). Each attempt is RE-SIGNED with a current t: your 5-minute window therefore accepts retries. The event id stays identical across retries — deduplicate on it.

Or by polling

Two ways to know a payment succeeded: receive the webhook, or poll the intent until its status is SUCCEEDED.

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

Pay a test intent

In sandbox the simplest is POST /v1/test/pay (above): no Konbit account required. Otherwise, open the checkoutUrl signed into a funded test Konbit account. Once card collection is enabled for your account (see below), the same checkoutUrl also offers “Pay by card” (no Konbit account): the intent is then marked paidViaCard, credited to your USD balance, and you receive card_payment.succeeded + payment_intent.succeeded (dedupe by id).

• Merchant sk_ key obtained and stored server-side (secrets manager), never client-side.
• Idempotency-Key set on every creation (your orderId).
• Amounts in minor units, within bounds; DOP currency.
• RAW body preserved for the HMAC check (no parsing before the signature).
• Webhook endpoint on https, replies 2xx in under 10 s, heavy work done asynchronously.
• Signature verified in constant time, t handled as milliseconds, requests older than 5 min rejected.
• Reconciliation polling as a safety net, on top of the webhook.
• EXPIRED / CANCELED / REFUNDED statuses and error codes handled cleanly.
• Deduplication on the EVENT id (at-least-once delivery).
• Re-verify the webhook's amount AND currency against your order — don't trust the event type alone.
• No client-side path marks "paid": returnUrl is not proof, only server confirmation is.