SafeGate v5.1 / Public Mock / Architecture Boundary

Receipt Verify API Mock

SafeGate converts a finalized Pi Testnet payment into a verifiable post-payment trust record: PAYMENT_FINALIZED → receipt proof → access unlocked → merchant record.

Important boundary: This page describes a public mock and architecture direction. It is not a production public API, does not expose API keys, does not expose backend secrets, and does not claim Pi Mainnet settlement proof.

1. Why Receipt Verification Matters

In payment-based digital access flows, the payment itself is only the trigger. The real product is the trust layer that proves what happened after payment: whether the payment was finalized, whether access was unlocked, whether a receipt was generated, and whether the merchant-side record exists.

SafeGate principle:
Payment is the trigger. Trust is the product.

2. Mock Endpoint Shape

The future Receipt Verify API can expose a minimal verification endpoint for merchants, reviewers, or controlled integrations. The current version is only a public mock contract.

GET /api/receipt/verify?receiptId=SG-RCPT-1781465776152

3. Mock Success Response

{
  "ok": true,
  "mode": "public_mock",
  "receiptId": "SG-RCPT-1781465776152",
  "paymentNetwork": "Pi Testnet",
  "paymentState": "PAYMENT_FINALIZED",
  "accessState": "UNLOCKED",
  "merchantRecord": "FOUND",
  "settlementClaim": "NO_MAINNET_SETTLEMENT_CLAIM",
  "productionApi": false,
  "verifiedAt": "mock_timestamp",
  "trustSummary": {
    "paymentFinalized": true,
    "receiptProofCreated": true,
    "accessUnlocked": true,
    "merchantRecordFound": true
  }
}

4. Mock Failure Response

{
  "ok": false,
  "mode": "public_mock",
  "receiptId": "SG-RCPT-UNKNOWN",
  "paymentState": "UNKNOWN",
  "accessState": "LOCKED_OR_UNKNOWN",
  "merchantRecord": "NOT_FOUND",
  "productionApi": false,
  "reason": "Receipt was not found in the controlled evidence set."
}

5. Security Boundaries

No Secret Exposure

Backend secrets, service role keys, wallet passphrases, access tokens, and private infrastructure credentials must never be exposed through public pages or client-side code.

No Production API Claim

This page is a mock architecture layer. It does not claim a live production public API or external merchant API key system.

No Mainnet Settlement Claim

Current evidence is based on controlled Pi Testnet payment flow. Mainnet settlement verification is a future adapter boundary.

Server-Side Verification First

Real verification should remain server-side, with durable storage, replay protection, idempotency, rate limiting, and signed receipt validation.

6. Controlled Evidence Mapping

The current public evidence set includes five controlled tester flows. Each case follows the same trust pattern: finalized payment, unlocked access, receipt proof, and merchant-side record.

[
  {
    "tester": "Ibrahim",
    "orderId": "TP-DEMO-273551",
    "state": "PAYMENT_FINALIZED",
    "access": "UNLOCKED",
    "receiptId": "SG-RCPT-1781465776152",
    "merchantRecord": "FOUND"
  },
  {
    "tester": "Gonul",
    "orderId": "TP-DEMO-482507",
    "state": "PAYMENT_FINALIZED",
    "access": "UNLOCKED",
    "receiptId": "SG-RCPT-1781527252627",
    "merchantRecord": "FOUND"
  },
  {
    "tester": "Tugba",
    "orderId": "TP-DEMO-519861",
    "state": "PAYMENT_FINALIZED",
    "access": "UNLOCKED",
    "receiptId": "SG-RCPT-1781533835531",
    "merchantRecord": "FOUND"
  },
  {
    "tester": "Unal",
    "orderId": "TP-DEMO-480574",
    "state": "PAYMENT_FINALIZED",
    "access": "UNLOCKED",
    "receiptId": "SG-RCPT-1781542533448",
    "merchantRecord": "FOUND"
  },
  {
    "tester": "Turgay",
    "orderId": "TP-DEMO-227028",
    "state": "PAYMENT_FINALIZED",
    "access": "UNLOCKED",
    "receiptId": "SG-RCPT-1781550995179",
    "merchantRecord": "FOUND"
  }
]

7. Future Production Direction

Merchant-scoped API keys without exposing backend secrets.
Signed receipt proof with server-side validation.
Rate limiting per merchant/API key, not only per IP.
Idempotency protection for repeated verification attempts.
Durable audit trail for receipt verification attempts.
Adapter-ready design for Pi-first and future chain-agnostic payment verification.