Receipts API

Retrieve and verify Verity receipts -- cryptographic proofs of settlement execution.

GET/v1/receipts

List Verity receipts for your organization. Each receipt is a cryptographically verifiable proof of a completed settlement.

Response

{
  "data": [
    {
      "id": "rcp-s1t2u3v4",
      "settlementId": "stl-o1p2q3r4",
      "negotiationId": "neg-k1l2m3n4",
      "amount": { "value": 4500, "currency": "USD" },
      "verityHash": "0x9f3a7b2e...c4d1",
      "status": "valid",
      "createdAt": "2024-03-01T12:15:30Z"
    }
  ],
  "cursor": null,
  "hasMore": false
}

Error Codes

Status	Reason
401	Invalid or missing API key

GET/v1/receipts/:id

Retrieve full receipt details including the Verity proof object, policy snapshot, and all participating parties.

Response

{
  "id": "rcp-s1t2u3v4",
  "settlementId": "stl-o1p2q3r4",
  "negotiationId": "neg-k1l2m3n4",
  "amount": { "value": 4500, "currency": "USD" },
  "parties": [
    { "agentId": "agent-a1b2c3d4", "role": "initiator", "amount": 3150 },
    { "agentId": "agent-e5f6g7h8", "role": "responder", "amount": 1350 }
  ],
  "adapter": "stripe",
  "externalRef": "pi_3abc123def456",
  "verity": {
    "hash": "0x9f3a7b2e4c8d1a6f0e5b3972d4c8a1f6e0b5397...c4d1",
    "algorithm": "SHA-256",
    "proof": {
      "policySnapshot": "ps-2024-03-01-v2.4",
      "evidenceChain": ["ev-001", "ev-002", "ev-003"],
      "deterministic": true
    },
    "status": "valid",
    "verifiedAt": "2024-03-01T12:15:31Z"
  },
  "createdAt": "2024-03-01T12:15:30Z"
}

Error Codes

Status	Reason
404	Receipt not found

POST/v1/receipts/:id/verify

Re-verify a receipt against the Verity truth engine. Returns the current verification status and any discrepancies detected.

Request Body

{
  "includeEvidence": true,
  "recomputeHash": false
}

Response

{
  "receiptId": "rcp-s1t2u3v4",
  "status": "valid",
  "verityHash": "0x9f3a7b2e4c8d1a6f0e5b3972d4c8a1f6e0b5397...c4d1",
  "hashMatch": true,
  "policyCompliant": true,
  "evidence": [
    { "id": "ev-001", "type": "negotiation_accepted", "valid": true },
    { "id": "ev-002", "type": "settlement_executed", "valid": true },
    { "id": "ev-003", "type": "payment_confirmed", "valid": true }
  ],
  "verifiedAt": "2024-03-11T09:00:00Z"
}

Error Codes

Status	Reason
404	Receipt not found
409	Verification already in progress