Skip to main content
POST
/
v1
/
receipts
Mint receipt
curl --request POST \
  --url https://api.truthlocks.com/v1/receipts \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "issuer_id": "<string>",
  "kid": "<string>",
  "receipt_type": "<string>",
  "subject": "<string>",
  "payload": {},
  "metadata": {}
}
'
{
  "receipt_id": "<string>",
  "receipt_type": "<string>",
  "status": "<string>",
  "issuer_id": "<string>",
  "subject": "<string>",
  "signature": {
    "alg": "<string>",
    "kid": "<string>",
    "value": "<string>"
  },
  "issued_at": "<string>"
}
Creates a cryptographically signed, transparency-log-anchored receipt event. Receipts are validated against the registered receipt type schema before signing.

​
Receipt types

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

​
Headers

​
Idempotency-Key
string
required
UUID for idempotent minting. If you submit the same key twice, the original receipt is returned.

​
Request

​
issuer_id
string
required
UUID of the issuer signing the receipt.
​
kid
string
required
Key ID of the signing key.
​
alg
string
required
Signing algorithm: Ed25519, ES256, or RS256.
​
receipt_type
string
required
Receipt type name (e.g. payment_receipt, security_event_receipt, or a custom type).
​
subject
string
required
Subject identifier for the receipt.
​
payload
object
required
Receipt payload — validated against the receipt type’s JSON Schema.
​
metadata
object
Optional metadata attached to the receipt envelope.

​
Response

​
receipt_id
string
UUID of the created receipt.
​
receipt_type
string
The receipt type name.
​
status
string
active
​
issuer_id
string
UUID of the signing issuer.
​
subject
string
Subject identifier.
​
signature
object
Cryptographic signature: alg, kid, value.
​
issued_at
string
ISO 8601 timestamp.

​
Webhook event

A receipt.created webhook event is delivered to all configured endpoints after a successful mint.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Headers

​
Idempotency-Key
string
required

UUID for idempotent minting

Body

application/json
​
issuer_id
string
required

UUID of the issuer signing the receipt

​
kid
string
required

Key ID of the signing key

​
alg
enum<string>
required

Signing algorithm

Available options:
Ed25519,
ES256,
ES384,
ES512,
RS256,
RS384,
RS512,
PS256,
PS384,
PS512
​
receipt_type
string
required

Receipt type name

​
subject
string
required

Subject identifier

​
payload
object
required

Receipt payload validated against schema

​
metadata
object

Optional metadata

Response

Receipt created

​
receipt_id
string
​
receipt_type
string
​
status
string
​
issuer_id
string
​
subject
string
​
signature
object
​
issued_at
string