Konekte Voucher System

Technical Reference Document — System Architecture, API Specification, Data Schemas, and Operational Flows

Version 3.0 — Policy-Driven Model•April 2026•Confidential

System Overview

The Konekte Voucher System is a full-lifecycle digital voucher infrastructure designed for the Haitian market. It supports multiple entry points (Partner API, Stripe, NGO bulk, in-app), a multi-merchant redemption network with real-time float management, and a double-entry financial ledger with automated settlement and contribution-based capital recovery.

4
Entry Points
API, Stripe, NGO, In-App
2
Funding Modes
Prefunded & Deferred
13
Ledger Entry Types
Double-entry accounting
5
Voucher States
Full lifecycle tracking

System Architecture

High-level architecture showing entry points, core processing engine, and distribution network.

Entry Points
  • Partner API (REST + API Key)
  • Stripe Checkout (public buyers)
  • NGO Bulk Purchase (dashboard)
  • In-App Purchase (wallet users)
Core Engine
  • Voucher Lifecycle Manager
  • Treasury Ledger (double-entry)
  • Fee Engine (contribution-recovery-aware)
  • FX Pricing Engine (real-time)
  • Idempotency Guard
  • SMS Delivery (Twilio)
  • Webhook Dispatcher (HMAC)
Distribution Network
  • Merchant Registry (multi-location)
  • Float Management (real-time alerts)
  • MSF Configuration (per-merchant)
  • Department-based routing
  • Denomination validation
Key Design Principles: Idempotent operations (every write uses a unique reference_id), immutable ledger entries (no updates or deletes), hash-based PIN security (plaintext never stored), and optimistic locking on all balance mutations.

API Reference

All endpoints use POST method with JSON body. Authentication via X-API-Key header.

EndpointPurposeIdempotent
/api/partnerIssueVoucherIssue new voucher with SMS PIN deliveryYes (external_reference_id)
/api/partnerGetVoucherLookup voucher by external referenceN/A (read)
/api/partnerGetBalanceCurrent balance / credit utilizationN/A (read)
/api/partnerGetSummaryAggregated issuance & redemption metricsN/A (read)
/api/partnerGetTransactionsPaginated transaction historyN/A (read)
Breaking Change (v3.0): All issuance requests now require a policy object. Partner API only supports policy.type = "MERCHANT". Requests without a policy are rejected with ERR_INVALID_POLICY. Legacy merchant_id field is accepted as fallback but deprecated.
Policy Object Structure
// MERCHANT — locked to specific merchant (Partner API)
{ "type": "MERCHANT", "merchant_code": "M-001" }

// CATEGORY — restricted to merchant categories (Admin/NGO/In-App)
{ "type": "CATEGORY", "category_codes": ["food", "pharmacy"] }

// ANY — redeemable at any merchant (Admin/NGO with confirmation)
{ "type": "ANY" }
Example: Issue Voucher Request (v3.0)
POST /api/partnerIssueVoucher
X-API-Key: pk_live_xxxxxxxxxx

{
  "external_reference_id": "DING-TXN-20260425-001",
  "amount_htg": 500,
  "recipient_phone": "+50912345678",
  "recipient_name": "Jean Pierre",
  "policy": {
    "type": "MERCHANT",
    "merchant_code": "M-001"
  }
}
Example: Issue Voucher Response
{
  "voucher_code": "VI-A1B2C3D4",
  "external_reference_id": "DING-TXN-20260425-001",
  "amount_htg": 500,
  "currency": "HTG",
  "status": "ISSUED",
  "expires_at": "2026-10-22T14:30:00Z",
  "policy": {
    "type": "MERCHANT",
    "merchant_code": "M-001",
    "merchant_id": "abc123"
  },
  "merchant_name": "MegaMart",
  "_request_id": "req_..."
}
Fee Earnings Note: Partners with an active capital contribution (PartnerContribution) will see temporarily higher fee share during the recovery period. Once the contribution is fully recovered, fee distribution reverts to the standard revenue share model. API response schemas are not affected — fee details are handled internally and reflected in settlement statements.

Error Codes

ERR_UNAUTHORIZED — Invalid/missing API key
ERR_INVALID_POLICY — Missing/invalid policy object
ERR_MERCHANT_REQUIRED — merchant_code missing
ERR_INVALID_MERCHANT — Merchant not found/inactive
ERR_MERCHANT_MISMATCH — Redemption at wrong merchant
ERR_CATEGORY_MISMATCH — Category not matching
ERR_INVALID_CATEGORY — Invalid category code
ERR_INSUFFICIENT_CUSTODIAL — Balance too low
ERR_CREDIT_LIMIT_EXCEEDED — Over credit limit
ERR_INVALID_AMOUNT — No voucher for amount
ERR_RATE_LIMIT_EXCEEDED — Rate limit exceeded
ERR_PARTNER_INACTIVE — Account suspended

Deprecated Fields

eligibility_type → use policy.type
eligibility_value → use policy.merchant_code / policy.category_codes
merchant_id (request) → use policy.merchant_code

Legacy fields are retained on existing records but not used for validation.

Voucher Issuance Flow

Complete issuance pipeline from API request to SMS delivery and webhook notification.

Voucher = Amount + Recipient + Policy

Every voucher is defined by three immutable properties: the denomination (amount), the intended recipient, and the redemption policy. The policy is attached at issuance and never modified thereafter.

1. Issuance

Policy attached (immutable). Treasury lock created. SMS PIN delivered.

