Skip to main content
Creates a cryptographically signed, transparency-log-anchored receipt event. Receipts are validated against the registered receipt type schema before signing.

​
Receipt Types

Platform-defined receipt families are available to all tenants. Custom receipt types can be registered via the tenant console.
TypeNameRequired Fields
payment_receiptPayment Receiptamount, currency, provider, provider_reference, subject
security_event_receiptSecurity Event Receiptevent_type, severity, subject, outcome
delivery_receiptDelivery Receiptitem_reference, recipient, delivery_method, delivered_at
compliance_receiptCompliance Receiptcheck_type, subject, result, framework
custom_receiptCustom Receiptsubject, event

​
Canonical Envelope

Every receipt — regardless of type — is wrapped in a canonical envelope before signing: 
{
  "spec_version": "receipt-v1",
  "receipt_type": "payment_receipt",
  "receipt_version": "1.0.0",
  "receipt_id": "<uuid>",
  "tenant_id": "<uuid>",
  "issuer_id": "<uuid>",
  "issued_at": "<RFC3339>",
  "subject": "<string>",
  "payload": { ... },
  "metadata": { ... }
}
The SHA-256 hash of this canonical JSON is what gets signed and anchored in the transparency log.

​
Example: Mint a Payment Receipt

curl -X POST https://api.truthlocks.com/v1/receipts \
  -H "X-API-Key: tl_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "kid": "ed-key-2026",
    "alg": "Ed25519",
    "receipt_type": "payment_receipt",
    "subject": "customer@example.com",
    "payload": {
      "amount": 5000,
      "currency": "USD",
      "provider": "stripe",
      "provider_reference": "ch_3Pxabc123"
    }
  }'

​
Schema Validation

The payload field is validated against the receipt type’s JSON Schema before signing. Missing required fields return 422 Unprocessable Entity with a list of the missing fields.
The Idempotency-Key header is required. If you submit the same key twice with the same parameters, the original receipt is returned rather than creating a duplicate.

​
Webhook Event

A receipt.created webhook event is delivered to all configured endpoints after a successful mint: 
{
  "event_type": "receipt.created",
  "receipt_id": "<uuid>",
  "receipt_type": "payment_receipt",
  "tenant_id": "<uuid>",
  "issued_at": "<RFC3339>"
}