Receipts & Reconciliation

Availability: coming soon. This page is the contract of record, published ahead of rollout; field names may still change until frozen.

Machine-readable proof of what an execution actually did — the FX conversion that happened (offramp block), the fiat delivery that happened (payout block), and the fees charged — plus an aggregate reconciliation view for joining many executions against your own ledger.

Payout partners each produce different receipt formats; Ezys normalizes them into the single schema below, so consumers never handle provider-specific shapes.

Get receipt

GET /v1/executions/{reference}/receipt

Returns the normalized receipt for one completed (or terminally failed) execution. {reference} resolution follows the same rules as the Status API.

Read endpoints are authenticated with an API key (X-API-Key) — see Authentication.

Response

{
  "clientReference": "NR-2026-000123",
  "provider": "hopnow",
  "offramp": {
    "fromAsset": "USDC",
    "fromAmountMinor": "10003250000",
    "toAsset": "USD",
    "toAmountMinor": "1000000000",
    "fxRate": "0.99968",
    "roundingRule": "floor",
    "occurredAt": "2026-07-15T02:10:11.902Z"
  },
  "payout": {
    "toAmountMinor": "1000000000",
    "beneficiary": {
      "nameMasked": "J*** D**",
      "accountLast4": "6789",
      "accountHash": "d1f8a4…"
    },
    "bankRef": "FEDWIRE-20260715-00123",
    "occurredAt": "2026-07-15T02:14:02.000Z"
  },
  "fees": [
    { "type": "protocol_fee", "amountMinor": "1500000", "currency": "USDC", "collection": "deducted" },
    { "type": "payout_fee",   "amountMinor": "2500",    "currency": "USD",  "collection": "deducted" },
    { "type": "network_fee",  "amountMinor": "0",       "currency": "USDC", "collection": "absorbed" }
  ],
  "txHash": "0x9c1d8f2e…",
  "issuedAt": "2026-07-15T02:14:05.113Z"
}

Field	Type	Description
clientReference	string	Your reference key, echoed verbatim — the join key against your ledger
provider	string	Payout provider that executed the delivery (normalized identifier)
offramp	object	The FX conversion that actually happened. See Offramp block
payout	object	The fiat delivery that actually happened. See Payout block
fees	array	Fees actually charged (or absorbed), itemized and kept separate from principal. See Fees
txHash	string	Hash of the on-chain transaction that records this same receipt content on-chain. Use it to independently verify the receipt against the chain (tamper-evident copy). Omitted until the anchoring transaction is confirmed
issuedAt	string	When this normalized receipt was issued

Offramp block

Field	Type	Description
fromAsset / toAsset	string	Conversion pair (e.g. USDC → USD)
fromAmountMinor / toAmountMinor	string	Amounts in minor units, integer strings — see Money & Amounts
fxRate	string	Executed conversion rate
roundingRule	string	Rounding applied — floor, per the Money & Amounts contract (residuals are ledgered, never silently lost)
occurredAt	string	Execution time of the conversion

Payout block

Field	Type	Description
toAmountMinor	string	Amount delivered to the beneficiary, minor units
beneficiary	object	Masked only — nameMasked, accountLast4, accountHash. Raw beneficiary data is never returned on this surface
bankRef	string	Rail-level reference of the credit (e.g. wire reference)
occurredAt	string	Confirmation time of the delivery

The accountHash is a salted, stable hash: the same beneficiary account always yields the same hash, so consumers can group receipts by beneficiary without ever holding the raw account number. (Algorithm and salt-handling are fixed in the final spec.)

Fees

Each fees[] entry is one fee item:

Field	Type	Description
type	string	Closed set: protocol_fee — the Ezys network fee for executing the intent; payout_fee — the payout rail / provider charge; network_fee — on-chain gas for the settlement legs
amountMinor	string	Amount in minor units of this item's currency — items may be denominated in different currencies, so sum only per currency
currency	string	Currency / ticker of this item
collection	string	How the item is collected: deducted — taken in-flow from the transferred asset (transaction-fee style); billed — invoiced separately; absorbed — fronted by Ezys and reported for transparency, not charged

Two invariants:

• Fees are never baked into the principal amounts in the offramp / payout blocks — the R-11 fee-separation guarantee.
• FX spread is not a fee item. offramp.fxRate is the all-in executed rate; the spread is a component of that rate, not a separately charged fee. (A mid-rate reference for rate verification belongs to the quote surface, not the receipt.)

The protocol_fee is collected transaction-fee style — deducted from the input asset at settlement (collection: "deducted") — consistent with the network's decentralized execution model.

Reconciliation

GET /v1/reconciliation?from={date}&to={date}

Aggregate view over a date range for ledger reconciliation: one row per execution (keyed by clientReference) with amounts, fees, and terminal status, plus range totals. Pagination and a fixed daily-cutoff variant (/v1/reports/reconciliation/daily?date=) are part of the final spec, aligned with the daily evidence-export milestone.

Reconciliation rows are derived from the same store as receipts and webhooks — the three surfaces cannot disagree.

Notes

• All amounts are minor-unit integer strings with floor rounding — the full contract is Money & Amounts.
• Receipts are immutable once issued; a post-completion reversal (e.g. chargeback-style rail reversal) produces a new event on the Status API and a superseding receipt, never an in-place edit.
• Each receipt is also recorded on-chain — txHash points to that transaction. The on-chain copy carries the same normalized content (beneficiary fields masked, as above), so consumers can verify a receipt without trusting the API response alone. A superseding receipt is anchored by a new transaction; the original stays on-chain as history.
• Retention target for receipt/event backfill is 90 days (subject to agreement).