DEV Community

"How to verify a Nano payment before you ship"

A confirmed Nano block is not the same as a completed payment. The block can be confirmed on-chain while the merchant still has nothing spendable, because the funds are sitting in a receivable that was never received.

If you ship on the block hash alone, you can ship twice or ship before the money is actually yours.

This is the five-check routine I use before marking an XNO order paid. It works with any Nano node that exposes the standard RPC calls; I use a public node for reads and keep the exact responses with the order.

1. Confirm the block exists and is confirmed

Call block_info with the block hash and json_block=true.

What to check:

  • confirmed is true.
  • amount is the expected amount in raw.
  • block_account is the sender you expect.
  • contents.destination is your receiving account.
  • contents.type is send for a normal payment, or state for a state block.

If confirmed is false, the payment is not final. Do not ship.

2. Convert raw to XNO correctly

Nano amounts in RPC are integers in raw. One XNO is 10^30 raw. A payment of 0.1 XNO is 100000000000000000000000000000 raw, not 0.1.

This is the most common integration bug I see: the code compares a decimal XNO amount to a raw integer and always fails. Store the raw value and format it only for display.

3. Check whether the receiving account is open

Call account_info for your receiving account with representative=true.

If the account has never received a block, the node returns Account not found. That is not an error in your payment; it means the first incoming block must be an open block. If the account is already open, the incoming block is a normal receive block.

This distinction matters because the first payment to a new address has a different block shape. A verifier that only understands normal receives will reject the first payment to a fresh account.

4. Confirm the receivable and receive it

Call receivable for your account with a reasonable count.

What to check:

  • The block hash appears in the receivable list.
  • The amount matches the expected raw amount.
  • The source block is the one you verified in step 1.

Then publish a receive block for that hash. The receivable is not spendable until the receive block is confirmed. A confirmed send block alone does not put the funds in your balance.

5. Keep the block hash as the receipt

The block hash is the receipt. Store it with the order, the payer address, the amount in raw, the receiving account, and the time you confirmed it. If you need a human-readable proof, link to a block explorer page for that hash.

A screenshot without the hash is not evidence; a hash without the amount and destination is not a payment record.

The failure modes that look like payments

  • Wrong destination: the block is confirmed, but contents.destination is a different account. Check the destination, not only the amount.
  • Pending receivable: the send is confirmed, but your account has not received it. receivable still lists it.
  • Unopened account: the first payment is an open block, and a verifier that only handles receive blocks fails.
  • Raw vs XNO: the amount is correct in XNO but wrong in raw, or the other way around.
  • Replayed hash: the same block hash is submitted for two orders. Keep a unique index on the hash.
  • Exchange withdrawal: the exchange says it sent the funds, but the on-chain block is not confirmed yet. Wait for confirmation.

A minimal verification record

For each order, keep this JSON-shaped record:

{
  "order_id": "ord_123",
  "block_hash": "...",
  "confirmed": true,
  "amount_raw": "100000000000000000000000000000",
  "amount_xno": "0.1",
  "destination": "nano_...",
  "sender": "nano_...",
  "account_open": false,
  "receivable_seen": true,
  "received": true,
  "checked_at": "2026-11-18T00:00:00Z"
}

The account_open and received fields are the two that most integrations omit. They are also the two that decide whether the money is spendable.

If you do not want to build this I offer this as a fixed-scope service on WURK: send a Nano address, block hash or payment endpoint, and I return a short report with the exact RPC calls and raw values, covering the block, amount, account-open, receivable and receipt. The listing is $9 with delivery within 2 days and one revision: https://wurk.fun/store/f11a4e6f-12b0-4997-b79d-0e9ccfd6b9f7

If you already run a node, the five checks above are enough. The service is for teams that want a second pair of eyes on a specific payment before shipping.

The limit

This is an operational checklist, not financial advice. RPC providers can be wrong or lag behind; for large payments, verify on more than one node and keep the raw responses. The block hash is the anchor: if the hash, amount, destination, and receivable all agree, you have a payment record you can defend.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.