API docs

Overview

Khusela is payment-risk verification for South African micro-sellers. A buyer sends proof of payment; Khusela checks the document for editing traces, compares the claim to an expected sale, and looks for the same document under another seller.

All request and response bodies are JSON except the multipart upload to /check. Timestamps are ISO 8601 in SAST.

Authentication

Every request uses a seller token in the Authorization header. The token resolves to one row in sellers; the seller ID is never accepted from the request body.

Authorization: Bearer khs_live_7f3a…

Register a seller

The response contains the seller record and a one-time auth_token. Store it immediately; only a hash is retained.

Verify a payment

Multipart form upload. The file must be JPEG, PNG, or PDF and no larger than 5 MB.

curl -X POST https://api.khusela.internal/check \
  -H "Authorization: Bearer khs_live_7f3a…" \
  -F "file=@receipt.png" \
  -F "expected_sale_id=ES-88213"

Response

{
  "check_id": "CHK-10482",
  "verdict": "MATCH",
  "confidence": 98.4,
  "reasons": [
    "amount_matches_expected_sale",
    "recipient_matches",
    "bank_alert_found"
  ],
  "duplicate": false,
  "retention": "raw_file_deleted_in_24h"
}

The response is returned only after the verdict is written to checks and the fingerprint to fingerprints. A duplicate hit from another seller returns STOP even when every amount signal passes.

Verdicts

Scores are deterministic for the same inputs and rule version. The rule version is stored with every check so a historical verdict can be reproduced.

Common reason codes

• amount_matches_expected_sale — exact amount match, zero tolerance.
• recipient_matches — fuzzy name match at 90% or better.
• bank_alert_found — settled event with the same amount and reference.
• amount_mismatch — claim differs from the expected sale; caps at WAIT.
• font_inconsistency — edited text layer detected; forces STOP.
• cross_seller_duplicate — perceptual hash hit under another seller; forces STOP.

Data models

SQLite via SQLAlchemy. Four tables hold the entire verification state; raw files live outside the database and expire in 24 hours.

sellers

expected_sales

checks

fingerprints

Errors

{
  "error": "unreadable_document",
  "message": "The PDF could not be parsed in the sandbox.",
  "request_id": "req_8f21c0"
}

Safety limits

• Maximum upload size is 5 MB, enforced before the body is fully read.
• Allowed MIME types are image/jpeg, image/png, and application/pdf.
• PDFs are parsed in an unprivileged Docker container with no network access and a 5 second CPU budget.
• Duplicate lookup only considers fingerprints from other sellers, so a seller cannot poison their own history.
• A STOP verdict can never be auto-released, even if the amount later matches.
• Requests are rate limited to 60 checks per minute per seller token.

Retention

Raw receipts are deleted 24 hours after upload by a scheduled worker that runs every 15 minutes. Verdicts and fingerprints persist for 90 days, then are aggregated into seller-level counts. Confirmed fraud incidents keep metadata only; the raw document is never retained for a case.