What is a transaction reference?

A reference is the unique key you put on a transaction so the ledger can refuse a duplicate. If you send the same reference twice, the second request does not create a second movement. People often call this idempotency. The field name is reference.

How does a reference work?

You generate a key in your app, one per intended movement. The ledger stores it. A retry with the same key returns the original transaction. A new movement needs a new key. That is the whole contract.

Timeouts, double clicks, and webhook retries all resend work. Without a reference you post twice. With one, the ledger treats the retry as the same transfer.

Reference vs transaction id

The ledger assigns the transaction id. You assign the reference. Look up by reference when your app needs to know what happened to a submit it already made. Look up by id when you already have the ledger’s record.

What makes a good reference?

Stable, unique, and generated before you call the API. Do not derive it from the amount alone. Do not reuse it for a refund or a retry that is meant to be a new movement. A UUID or an idempotency key from your job runner is enough.

In Blnk, reference is required on every transaction. It is how the ledger implements idempotency. After a queued transfer is processed, lookups that need the next state use the parent chain. See transactions and the idempotency guide.