Skip to main content
Everything AroPay does on-chain is recorded as a transaction. This guide covers the read side: history, filters, polling patterns, and receipts.

​
List with filters

​
Poll a single transaction

Money movement is executed by a background worker after the POST returns; reads are plain database reads that observe its progress. Poll until the status is terminal:
Guidelines:
  • A modest interval (3–10 s) is plenty. Reads count against the 120-reads/min rate limit, and Ethereum blocks land every ~12 s anyway.
  • Terminal states are CONFIRMED, SETTLED, and FAILED. QUEUED, PENDING, and SETTLING always warrant another poll, and so does any status you don’t recognise; test for membership in the terminal set rather than != "PENDING".
  • Batch when you can. With several transactions in flight, one GET /transactions?status=QUEUED (and PENDING, SETTLING) per interval is cheaper than one request per row.
  • FAILED carries context in error (human-readable) and errorCode (machine-readable, see Errors); the row is kept for your audit trail. A FAILED row means nothing moved on-chain.
  • Stuck QUEUED? A row that stays QUEUED for more than about 5 minutes means the worker is delayed; it will resume automatically, but report it with the transaction ID if it persists.
Every transaction with a hash includes an explorerUrl, a direct Etherscan link on the environment’s chain (etherscan.io on production, sepolia.etherscan.io on the sandbox). For redeems, settlementTxHash identifies the payout leg (construct its URL the same way if you need it).
For PRIVATE_TRANSFER rows (and the LETTER_* legs, which are private transfers too), the explorer shows the transfer but not the amount; that’s the point. Your own transaction row keeps the plaintext amount because you’re a party to it.

​
Follow a letter’s legs

Each Aro Mail letter writes up to three rows: LETTER_ESCROW when you create it, LETTER_CLAIM when the recipient claims, and LETTER_REFUND if it is voided or expires. Their metadata carries { "letterId": "…", "leg": "escrow" | "claim" | "refund" }, so you can join history back to letters, and the letter itself links each leg by transaction id:
A leg row reaching CONFIRMED is not the whole story for a letter: the letter status moves only after AroPay verifies the encrypted amount, which the letter reports as verified: true on that leg. Poll the letter, not just the transaction, when you need to know whether the value has actually landed.

​
Download a receipt

Once a transaction has reached the chain, produce a notarized .nota receipt:
While a transaction is still QUEUED (no hash yet) the endpoint returns 409 receipt_unavailable with details.retryable: true; retry after it is submitted. A transaction that FAILED before submission returns 400 receipt_unavailable with details.retryable: false and never gets a receipt.

​
In the dashboard

The Transactions page mirrors all of this: filterable history, detail views with both legs, explorer links, and one-click receipt downloads. Handy for eyeballing what your integration just did.