Receipts

Report an outcome for an operation.

Appends one link to the operation's hash chain. The server computes prev_hash and hash; a caller cannot choose them. Lifecycle transitions are enforced, so an operation cannot be reported delivered without having been accepted.

post/v1/receipts

Request

  • Base URL: https://api.fidren.net
  • URL: https://api.fidren.net/v1/receipts
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

operation_idstring required
addressstring required

The reporting address — this side's own address. A signature, if given, must be produced by it.

chain'base' | 'polygon' required
side'PAYER' | 'PAYEE' required

Which end of the operation is reporting. Each side keeps its own hash chain, and the two accounts are compared rather than merged.

counterparty_addressstring nullable

The other end, as this reporter names it.

status'REQUESTED' | 'ACCEPTED' | 'DELIVERED' | 'CONCLUDED' | 'FAILED' | 'DISPUTED' | 'REFUNDED' required
signaturestring

Optional 65-byte personal_sign signature over the statement returned by POST /v1/receipts/signing-message. Stored only if it verifies against address; an unverifiable one is reported back and the receipt is recorded without it.

amount_centsinteger nullable
currencystring
tx_hashstring nullable
occurred_atstring date-time required

Response

The stored receipt.

idinteger required
operation_idstring required
addressstring required
chainstring required
side'PAYER' | 'PAYEE' required
counterparty_addressstring nullable required
status'REQUESTED' | 'ACCEPTED' | 'DELIVERED' | 'CONCLUDED' | 'FAILED' | 'DISPUTED' | 'REFUNDED' required
amount_centsinteger nullable required
currencystring nullable required
tx_hashstring nullable required
occurred_atstring date-time required
prev_hashstring nullable required
hashstring required
signaturestring nullable required

The reporter's signature over this receipt, or null. Non-null means it was checked and matched: anyone holding this row can recompute the hash, rebuild the statement and recover the signer without trusting Fidren or the key that submitted it.

signedboolean required

Whether authorship rests on a signature from the address rather than on the API key that submitted the report.

signature_errorstring

Why the supplied signature was not accepted. Present on a POST /v1/receipts response only when a signature was sent and did not match address when checked; absent when none was sent or it matched. The receipt is still recorded — with signature: null and signed: false, attributed to the API key rather than to the address. Prose; do not parse it.

Changes

No recorded changes to this operation across all 1 revision of this API.