Skip to main content

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.

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 (POSTED on IETF datatracker; revision -01 POSTED 2026-05-25), and published as a standalone reference implementation: Both packages depend on algovoi-substrate / @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. 
{
  "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
}
FieldTypeDescription
canon_versionstringIn-band canonicalisation rule pin. Fixed jcs-rfc8785-v1 for this version.
jurisdiction_flagsordered array of stringISO-3166-1 codes; primary jurisdiction first. Array order is significant under RFC 8785 §3.2.3.
original_payment_refstringsha256:{hex} reference to the original payment record (compliance receipt content_hash, STARK receipt, or operator-specific).
refund_amountobject{amount_minor: string, asset_id: string}. String amount_minor avoids float-precision and JS-integer-overflow concerns.
refund_provider_didstringDID URI identifying the refund-issuing entity.
refund_resultstring (closed enum)FULL / PARTIAL / REJECTED.
refund_timestamp_msintegerEpoch milliseconds. Substrate Rule 2: MUST be integer. RFC 3339 string forms rejected.

​
The closed enumeration: refund_result

ValueSemanticRegulatory significance
FULLEntire 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.
PARTIALLess 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.
REJECTEDA 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/. The canonicalisation layer underneath the refund receipt is the same JCS RFC 8785 layer covered by the 8-implementation cross-validation attestation 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

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

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 (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