2. Distribution

Assignment only (NGO bulk). No policy change. Narrows, never broadens.

3. Redemption

Policy validation enforced. Merchant match required for MERCHANT type.

4. Settlement

Merchant credited. MSF deducted. Lock released.

Partner (Ding)
  • POST /api/partnerIssueVoucher
  • X-API-Key header
  • external_reference_id (idempotency)
API Request
Konekte Platform
  • 1. Authenticate API key (SHA-256 hash match)
  • 2. Validate partner status & balance/credit
  • 3. Check contribution recovery → calculate fee split
  • 4. Create VoucherInstance + PIN (hashed)
  • 5. Create VoucherTreasuryLock (liability)
  • 6. Create VoucherFeeSnapshot (fee audit)
  • 7. Create VoucherLedgerEntry (ISSUANCE_DEBIT)
  • 8. Send PIN via SMS (Twilio)
  • 9. Dispatch webhook (voucher_issued)
SMS
Recipient
  • Receives PIN via SMS
  • Can check status online
Webhook
Partner System
  • voucher_issued event
  • HMAC signature verified
Idempotency Guarantee: If the same external_reference_id is submitted twice, the system returns the original voucher data without creating a duplicate. Safe for network retries.

Voucher Redemption Flow

End-to-end redemption process from recipient presentation to merchant settlement.

Voucher Holder
  • Presents serial number + PIN at merchant
Redemption Request
Merchant
  • Verifies voucher via Konekte system
  • Provides cash/goods to recipient
System Processing
Konekte Platform
  • 1. Validate PIN (hash comparison)
  • 2. Check voucher status = ISSUED & not expired
  • 3. Create VoucherRedemption (PENDING → COMPLETED)
  • 4. Release VoucherTreasuryLock (LOCKED → RELEASED)
  • 5. Deduct merchant float_balance
  • 6. Record allocation ledger entry
  • 7. Calculate & record MSF (merchant service fee)
  • 8. Dispatch webhook (voucher_redeemed)
Webhook Notification
Partner System
  • voucher_redeemed event
  • Real-time settlement tracking

Settlement & Fee Recovery

Weekly settlement cycle with contribution-based capital recovery.

Weekly Settlement Cycle
  • System aggregates deferred receivables
  • Calculates: principal + fees (contribution recovery applied at issuance)
  • Generates settlement snapshot
Settlement Invoice
Partner (Ding)
  • Receives settlement statement
  • Remits net amount to Konekte
Payment Confirmed
Ledger Updates
  • PARTNER_SETTLEMENT_INFLOW recorded
  • current_receivable decreased
  • Fee snapshots marked SETTLED
  • Revenue recognized (platform + partner shares)

Contribution Recovery Mechanism

When a partner has an active PartnerContribution (capital investment), the system redirects issuance fees to the partner until the contributed amount is fully recovered. Fees are charged normally — the split is adjusted so the partner receives a larger share until recovery is complete, then transitions to the standard revenue share model.

Phase 1: Recovery Active

Fees are redirected to partner (contribution_recovery_htg) until capital is recovered

Phase 2: Exhausted

Auto-transitions to standard revenue share (e.g., 20%)

Tracking

Every recovery is recorded as a CONTRIBUTION_RECOVERY ledger entry

Merchant Float Model

Merchants receive float through two distinct channels, tracked via campaign_tag for reporting:

INITIAL_ONBOARDING

One-time seed capital to activate a new merchant. Treated as working capital deployment, not operational expense.

PROMOTIONAL_SUBSIDY

Promotional float top-ups. Treated as true operational expense for P&L reporting.

Data Schemas

Core entity schemas powering the voucher system. Click each to expand field details.

Security Model

API Authentication

SHA-256 hashed API keys. Plaintext shown once at generation, never stored. Prefix-based identification for key management.

PIN Security

Voucher PINs are hashed before storage using HMAC-SHA256. Verification via hash comparison only. Plaintext delivered once via SMS.

Webhook Signatures

All webhook payloads are signed with HMAC-SHA256 using a per-partner secret. Recipients must verify the X-Webhook-Signature header.

Idempotency

Every write operation uses a unique reference_id enforced at the database level (unique constraint). Prevents double-issuance under any failure condition.

Optimistic Locking

All balance mutations use version counters. Concurrent writes are detected and safely retried, preventing race conditions.

Immutable Ledger

Financial ledger entries are append-only. No updates or deletes. Every entry includes balance_before and balance_after snapshots for audit.

Monitoring & Alerts

Merchant Float Alerts — WARNING at <40%, URGENT at <25%, CRITICAL at <10% of allocated float. CRITICAL merchants are automatically hidden from catalog.
Voucher Expiration — Automated daily sweep expires ISSUED vouchers past their validity period. Treasury locks are cancelled, releasing liability.
Webhook Delivery — Every webhook delivery is logged with status, HTTP code, and error details. Failed deliveries are visible in the partner portal.
SMS Delivery — PIN delivery attempts are logged per voucher instance. Failed SMS triggers admin notification for manual intervention.
Settlement Tracking — All fee snapshots carry settlement_status (UNSETTLED/SETTLED). Provides real-time visibility into outstanding receivables.
Credit Exposure — Deferred partners have real-time credit utilization tracking. Issuance is blocked when credit_limit is reached.

Konekte — Digital Infrastructure for Haiti

This document is confidential and intended for authorized integration partners only.

Contact: info@konekte.org