> ## 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. # Refund Receipt Format > AlgoVoi authored refund receipt format: a categorical FULL, PARTIAL, REJECTED enumeration under JCS RFC 8785 that composes with compliance receipts. The refund receipt is the post-settlement counterpart to the compliance receipt. Where the compliance receipt records an admission-time screening decision, the refund receipt records a **reversal-of-funds event** under the same canonicalisation discipline. It is AlgoVoi-authored, specified in IETF Internet-Draft [`draft-hopley-x402-refund-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-refund-receipt/) (POSTED on IETF datatracker; revision -01 POSTED 2026-05-25), and published as a standalone reference implementation: * Python: [`algovoi-refund-receipt`](https://pypi.org/project/algovoi-refund-receipt/) (live, v0.1.0) Both packages depend on [`algovoi-substrate`](https://pypi.org/project/algovoi-substrate/) / [`@algovoi/substrate`](https://www.npmjs.com/package/@algovoi/substrate) for the JCS canonicalisation primitive. Apache 2.0. ## Why this format Refund events are state transitions that carry distinct regulatory significance from the original payment. A refund receipt format that collapses the outcome to a continuous percentage-of-original representation loses the load-bearing operational distinction: * Under UK Consumer Rights Act 2015 and EU Consumer Rights Directive 2011/83/EU Article 9, only a **FULL** refund within the statutory window closes the consumer's right to further remedy. * Under PSD2 (Directive 2015/2366) Article 89, a payer denied a refund must receive a documented denial — operationally distinct from a **PARTIAL** refund where some-but-not-all of the original amount has been returned. * Under UK POCA 2002 and EU AML Directives 5/6, a refund triggered by post-settlement sanctions or fraud detection requires audit-chain linkage back to the original compliance receipt for retention-period audit by competent authorities. The refund receipt format preserves these distinctions at the canonical-bytes level via a closed three-element enumeration. ## Receipt shape A refund receipt is a seven-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"], "original_payment_ref": "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f", "refund_amount": {"amount_minor": "100000", "asset_id": "USDC.6"}, "refund_provider_did": "did:web:api.algovoi.co.uk", "refund_result": "FULL", "refund_timestamp_ms": 1716494400000 } ``` | Field | Type | Description | | ---------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `canon_version` | string | In-band canonicalisation rule pin. Fixed `jcs-rfc8785-v1` for this version. | | `jurisdiction_flags` | ordered array of string | ISO-3166-1 codes; primary jurisdiction first. Array order is significant under RFC 8785 §3.2.3. | | `original_payment_ref` | string | `sha256:{hex}` reference to the original payment record (compliance receipt content\_hash, STARK receipt, or operator-specific). | | `refund_amount` | object | `{amount_minor: string, asset_id: string}`. String `amount_minor` avoids float-precision and JS-integer-overflow concerns. | | `refund_provider_did` | string | DID URI identifying the refund-issuing entity. | | `refund_result` | string (closed enum) | `FULL` / `PARTIAL` / `REJECTED`. | | `refund_timestamp_ms` | integer | Epoch milliseconds. **Substrate Rule 2**: MUST be integer. RFC 3339 string forms rejected. | ## The closed enumeration: `refund_result` | Value | Semantic | Regulatory significance | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `FULL` | Entire original amount returned. | Closes consumer's right to further remedy under UK Consumer Rights Act 2015 and EU Consumer Rights Directive 2011/83/EU Article 9. | | `PARTIAL` | Less than the original amount returned. `refund_amount` carries the actual refunded value; the verifier compares against the original via `original_payment_ref` linkage. | Does not close consumer-rights remedies; further refund obligations may remain. | | `REJECTED` | A refund request was processed and denied. No funds moved. The receipt records the denial event so downstream dispute chains can reference it. | Required under PSD2 (Directive 2015/2366) Article 89 for unauthorised-payment refund disputes; documented denial obligation. | Each value produces a byte-distinct `content_hash` from the other two. Implementations MUST reject any other value at validation time before canonicalisation. ## Composition with compliance receipts A refund receipt's `original_payment_ref` MAY reference the `content_hash` of a compliance receipt. The two receipts compose into one audit-chain segment recording the full admission-through-refund lifecycle: ``` chain row N chain row N+1 +------------+ +------------+ | compliance |-->| refund | | receipt | | receipt | | (ALLOW) | | (FULL) | +------------+ +------------+ ``` A verifier walking this segment confirms: (a) the compliance receipt admitted the original payment; (b) the refund receipt links to that admission via `original_payment_ref`; (c) the chain rows preserve hash-linkage with no truncation or reordering. ## Conformance vectors Eight byte-level reference vectors + five pair invariants + three chain invariants are published at [`algovoi-jcs-conformance-vectors/vectors/refund_receipt_v1/`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/refund_receipt_v1). The canonicalisation layer underneath the refund receipt is the same JCS RFC 8785 layer covered by the [8-implementation cross-validation attestation](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/blob/main/_attestations/2026-05-24-8-impl-cross-validation.md) dated 2026-05-24. The refund receipt's `content_hash` reproduces byte-identical under any of the eight implementations (Python, TypeScript, Go, Rust, Java, PHP, .NET, Ruby). ## Quick start ### Python ```python theme={null} from algovoi_refund_receipt import build_refund_receipt from algovoi_substrate import sha256_jcs receipt = build_refund_receipt( original_payment_ref="sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f", refund_result="FULL", refund_timestamp_ms=1716494400000, refund_provider_did="did:web:api.algovoi.co.uk", refund_amount={"amount_minor": "100000", "asset_id": "USDC.6"}, jurisdiction_flags=["UK", "EU"], ) print(sha256_jcs(dict(receipt))) # 7fdd283c3a8abb14d893999d1d16e2f7697ad0539250f2e0fc3e31ce89943dcb ``` ### TypeScript ```typescript theme={null} import { buildRefundReceipt } from "@algovoi/refund-receipt"; import { sha256Jcs } from "@algovoi/substrate"; const receipt = buildRefundReceipt({ original_payment_ref: "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f", refund_result: "FULL", refund_timestamp_ms: 1716494400000, refund_provider_did: "did:web:api.algovoi.co.uk", refund_amount: { amount_minor: "100000", asset_id: "USDC.6" }, jurisdiction_flags: ["UK", "EU"], }); console.log(sha256Jcs(receipt)); // 7fdd283c3a8abb14d893999d1d16e2f7697ad0539250f2e0fc3e31ce89943dcb ``` ## What this is NOT * **Not a dispute resolution protocol.** Disputes are multi-party state machines. The refund receipt records one state transition; orchestration is operator-layer. * **Not a cross-network settlement attestation.** A refund receipt MAY refund in a different asset than the original payment (e.g. paid USDC on Base, refunded USDC on Solana), but the cross-chain mechanism is out of scope of this format. * **Not a chargeback / interchange format.** ISO 8583 and ISO 20022 message families cover card-network chargeback. This format applies to agentic-payment receipts. * **Not the only refund format.** Operators MAY emit richer receipts with additional internal fields. This format specifies the minimum byte-load-bearing surface required for cross-implementation verifiability. ## Companion IETF Internet-Draft [`draft-hopley-x402-refund-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-refund-receipt/) (Independent Submission, Informational) is the canonical specification. AlgoVoi-authored, sole authorship. The draft pins `urn:x402:canonicalisation:jcs-rfc8785-v1` and specifies the seven-field receipt format, audit-chain composition, and year-N auditability properties. ## See also * [Canonicalisation substrate](/canonicalisation-substrate) — the JCS RFC 8785 + Substrate Rule 2 discipline * [Conformance vectors](/conformance-vectors) — the full vector corpus * [Audit verifier](/audit-verifier) — selective-disclosure audit-chain verifier * [Substrate authorship and provenance](/substrate-authorship-provenance) — citable record of AlgoVoi-authored substrate artefacts