From receipt verification blueprint to working proof direction.
v6.1 defines what the first backend-supported receipt verification endpoint should prove before SafeGate claims production readiness.
The goal is not to overclaim. The goal is to define the smallest honest working proof: one receipt ID enters, a bounded verification response returns, and the audit trail records what happened.
30-Second v6.1 Summary
SafeGate should move from static receipt verification architecture toward a backend-supported endpoint: receipt ID in → verified payment/access/merchant state out → audit event recorded.
1. Target Endpoint Shape
Proposed first backend-supported endpoint direction:
GET /api/receipt/verify?receiptId=SG-RCPT-1781465776152
This endpoint should not expose secrets, should not reveal unnecessary user data, and should fail securely if verification is unclear.
2. Minimal Working Proof Criteria
Known Receipt ID
A controlled receipt ID can be queried without exposing backend secrets.
Payment State
The response returns a bounded payment state such as PAYMENT_FINALIZED.
Access State
The response returns access state such as UNLOCKED or LOCKED.
Merchant Evidence
The response confirms whether merchant-side evidence exists.
Audit Event
Every verification attempt creates a minimal audit event.
Fail Secure
Invalid, missing, ambiguous, duplicate, or rate-limited cases do not unlock access.
3. Proposed Success Response
{
"ok": true,
"statusCode": 200,
"code": "RECEIPT_VERIFIED",
"mode": "backend_supported_direction",
"receiptId": "SG-RCPT-1781465776152",
"orderId": "TP-DEMO-273551",
"network": "Pi Testnet",
"paymentState": "PAYMENT_FINALIZED",
"receiptProof": "CREATED",
"accessState": "UNLOCKED",
"merchantRecord": "FOUND",
"auditEvent": {
"eventType": "RECEIPT_VERIFIED",
"result": "OK",
"safeBehavior": "CONTINUE",
"createdAt": "mock_timestamp"
},
"boundaries": {
"productionPublicApiClaim": false,
"productionApiKeyIssued": false,
"backendSecretExposed": false,
"piMainnetSettlementClaim": false
}
}
4. Required Error Responses
400 INVALID_RECEIPT_ID
Receipt ID format is missing or invalid.
404 RECEIPT_NOT_FOUND
No controlled evidence record exists for this receipt ID.
409 DUPLICATE_OR_REPLAY_ATTEMPT
Duplicate verification or replay-like behavior is detected and logged.
429 RATE_LIMITED
Merchant/API consumer exceeded verification limits.
503 VERIFICATION_AMBIGUOUS
Payment state cannot be confirmed safely; fail secure.
500 INTERNAL_ERROR_SAFE
Generic safe error. No stack trace, secret, database string, or internal config leaks.
5. Working Proof Must Not Mean Production Claim
A working receipt verify endpoint can prove backend behavior without claiming production readiness. SafeGate should clearly separate:
- Backend-supported proof: endpoint responds from controlled records.
- Production public API: not claimed until auth, rate-limit, monitoring, audit, security review, and operational controls mature.
6. Backend Implementation Direction
{
"recommendedRuntime": "Node.js / Vercel serverless function or equivalent backend route",
"minimumStorage": "controlled receipt evidence table",
"minimumInputs": [
"receiptId"
],
"minimumChecks": [
"validate receiptId format",
"lookup controlled receipt record",
"confirm payment state",
"confirm access state",
"confirm merchant record",
"write audit event",
"return bounded response"
],
"mustNotExpose": [
"service role key",
"wallet passphrase",
"access token",
"database connection string",
"raw internal exception",
"private user data"
]
}
7. Next Stage Linkage
v6.2 Edge Case Test Plan
Wrong amount, duplicate payment, callback delay, replay attempt, ambiguous verification, rate-limit, and safe internal error cases.
v6.3 Evidence Timeline
Show verification and audit events as minimal event/time/result rows.
v6.4 Security Hardening
Rate limits, secret rotation, audit log retention, error safety, and abuse controls.
8. Public Boundary
SafeGate v6.1 is a direction/spec page. It does not claim a production public API, does not issue real API keys, does not create production merchant accounts, does not expose backend secrets, and does not claim Pi Mainnet settlement proof.
Current evidence remains Pi Testnet controlled post-payment trust flow.