Concepts

Receipts and disclosure

Every settled payment is a receipt. The owner or the payee can disclose one payment to one person, who checks it against the chain.

A receipt is the record of one payment: who was paid, how much, for which request, what was returned and when. The chain already holds all of it, encrypted. The owner and the payee read it with their own keys, and either of them can disclose that one payment to someone else without showing anything more.

What a receipt binds

Two transactions make a receipt. pay creates the hold, which carries the payee, the owner, the amount, the mint, the request hash and the deadline. settle spends the hold and carries the response hash.

FieldTypeMeaning
paySignaturesignatureThe pay transaction. It identifies the payment.
payeeAddressWho was paid.
ownerAddressThe owner of the remit that paid.
amountu64 stringThe price, in base units of mint.
mintAddressThe mint it was paid in.
requestHash32 bytes, hexThe hash of the request the payment was made for.
statusheld, settled or refundedWhere the payment stands.
paidAtunix secondsWhen the hold was created.
settleSignaturesignatureThe settle transaction. Present once settled.
responseHash32 bytes, hexThe hash of the response the payee returned. Present once settled.
settledAtunix secondsWhen it settled. Present once settled.

The agent fixes the request hash when it pays. It is part of the hold's commitment, so nobody can change it afterwards. The payee fixes the response hash when it settles. Together they say: this payee was paid this amount for this request and answered with this response.

A payment that was refunded has a receipt too. It shows the hold and that it returned to the owner, with no response hash.

Disclosing one payment

A disclosed receipt is one string. It holds the pay signature and the hold's opening: the values behind the hold's commitment, which are the payee, the owner, the amount, the mint, the request hash, the deadline and the hold's blinding value.

The owner discloses from the remit's statement and the payee from the Earn screen. Each payment has a Disclose button that copies a link to Verify with the receipt in it. The receipt can be sent as the link or as the bare string.

What the person who receives it can read:

  • that payment's fields, as in the table above

What they cannot read from it:

  • the remit it came from: its balance, its caps, its payee list, its expiry
  • any other payment by the same agent or to the same payee
  • anything else in the owner's or the payee's private balance

A receipt carries no key. It cannot spend anything and it does not decrypt any other transaction.

How a receipt is verified

Verification trusts nothing in the receipt. It checks each value against the chain:

  1. It recomputes the hold's commitment from the opening in the receipt.
  2. It fetches the pay transaction by its signature and checks that this commitment is among its outputs. A receipt with a changed amount, payee or request hash produces a different commitment and does not match.
  3. It derives the hold's nullifier and looks for the transaction that spent the hold.
  4. If that transaction is a settle, the status is settled and the response hash is read from its instruction data. If it is a refund, the status is refunded. If the hold is unspent, the status is held.

Verify does this for a pasted receipt and needs no wallet. The same check is one API call:

HTTP
POST /v1/engine/receipts/verify
Content-Type: application/json

{ "receipt": "<the disclosed string>" }

It answers with the fields above, or with one of two errors:

CodeStatusMeaning
RECEIPT_NOT_FOUND404The string is not a receipt, or no pay transaction with that signature exists.
RECEIPT_MISMATCH422The transaction exists and the receipt's values do not match its output.

Checking the request and the response

A receipt proves which hashes were paid for and settled. Someone who also has the request and the response themselves can hash them and compare: The HTTP payment scheme defines both hashes.

Loading the index