Refund Receipt Format

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:

Python: algovoi-refund-receipt (live, v0.1.0)

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
}

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/. 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.

Get started

Platform

Concepts

Keystone

Agent Mesh

Substrate 2

Commercial

Open substrate

Payment protocols

Chains

Integrations

Help

Company

Why this format

Receipt shape

The closed enumeration: `refund_result`

Composition with compliance receipts

Conformance vectors

Quick start

Python

TypeScript

What this is NOT

Companion IETF Internet-Draft

See also

​Why this format

​Receipt shape

​The closed enumeration: refund_result

​Composition with compliance receipts

​Conformance vectors

​Quick start

​Python

​TypeScript

​What this is NOT

​Companion IETF Internet-Draft

​See also

Why this format

Receipt shape

The closed enumeration: `refund_result`

Composition with compliance receipts

Conformance vectors

Quick start

Python

TypeScript

What this is NOT

Companion IETF Internet-Draft

See also