How payments are matched (no TXIDs)

How Tillsafe knows which invoice a transfer belongs to without trusting anything the payer says, and why a transaction id never credits anything.

A payment on a public chain carries no order number. Tillsafe still knows which invoice every payment belongs to, without asking the payer for anything, because of one rule:

Money is attributed by who controlled the destination when it arrived, never by a transaction id someone hands us.

#Why a TXID never credits a payment

Asking the payer for the transaction id ("paste your TXID to confirm") looks harmless. It is the most common way crypto checkouts get robbed:

• Anyone can read every transaction on the chain. A thief pastes the TXID of somebody else's payment to the same exchange-shared address and walks off with the goods.
• Exchanges batch withdrawals: one TXID can pay hundreds of people, so it proves nothing about who paid.
• The same TXID can be submitted for two invoices.

So a TXID is never an input to crediting, anywhere in the API. There is no field to send one.

#The two ways a payment is matched

1. An exclusive deposit address. Every invoice gets a deposit address that, while the invoice is open, belongs to that invoice alone. Any transfer of an accepted token to that address is the invoice's. This is how almost every payment is matched: from an exchange withdrawal, a QR code or a copied address.

• The address is leased to the invoice for 24 hours, then rests in a 72-hour cooldown that is still attributed to it, so a slow payment still lands on the right invoice.
• Two invoices never hold the same address at the same time: the database refuses overlapping leases.
• On Bitcoin every invoice gets a fresh address from your own xpub, never reused.

Deposit addresses explains where the addresses come from.

2. A bound sender and a unique amount. When the payer pays from a browser wallet, the money goes straight to your payout address, which many payers share. Before the payer signs, the checkout binds their wallet address to the invoice and gets an exact amount with a tiny unique suffix (less than one cent). A transfer is credited only when the chain, token, destination, sender, exact amount and time window all match one binding. See connected wallet.

#What counts, and when

• The token must be one the invoice accepts, identified by its contract on that chain, never by its name. A look-alike token with the same symbol is not counted.
• Finality decides when. A transfer seen in the mempool never credits anything; a transfer in a block is detected, and it counts toward paid only at the finality its chain requires (finality per chain).
• Nothing counts twice. Every observation is keyed by (chain, transaction, log index), so the same transfer reported again, by a second node or after a restart, is the same observation.
• Payments add up. An invoice is one bill: a short payment can be topped up at the same address, or in another asset the invoice accepts (underpaid, overpaid, late).

#What is never guessed

Tillsafe does not try to be clever with money it cannot attribute:

#"Find my payment"

A payer who believes they paid can look their transaction hash up on the checkout (GET /v1/checkout/invoices/{id}/lookup). The lookup says where that transfer went on the invoice's networks and whether it is attributed to this invoice. It never credits anything: crediting only ever follows the address or the binding, from Tillsafe's own observations of the chain.