Docs/Reference/Receipts and polling

Receipts and polling

How brands confirm signed operations while issuer webhooks are still coming soon.

Receipt model#

A receipt is the completed evidence your brand can reconcile.

Issuer webhooks are coming soon. Until then, brands should treat the Loyfin API as a coordination and receipt surface: submit signed actions, store the returned operation ID, poll status, and read completed issuance/redemption receipts after mining.

Polling#

  • After POST /issuances or POST /redemptions, save the returned operation id, nonce, and operationHash.
  • Poll GET /operations/:id until status is mined, rejected, or your own timeout is reached.
  • For completed rows, fetch GET /issuances?operationHash=... or GET /redemptions?operationHash=... and store the txHash, blockNumber, and logIndex.
  • Use cursor pagination for backfills. Do not assume one poll will catch every status transition during an outage.

Failure handling#

  • pending means Created in product surfaces. It is not final.
  • submitted means a relayer has sent a transaction, but the brand should still wait for a mined receipt.
  • rejected means the brand should release, retry, or manually review the internal operation based on the reason.
  • Use direct chain reads as a fallback if the API is unavailable and the brand needs independent confirmation.