Skip to main content
The compliance receipt records the outcome of an admission-time compliance screen. It is the first receipt in the AlgoVoi payment lifecycle and the anchor for the downstream chain.

​
Protocol coverage

The AlgoVoi gateway issues a compliance receipt on every incoming payment request across all four payment protocols:
ProtocolTriggerReceipt on
x402POST /checkout/{token}Every admission screen
MPPPOST /mpp/{resource_id}Every admission screen
AP2POST /ap2/initiateEvery admission screen
A2APOST /a2a/v1/tasksEvery admission screen
The receipt is AlgoVoi-authored, specified in IETF Internet-Draft draft-hopley-x402-compliance-receipt (POSTED on IETF datatracker 2026-05-23, Independent Submission, Informational), and implemented as part of the substrate reference package: Apache 2.0.

​
Lifecycle position

admission         settlement        refund
compliance   -->  settlement   -->  refund
receipt           attestation       receipt
The compliance receipt is the entry point for the audit chain. Every downstream receipt — settlement attestation, refund receipt, cancellation receipt — chains back to the compliance receipt via content_hash linkage.

​
Receipt shape

A compliance receipt is a six-field JSON object canonicalised under RFC 8785 (JCS). Field names are sorted lexicographically by JCS during canonicalisation. 
{
  "canon_version": "jcs-rfc8785-v1",
  "jurisdiction_flags": ["UK", "EU"],
  "payer_ref": "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  "screen_provider_did": "did:web:api.algovoi.co.uk",
  "screen_result": "ALLOW",
  "screen_timestamp_ms": 1716494400000
}
FieldTypeDescription
canon_versionstringIn-band canonicalisation pin. Fixed jcs-rfc8785-v1.
jurisdiction_flagsordered arrayISO-3166-1 codes. Order significant under RFC 8785.
payer_refstringsha256:{hex} content-addressed reference to the payer identity record. SHA-256(network:address).
screen_provider_didstringDID URI of the screening party. Resolves without operator runtime access.
screen_resultstring (closed enum)ALLOW / REFER / DENY.
screen_timestamp_msintegerEpoch milliseconds. Substrate Rule 2 — MUST be integer, not float string.

​
The closed enumeration: screen_result

ValueSemanticRegulatory significance
ALLOWPayer passed all screening checks. Payment may proceed.No SAR obligation triggered. Baseline positive record in the audit chain.
REFERPayer matched a watchlist or risk threshold. Requires manual review before proceeding.Triggers SAR obligation under Proceeds of Crime Act 2002 s.330 (UK) / AMLR Article 56 (EU). Payment held pending review outcome.
DENYPayer matched sanctions list or failed mandatory check. Payment blocked.Triggers tipping-off compliance under SAMLA 2018 s.20 — reason for denial MUST NOT be disclosed to the payer.
Each value produces a byte-distinct content_hash under JCS. Probability scores, risk tiers, or intermediate states are not acceptable substitutes in the canonical receipt record.

​
payer_ref construction

payer_ref is a content-addressed reference to the payer identity — not the payer’s raw address. The preimage is {chain_network}:{wallet_address}, hashed with SHA-256: 
import hashlib
payer_ref = "sha256:" + hashlib.sha256(f"{network}:{address}".encode()).hexdigest()
This means the receipt does not expose the payer’s wallet address at the canonical-bytes level. A verifier with access to the original network+address can reconstruct the hash independently.

​
Why this format

The compliance receipt exists to create an independently verifiable admission-time record:
  • Under AMLD6 / AMLR Article 56, operators must retain records of every transaction screening decision with enough detail to reconstruct the decision at audit time.
  • Under SAMLA 2018 s.20 (UK), the reason for a DENY must not be disclosed to the payer. The receipt records the categorical outcome; the screening detail stays in the operator’s internal records.
  • Under PSD2 Article 74 (Directive 2015/2366), transaction monitoring records must be available to competent authorities. A content_hash-chained receipt that a third party can verify without operator runtime access satisfies this without exposing operator internals.
The closed three-element enum ensures that every compliance outcome is a positive record — a DENY receipt is not missing data, it is a byte-distinct verifiable artefact.

​
Audit chain linkage

Every compliance receipt is appended to the SHA-256 JCS hash-chained audit ledger: 
content_hash_n = sha256(jcs(receipt_n))
prev_hash_n    = content_hash_(n-1)
A verifier reconstructs the chain from raw rows without trusting the operator’s infrastructure. The chain is stored in Backblaze B2 with Object Lock COMPLIANCE mode retention (seven years).

​
Conformance vectors

8 byte-level reference vectors + 5 pair invariants + 3 chain invariants at vectors/compliance_receipt_v1/. Reproduce the full 8-implementation cross-validation: 
git clone https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors
cd algovoi-jcs-conformance-vectors/vectors/compliance_receipt_v1
python runner_python.py   # expects: PASS 8 vectors + 5 pair + 3 chain
node runner_node.js       # expects: PASS

​
Quick start

​
TypeScript

import { buildComplianceReceipt } from "@algovoi/substrate";
import { sha256Jcs } from "@algovoi/substrate";

const receipt = buildComplianceReceipt({
  payer_ref: "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  screen_result: "ALLOW",
  screen_timestamp_ms: 1716494400000,
  screen_provider_did: "did:web:api.algovoi.co.uk",
  jurisdiction_flags: ["UK", "EU"],
});
console.log(sha256Jcs(receipt));
// content_hash suitable for audit chain linkage

​
Python

from algovoi_substrate import build_compliance_receipt, sha256_jcs

receipt = build_compliance_receipt(
    payer_ref="sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
    screen_result="ALLOW",
    screen_timestamp_ms=1716494400000,
    screen_provider_did="did:web:api.algovoi.co.uk",
    jurisdiction_flags=["UK", "EU"],
)
print(sha256_jcs(receipt))

​
What this is NOT

  • Not a risk score. The receipt records a categorical admission decision, not a continuous risk signal. Upstream risk models emit scores; the receipt records the policy outcome of applying those scores.
  • Not a KYC certificate. The receipt records that a compliance screen was performed and its outcome. Full KYC documentation is held in the operator’s internal records, not in the canonical receipt.
  • Not a payment confirmation. The compliance receipt records admission. Settlement is recorded separately in the settlement attestation.

​
Companion IETF Internet-Draft

draft-hopley-x402-compliance-receipt (Independent Submission, Informational). AlgoVoi-authored, sole authorship. Normatively references draft-hopley-x402-canonicalisation-jcs-v1.

​
See also