The gateway reference that joins everything

Every automated reconciliation rests on a single question: which field in the gateway's records corresponds to which field in your order records?

Get it right and the matching is mechanical. Get it wrong, or find that no such field survives reliably, and somebody is matching by amount and date for the rest of the store's life.

It is the least glamorous hour of an integration project and by some distance the most consequential.

Why it is not obvious

At checkout your store passes a reference to the gateway. What arrives at the other end varies more than anyone expects.

It may be truncated. Reference fields have length limits, and a long order name plus a prefix can be cut.

It may be the wrong identifier. Stores commonly have an order number a customer sees and an internal identifier a system uses. Which one is passed depends on configuration, and they are not interchangeable.

It may be overwritten. Some platforms or apps substitute their own reference.

It may not survive a retry. A customer whose first attempt fails and second succeeds can produce two gateway records, and whether both carry the same reference is worth knowing.

It may be optional. Where the field is not mandatory, orders created by unusual routes — a draft order, a manual payment link, an app — may carry nothing at all.

Establishing it properly

An hour, done once, on real data. Not on test transactions, which are too clean to be informative.

Take one day of orders and one day of gateway transactions. Both complete, both real.

Match them by hand. Every one. Note which field actually corresponds and in what format.

Then look for the awkward cases. A retried payment. A partial capture. A refunded order. An order created outside the normal checkout. A cancelled order that was paid.

Write down what you find, including the failures. The cases where the reference is absent or ambiguous are the specification for your exception handling, and discovering them in production instead is what makes integrations feel unreliable.

When there is no reliable reference

Sometimes the honest answer is that no field joins cleanly. It happens, particularly with older gateway integrations or where an intermediary sits in between.

The fallback is composite matching: amount plus timestamp plus payment method, within a tolerance. It works better than people expect and worse than a reference.

Where it breaks is duplicates — two orders for the same amount within the tolerance window, which is common with a popular product at a single price point. Those become exceptions requiring a person, and their volume determines whether the approach is viable.

If composite matching is your only option, measure the ambiguity rate on a month of real data before building on it. A few exceptions a week is workable. A few hundred is not.

The second join, and the third

The reference is only the first of three joins the reconciliation needs.

Order to transaction — the one above. Transaction to payout — usually the gateway's own linkage, and usually reliable, but confirm it is exposed in the data you can actually get rather than only visible in a portal. Payout to bank — amount and date, with narration as a tiebreak when several gateways pay into one account. See reconciling two gateways into one bank account.

A chain is only as strong as its weakest link, and it is worth proving all three on one day of data before automating any of it. How Shopify reconciliation actually works sets out the full sequence.

What to configure while you can

If you are setting up a gateway now rather than inheriting one:

Pass the customer-visible order number, not an internal identifier, and check what arrives.

Keep it short and unprefixed so nothing is truncated.

Make it mandatory if the option exists.

Test the awkward paths — a manual payment link, a draft order, a retry — before going live rather than after.

Ten minutes of configuration at setup removes a permanent category of manual work. It is very hard to retrofit onto transactions already processed.

Common questions

What is the most important field in a payment reconciliation?

The reference passed from the store to the gateway at checkout, because it is what joins an order to the transaction that paid for it. If it is reliable, matching is mechanical and can be automated; if it is missing, truncated or inconsistent, reconciliation falls back to matching on amount and date, which produces ambiguity that needs human resolution.

How do you verify the order reference actually works?

By matching one full day of real orders against one full day of real gateway transactions by hand, then deliberately examining the awkward cases — a retried payment, a partial capture, a refund, an order created outside the normal checkout. Test transactions are too clean to reveal the problems that matter.

What if no reliable reference exists?

Fall back to composite matching on amount, timestamp and payment method within a tolerance. It works reasonably well but breaks on duplicates, which are common when a popular product sells at a single price point. Measure the ambiguity rate against a month of real data before building on it, since a few exceptions a week is workable and a few hundred is not.

What should be configured at gateway setup to avoid this problem?

Pass the customer-visible order number rather than an internal system identifier, keep it short and unprefixed so nothing is truncated by field length limits, make it mandatory where that option exists, and test the unusual payment paths before going live. This is very difficult to retrofit onto transactions already processed.

Related: how Shopify reconciliation actually works · when your gateway settlement does not match your orders · what the Shopify Admin API actually returns