> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Compliance Receipt Format

> AlgoVoi authored admission time compliance receipt format: a categorical ALLOW, REFER, DENY enumeration under JCS RFC 8785, with a companion IETF draft.

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:

| Protocol | Trigger                   | Receipt on             |
| -------- | ------------------------- | ---------------------- |
| **x402** | `POST /checkout/{token}`  | Every admission screen |
| **MPP**  | `POST /mpp/{resource_id}` | Every admission screen |
| **AP2**  | `POST /ap2/initiate`      | Every admission screen |
| **A2A**  | `POST /a2a/v1/tasks`      | Every admission screen |

The receipt is AlgoVoi-authored, specified in IETF Internet-Draft [`draft-hopley-x402-compliance-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-compliance-receipt/) (POSTED on IETF datatracker 2026-05-23, Independent Submission, Informational), and implemented as part of the substrate reference package:

* TypeScript: [`@algovoi/substrate`](https://www.npmjs.com/package/@algovoi/substrate) — `buildComplianceReceipt()` (live, v0.3.0)
* Python: [`algovoi-substrate`](https://pypi.org/project/algovoi-substrate/) — `build_compliance_receipt()` (live, v0.3.0)

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.

```json theme={null}
{
  "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
}
```

| Field                 | Type                 | Description                                                                                        |
| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
| `canon_version`       | string               | In-band canonicalisation pin. Fixed `jcs-rfc8785-v1`.                                              |
| `jurisdiction_flags`  | ordered array        | ISO-3166-1 codes. Order significant under RFC 8785.                                                |
| `payer_ref`           | string               | `sha256:{hex}` content-addressed reference to the payer identity record. SHA-256(network:address). |
| `screen_provider_did` | string               | DID URI of the screening party. Resolves without operator runtime access.                          |
| `screen_result`       | string (closed enum) | `ALLOW` / `REFER` / `DENY`.                                                                        |
| `screen_timestamp_ms` | integer              | Epoch milliseconds. **Substrate Rule 2** — MUST be integer, not float string.                      |

## The closed enumeration: `screen_result`

| Value   | Semantic                                                                               | Regulatory significance                                                                                                          |
| ------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `ALLOW` | Payer passed all screening checks. Payment may proceed.                                | No SAR obligation triggered. Baseline positive record in the audit chain.                                                        |
| `REFER` | Payer 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. |
| `DENY`  | Payer 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:

```python theme={null}
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/`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/compliance_receipt_v1).

Reproduce the full 8-implementation cross-validation:

```bash theme={null}
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

```typescript theme={null}
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

```python theme={null}
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](/settlement-attestation).

## Companion IETF Internet-Draft

[`draft-hopley-x402-compliance-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-compliance-receipt/) (Independent Submission, Informational). AlgoVoi-authored, sole authorship. Normatively references [`draft-hopley-x402-canonicalisation-jcs-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/).

## See also

* [Canonicalisation substrate](/canonicalisation-substrate) — the JCS discipline
* [Settlement attestation](/settlement-attestation) — post-admission counterpart
* [Refund receipt](/refund-receipt) — post-settlement counterpart
* [Payment Evidence Frame](/payment-evidence-frame) — wraps all receipt types into one verifiable artefact
* [Conformance vectors](/conformance-vectors) — full vector corpus
* [Substrate authorship and provenance](/substrate-authorship-provenance) — citable AlgoVoi authorship record
* [Verifiable x402 receipts](/verifiable-x402-receipt) — the full x402 receipt chain (compliance, settlement, refund)
* [No-PII compliance receipts](/no-pii-compliance-receipt) — how the payer reference is hashed so no wallet address appears in the canonical bytes