Proof receipts and escrow#
Completion is a claim. A proof receipt is the evidence. Remindify stores the evidence text, hashes it with SHA-256, and signs a canonical payload with HMAC-SHA256 on the server. An AI proof auditor decides whether the evidence actually satisfies the obligation. Escrow releases only against a receipt the auditor has verified, and settlement runs entirely through PayPal.
The receipt lifecycle#
| State | Meaning |
|---|---|
filed |
Created by a completion, an agent or the Trust page. The evidence, hashes and server signature exist. |
verified |
The proof auditor accepted the evidence at or above the confidence threshold. |
rejected |
The auditor found the evidence insufficient or inconsistent. The receipt stays visible. |
settled |
A PayPal escrow was captured and the provider was paid against this receipt. |
A receipt records:
proof_label— the human-readable reference, such asCloudflare order CF-88213.proof_hash— a SHA-256 hash of the obligation id, the evidence text and the filing time.artifactandartifact_hash— the evidence text and its own SHA-256 hash.actor_id,actor_typeandactor— who filed it.completed_at,statusandsignature.audit— the auditor verdict, confidence and discrepancies once audited.settlement— the capture, payout, fee and net once released.
Proof is a reference and an evidence excerpt, not a stored document. File uploads are not part of the current preview. Keep the original receipt in your own storage and put its identifier, URL or hash in proof.
The signature#
The server signs a canonical JSON payload:
{
"obligation_id": "ob_domain",
"actor_id": "ag_ledger",
"actor_type": "human",
"proof_hash": "9f2c...",
"completed_at": "2026-10-28T09:00:00.000Z"
}The signature is HMAC-SHA256(TRUST_RECEIPT_SECRET, payload). It is computed when the receipt is filed and recomputed whenever the receipt changes, including after an audit. The only secret is the server's receipt secret, and nothing is signed in the browser.
A signed-in workspace member can check a receipt directly:
curl "$REMINDIFY_URL/api/trust/receipts/rcpt_.../verify"{
"status": "verified",
"valid": true,
"proof_hash": "9f2c...",
"settlement": null
}valid compares the stored signature with a fresh HMAC over the canonical payload, so an edited receipt fails verification. settlement is null until an escrow release settles the receipt.
The AI Proof Auditor#
POST /api/trust/receipts/:id/audit scores the evidence against the obligation's amount, reference and date. It uses Gemini 2.5 Flash with structured JSON output (AI_MODEL_ID, default gemini-2.5-flash) and returns:
verified— whether the evidence is sufficient;confidence— a score between 0 and 1;matching_verdict— a short explanation;discrepancies— the specific mismatches a payer can act on.
The release threshold is AUDIT_MIN_CONFIDENCE (default 0.8). A confident model answer below the threshold is rejected and the threshold is named in the discrepancies.
Without GEMINI_API_KEY, the auditor falls back to deterministic offline rules that look for the amount, a confirmation or reference number, a date and the words of the proof requirement. A provider error uses the same fallback and labels the result deterministic_fallback, so a network hiccup never silently approves a payout.
A release runs the auditor first when the receipt is not already verified. A rejected proof returns proof_rejected and leaves the payer's hold untouched.
Escrow#
Escrow is a PayPal authorization hold. The payer approves a hold for up to 29 days (HOLD_DAYS=29) and nothing moves yet. On release Remindify captures the authorization and sends a PayPal Payout to the provider's PayPal email, net of the platform fee.
| State | Reached by | Meaning |
|---|---|---|
draft |
POST /api/trust/escrows |
Amount, obligation, provider and payee email recorded. |
hold_pending |
/hold |
A PayPal order with intent=AUTHORIZE exists and awaits the payer. |
authorized |
PayPal return to /api/trust/escrows/paypal/return?token= |
The payer approved the hold; no money has moved. |
captured_awaiting_payout |
/release when the payout fails |
The hold was captured, but the provider was not paid. |
released |
/release |
Capture and payout both succeeded against a verified receipt. |
voided |
/void |
The hold was released back to the payer. |
Rules:
- Creating an escrow requires a PayPal email for the payee. Without one the route returns
payee_required. - The amount must be positive and is settled in USD.
- A hold needs
PAYPAL_CLIENT_IDandPAYPAL_CLIENT_SECRET; otherwise the route returnspaypal_not_configured. - Release requires a verified receipt for the same obligation. A receipt for another obligation returns
proof_wrong_obligation; a missing one returnsproof_required. - Release works from
authorizedorcaptured_awaiting_payout. A draft returnsescrow_not_releasable. - A payout failure parks the escrow in
captured_awaiting_payoutwithpayout_failed. It is never reported as settled, and the payout can be retried. - Region gating applies to creating an escrow, placing a hold and releasing it.
curl -X POST http://localhost:4178/api/trust/escrows \
-H "cookie: remindify_session=..." \
-H "content-type: application/json" \
-d '{
"obligation_id": "ob_payroll",
"provider_id": "pv_meron",
"amount": 120,
"payee_paypal_email": "meron@example.com"
}'The fee is deducted from the captured amount at release. With PAYPAL_PLATFORM_FEE_PERCENT=10, a $612 escrow captures $612, records a $61.20 platform fee and pays the provider $550.80. There is no token and no custody: Remindify never holds a balance or a card, and PayPal moves the money between the payer, the merchant account and the provider.
Escrow is a proof-gated trust boundary, not a general payment processor. It does not settle cards, run a refund desk or hold fiat outside PayPal. A receipt does not prove the underlying work is good. For an immediate payment with no release condition, use PayPal Orders (Payments).
What is verifiable#
A third party can verify:
- the HMAC signature against the canonical payload and the receipt fields;
- the proof hash and the evidence hash against the evidence text;
- the auditor verdict, confidence and engine;
- the settlement record, including capture id, payout batch, fee and net;
- the event log entry that says who filed it and when.
They cannot verify the underlying document unless you publish it. The hash proves that a document did not change after filing; it does not prove the document is true.