Guides

Payment status mapping: a practical guide

Payment status mapping translates every provider’s raw status values into one shared set of meanings, per provider and per message type. A good mapping gives each raw value one meaning, keeps final outcomes apart from progress states, sends unknown values to a person instead of guessing, and is versioned so past results stay explainable.

Why providers report the same outcome differently

Payment providers describe the same outcome in different words and in different places. One provider writes SUCCESS in transaction.status. Another writes confirmed in state. A third writes paid in a field nested two levels deep. Each choice is reasonable on its own. Together they mean that no report can count payments across providers until the words are translated. On one anonymised merchant day measured by Reconora, 318 distinct raw status values appeared under 39 different paths in the messages. They reduced to 9 meanings. That day is one observation, not an industry benchmark. It still shows the scale of the task. A merchant with many providers is not translating a handful of words. It is maintaining a dictionary. The dictionary also moves. Providers add values, rename fields and introduce new message shapes without notice. A status mapping is the place where all of this becomes one language.

What a status mapping is

A payment status mapping is a set of rules that turn each provider’s raw value into one canonical status. Each rule answers two questions. Where in this message does the status sit? What does each value found there mean? Both answers depend on the provider and on the message type. A callback, a status response and a statement line from the same provider may use different fields and different words. The key of a rule is therefore not the word alone. It is the provider, the message type, the path and the raw value, taken together. The output is one meaning from a short, fixed list. The list is short on purpose. Reports, reconciliation and alerts can then treat a payment from any provider the same way. A mapping is not a lookup table that someone fills once. It is a reviewed set of decisions, and each decision should be traceable to the person who made it.

What a good mapping does

A good payment status mapping follows a few plain rules.

  • One meaning per raw value per message type. Inside one message type of one provider, a value means exactly one thing. If it seems to mean two, the rule is missing a condition.
  • The same word can mean different things. One provider may send completed in a callback to say money moved, and completed in a redirect message to say only that the customer left the payment page. Those are two rules, not one.
  • Unknown stays unknown. A value nobody has confirmed is not guessed from its spelling. It goes to a person, and the payment waits.
  • Final and progress states are kept apart. Some meanings end a payment’s story; others only report that it is on its way.
  • Declines get a reason, separately. The status says the payment was declined. A second dictionary says why.

Final outcomes and progress states

Final outcomes and progress states answer different questions, so a mapping must label every meaning as one or the other. A final outcome says what happened to the money. A progress state says the payment is still moving: created, sent to the provider, waiting for the customer. A payment whose last known state is a progress state has no final status. That payment is open, not lost and not paid. Treating progress words as outcomes is the fastest way to misread a day. Counting them as failures inflates losses. Counting them as successes hides risk. Two practical rules follow. First, read the last status for a payment, not the first. Second, decide what happens when messages arrive out of order. A progress message that arrives after a final one should not reopen the payment silently. It should be kept as an observation and, if it contradicts the outcome, shown to a person.

Declines: status first, reason second

A decline is a status; the cause of a decline is a reason. Keeping the two in one list makes the status dictionary explode, because providers report causes with many codes and messages and messages. A cleaner design maps the status to a single meaning and maps the provider’s code and message to a decline reason in a separate dictionary. On one anonymised merchant day, 113 provider-specific decline-code pairs reduced to 22 reasons. The same rules apply as for statuses. A code whose meaning is not proven stays unknown. Calling it a customer decline would hide a provider problem. Reasons should also say who can act: the customer, the merchant or the provider. The status mapping stays small and stable, and the reason dictionary can grow at its own pace without changing how payments are counted.

How to build a mapping, step by step

A status mapping can be built from your own traffic in a few disciplined steps.

  1. Export the raw values. For each provider, list every distinct status value with its path, its message type and how often it appears.
  2. Separate message types. Group messages by shape: callbacks, status responses, redirects, statement lines. Map each type on its own.
  3. Read the documentation, then check it. Compare what the documentation says with real outcomes in the provider’s statement.
  4. Assign one meaning per value. Mark each meaning as final or progress.
  5. Leave the unproven as unknown. Route those values to a named person with examples.
  6. Map decline codes separately. Build the reason dictionary next to the status mapping, not inside it.
  7. Version the mapping. Record who approved each change and when it takes effect.
  8. Watch for drift. Each day, list values and paths that no rule recognised, and review them before the next close.

How to keep a mapping honest over time

A status mapping changes whenever a provider changes, so it needs the same care as any rule that moves money in reports. Every change should create a new version rather than edit the old one in place. Every reconciliation run should record which mapping version it used. When a value is remapped, past runs keep the meaning they were produced with. A new run can then be compared with the old one, and the difference explained line by line. Without versions, last month’s report silently changes when a rule is fixed today. Nobody can then say why a figure moved. A useful habit is a short review queue. New values, new paths and contradicting messages land there with examples. A person decides, the decision becomes a new version, and the queue empties. The aim is not zero unknowns. The aim is that every unknown is visible and has an owner.

Common mistakes

Most mapping errors come from a few shortcuts that look harmless on day one.

  • Mapping by word only. A rule that says “success means paid” for every provider and every message type will be wrong somewhere.
  • Ignoring the path. The same value under a different field can describe something else, such as a page redirect or an intermediate check.
  • Treating pending as failure. A progress word means the story is not over. Booking it as a failure creates false losses.
  • Guessing from spelling. A value such as hold_review looks harmless. Until a person confirms it, it is unknown.
  • Overwriting history. Editing a rule in place rewrites past results. Keep mappings versioned per run.
  • Mixing declines into statuses. Decline codes belong in their own dictionary.

A small synthetic example

The example below is synthetic. The providers, paths and values are invented for illustration.

Synthetic status mapping, version v3 (illustrative)

Provider A  callback         transaction.status = "SUCCESS"      -> SUCCEEDED
Provider A  callback         payment.status     = "success"      -> unknown — needs a person  (new path)
Provider B  callback         state              = "completed"    -> SUCCEEDED
Provider B  redirect         session.state      = "completed"    -> unknown — needs a person  (page closed only)
Provider C  status response  status             = "paid"         -> SUCCEEDED
Provider C  callback         status             = "hold_review"  -> unknown — needs a person

Provider A shows why the path matters: the same word under a new path is not mapped until someone checks it. Provider B shows one word with two meanings in two message types. Provider C shows the rule that matters most. A value nobody has confirmed stays unknown and never becomes “paid” by guesswork.

How Reconora handles status mapping

Reconora’s normalizer reads each provider’s messages in their native format and applies a rule per provider and message shape. Final statuses are assigned only by approved rules. An unknown value never becomes “paid”: it stays unknown until a person confirms it. When a provider changes its message, a new shape appears and is flagged instead of being read as empty. The result is one shared language for every provider, described on the canonical model page. That page shows one fragment of the model. The full model, with its dictionaries and provider rules, is Reconora’s own and is not published.

Try it on one day of your data

One day of your data, reconciled, and the report stays with you whether or not you continue.

By Reconora Research · Updated