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: paj kote kliyan an peye. code: antre alamen / QR. feeMinor: komisyon nou, deja retire sou balans ou (kliyan an peye amountMinor). expiresAtMs: apre sa entansyon an vin EXPIRED.

Nou pa ka jenere yon kle kounye a. Eseye ankò.

Peye yon entansyon tès (sandbox)

Pa bezwen kont Konbit: rele POST /v1/test/pay ak id entansyon an. Konbit similye yon peyè sandbox, mete entansyon an SUCCEEDED, voye webhook siyen an (si ou bay yon URL) epi kredite balans machann ou. Konsa ou teste tout sik la poukont ou.

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

Estati yon peman

REQUIRES_PAYMENT: ap tann · SUCCEEDED: peye · EXPIRED: ekspire · CANCELED: ou anile l · REFUNDED: ranbouse.

Kòd erè

Chak erè voye menm objè a: yon kòd ki estab (pou teste) ak yon mesaj lizib.

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

Verifye siyati a, etap pa etap

1. Li kò a BRUT (san parse). 2. Retire t ak v1 nan antèt la. 3. Rejte si |kounye a − t| > 5 min. 4. Kalkile HMAC-SHA256(sekrè_webhook, "."). 5. Konpare ak v1 an tan konstan. 6. Dedouble sou id (id EVÈNMAN an, pa data.id).

Verifikasyon — moso pou kopye

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

Règ rees​eye

Livrezon imedya sou evènman an. Si l echwe (repons ki pa 2xx, oswa depase 10 s), Konbit reeseye 5 fwa, ak yon backoff 1, 5, 30, 120 answit 720 minit — 6 tantativ antou sou anviwon 14,5 è anvan li abandone (estati «dead», vizib pou dyagnostik). Chak tantativ RESIYEN ak yon t aktyèl: donk fenèt 5 min ou aksepte reeseye yo. id evènman an rete menm ant reeseye yo — dedouble sou li.

Oswa pa mande (polling)

De fason pou konnen yon peman reyisi : resevwa webhook la, oswa mande estati entansyon an jiskaske li SUCCEEDED.

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

Peye yon entansyon tès

Pou rive nan peman an, ou bezwen yon kont Konbit ak balans. Nan sandbox: ouvri checkoutUrl la konekte sou yon kont Konbit tès, oswa mande nou yon kont peyè tès ak lajan. San sa ou ka kreye entansyon men ou pa ka peye yo. Yon fwa ankesman pa kat aktive pou kont ou (gade anba a), menm checkoutUrl la ofri tou « Peye ak kat » (san kont Konbit): entansyon an make paidViaCard, li kredite sou balans USD ou, epi ou resevwa card_payment.succeeded + payment_intent.succeeded (dedipe pa id).

• Kle sk_ machann jwenn epi sere bò sèvè a (jesyonè sekrè), pa janm bò kliyan.
• Idempotency-Key mete sou chak kreyasyon (orderId ou).
• Montan an inite minè, anndan limit yo; lajan DOP.
• Kò BRUT konsève pou verifikasyon HMAC (pa parse anvan siyati a).
• Endpoint webhook an https, reponn 2xx an mwens pase 10 s, travay lou an asenkwòn.
• Siyati verifye an tan konstan, t trete kòm milisgonn, demann ki gen plis pase 5 min rejte.
• Polling rekonsilyasyon kòm filè sekirite, anplis webhook la.
• Estati EXPIRED / CANCELED / REFUNDED ak kòd erè jere pwòp.
• Dedoublaj sou id EVÈNMAN an (livrezon omwen-yon-fwa).
• Reverifye montan AN ak lajan webhook la kont kòmand ou — pa fè konfyans nan tip evènman an sèlman.
• Okenn chemen bò kliyan pa make «peye»: returnUrl pa yon prèv, se sèlman konfimasyon sèvè a ki prèv.