Skip to content

M5-11 Credits/Vouchers Mechanism for Verification

Milestone: M5 — Disclosure and Verification SOW Reference: NFR5 (and referenced in the M5/M6 milestone description in Appendix 2) Requirement Clarity: ✅ Resolved 2026-09-15 — working end to end, nothing left to build on our side. Vouchers/credits are entirely managed on Velocity's side (earned via issuance, redeemed for vouchers) — no Registrar/CIH API exists for us to integrate against, and none is needed: verification against TESCO LLC's real disclosures now succeeds live. See the 2026-09-15 update below for the full resolution. Dev Status: ✅ Working — confirmed live 2026-09-15. payment.module.ts stays an empty stub deliberately; there is nothing for our own code to build here, this was never a code-side gap.

Overview

Implement the credit/voucher mechanism that pays for verification calls to the Credential Agent, per the original design: platform-pooled credits (time-limited) or organisation-purchased credits, exchanged for a Velocity Network voucher via the Registrar.

Backend Tasks

  • Confirm the mechanism still matches the original v3 doc's design, or get an updated spec
  • Implement credit balance tracking per organisation (and a platform-wide pool)
  • Implement the Registrar credit-transfer-for-voucher call
  • Use the voucher when calling the Credential Agent for verification (M5-08)

Frontend Tasks

  • Show credit balance to org admins
  • Handle the "out of credits" case gracefully in the verification flow

Dependencies

Acceptance Criteria

Not currently defined in SOW Appendix 3 — needs to be written once the mechanism is confirmed.

Existing Reference Material

  • Original v3 High-Level Requirements doc, Appendix 1, "Run Presentation Verification if requested" (not present in this repo — held by Curo/NeuralRays as the RFP-era document)

Blockers & Risks

  • Blocking: cannot be estimated or built without a confirmed spec — treat as equal priority to M5-02 and M7-01.

Update 2026-09-13 — this is a confirmed, paid MVP deliverable; mechanism clearer, still no callable API

Confirmed in-scope, not just referenced. The formal SOW's milestone table lists "credits/vouchers system" by name under M5/M6 — a real, contracted, paid deliverable (part of that milestone's 30% payment tranche), not just the bare Appendix-2 line item this task file originally described.

The economic mechanism, per a newly-found Velocity Credits.md: - Issuers (which TESCO LLC already is, via M3) earn Velocity Credits automatically per credential issued — "immediately upon issuing, regardless of whether the credentials are used." - Relying Parties can only buy Verification Vouchers with credits, not fiat directly — voucher price is "quoted in credits and fixed per transaction." - "The lion's share of Relying Parties are also Issuers... and they use their earned credits to buy vouchers." — meaning TESCO LLC may already have an unspent credit balance from its own M3 issuance activity that could fund a voucher, without needing anything purchased or granted. - If short, credits are bought via a licensed Credit Marketplace (an order-book exchange between credit buyers and sellers, run by vetted third-party "Credit Marketplace Operators") — not a direct API call.

Still no callable API for any of this. Checked every path in both the Registrar's and CIH's live OpenAPI specs — nothing exposes a credit or voucher balance, and nothing implements "redeem credits for a voucher." The closest lead is POST /events-processing/credential-issued-rewards on the Registrar (scope events:trigger) — name suggests it's tied to the issuance-reward mechanism above, but its schema is empty/undocumented in the spec, so its actual purpose is unconfirmed.

Concrete next step, in progress: ask Velocity directly (a) whether TESCO LLC already has an earned balance from M3 issuance, and (b) what credential-issued-rewards actually does — rather than continuing to guess from the whitepaper-level description above.

Update 2026-09-15 — vouchers added, verification confirmed working live

Andres Olave (Velocity CTO) confirmed by email: "The first 6 companies have had vouchers added to them and verify should now work." Includes TESCO LLC (the tenant shared across our local/dev/UAT environments).

Confirmed immediately after — ran a real verify against Krishnaraj Velayutham's disclosure (TESCO LLC): presentations/verify succeeded, no 402, 12/12 credentials verified true, all 6 checks passing. This unblocks M5-08/M5-09's live-data confirmation.

Update 2026-09-15 — rewards mechanism now confirmed working too. The item Andres was still tracking down ("why the rewards app didn't work for you") is now resolved and closed — the credit-earning mechanism is working, not just the one-time manual voucher top-up. Nothing outstanding on this task.

Still not self-service: there is still no API to check a voucher/credit balance proactively — worth remembering if this ever runs low again, since there's no way to catch it before a 402 in production without asking Velocity directly, same as this time.