10 Oct 2026

The payment-reference dictionary every growing business needs

When support, finance and engineering say “the reference”, they may mean different records. Use this dictionary to agree the identifiers and their joins.

A useful payment-reference dictionary defines each identifier, who creates it, where it is unique and how it connects to other records. Keep the order, collection attempt, provider transaction and notification identities separate. Include the merchant and environment in every investigation.

Suppose support says “the reference matches”. Finance is looking at a bank entry. Engineering is looking at a payment-attempt record. The merchant is quoting an order number. Everyone may have copied a valid reference while describing a different object.

For a commerce platform supporting Nigerian bank-transfer collections, the practical question is whether those records form an explainable trail. The dictionary below gives engineering, finance and support a shared starting point.

Start with the question each record answers

An order describes what the merchant is expected to supply. A payment attempt records an intention to collect for that order. A provider transaction records a money event according to that provider's model.

A notification event describes an observation or change. A delivery is an attempt to send a notification. The provider may expose either identity, both or neither; document what actually exists.

Settlement evidence belongs to a separate reconciliation trail. Identify the destination required by the arrangement: a provider-wallet credit and a subsequent bank credit are separate observations. Do not treat a successful transaction lookup as evidence that either destination received the money.

The official reference examples in Further reading show why field names and lifecycle stages need careful mapping. They do not establish a common schema across providers.

Copy this reference dictionary

These are illustrative application fields, not Velvpay endpoint names or a required provider contract. All identifiers and example values are fictional. “Unknown” is an acceptable recorded state when evidence has not arrived.

environment

Meaning and source: Application's isolated operating context

Fictional example: mock

Required rule: Keep mock, test and live records separated.

merchant_id

Meaning and source: Application's merchant or tenant boundary

Fictional example: M-07

Required rule: Enforce authorized merchant scope in every lookup.

provider_scope

Meaning and source: Provider identity plus relevant account/integration scope

Fictional example: DEMO / ACCOUNT-A

Required rule: Establish where provider identifiers are actually unique.

order_id

Meaning and source: Merchant application's order identity

Fictional example: O-1042

Required rule: One order can have multiple collection attempts.

payment_attempt_id

Meaning and source: Application's identity for an intended collection attempt

Fictional example: A-01

Required rule: Persist the attempt; a network retry does not automatically create a new intention.

merchant_payment_reference

Meaning and source: Application reference supplied where supported

Fictional example: REF-M07-A01

Required rule: Record provider constraints and uniqueness scope; keep distinct from provider transaction ID.

provider_transaction_id

Meaning and source: Provider's transaction identity when supplied

Fictional example: TX-FICTIONAL-91

Required rule: Preserve its origin; confirm availability and relationship to the attempt.

event_id

Meaning and source: Provider's event identity, if documented

Fictional example: EVENT-FICTIONAL-8

Required rule: Record its documented scope and meaning; do not assume it identifies delivery.

delivery_id

Meaning and source: Provider's delivery identity, if documented

Fictional example: Unknown

Required rule: Leave unknown when absent. Label an application receipt ID separately.

expected_amount_minor / currency

Meaning and source: Application's expected amount and explicit units

Fictional example: 2500000 / NGN

Required rule: This design uses kobo. Verify each source's units before comparison.

observed_amount_minor / currency

Meaning and source: Normalized amount from an identified observation

Fictional example: 2500000 / NGN

Required rule: Preserve the source value and units; never overwrite the expected amount to manufacture a match.

evidence_source / observed_at

Meaning and source: Source and time of the recorded observation

Fictional example: authenticated_lookup / 2026-10-10T09:15:00+01:00

Required rule: Separate the time you observed evidence from any provider event time.

settlement_reference

Meaning and source: Settlement, wallet or bank-reconciliation identifier where available

Fictional example: Unknown

Required rule: Record each source's reference and destination separately; transaction success does not populate this field.

For your actual dictionary, add the system of record, allowed format, nullable stages and lookup owner beside every field. An absent transaction ID before confirmation may be expected; an unexplained missing merchant scope needs investigation.

Keep credentials outside this dictionary. A reference helps locate a record; possession of it must not grant permission to access that record.

Trace one fictional order

Order O-1042 belongs to merchant M-07 in the mock environment. Its expected amount is NGN 25,000, represented here as 2,500,000 kobo. No live transaction is being described.

The application records attempt A-01 and reference REF-M07-A01. Its creation request times out. At that point, the application knows what it intended to create but lacks a resolved response. It retains the attempt and follows the actual provider's documented idempotency or recovery procedure. Blindly replacing it with A-02 could obscure the first outcome.

Later, an authenticated observation identifies TX-FICTIONAL-91 and its association with REF-M07-A01. The application checks merchant scope, provider scope, environment, amount, currency and documented state before applying a payment result to O-1042.

Two notifications then refer to TX-FICTIONAL-91. Those observations do not establish two payments. Keep the receipt history and apply the duplicate-callback processing safeguards.

Now imagine a genuinely different verified transaction, TX-FICTIONAL-92, associated with the same order. Preserve it separately for review. Deduplicating solely on order ID would hide a second payment that finance needs to investigate.

Settlement remains unknown until the appropriate evidence is available. None of the invented transaction identifiers substitutes for bank-credit evidence. This is an illustrative record trail, not an executable Velvpay API example or a reported test result.

Write down the join rules

Treat external identifiers as opaque strings. Preserve case and leading zeroes unless the provider explicitly defines normalization. Do not extract dates, merchant names or business meaning from their apparent shape.

Scope every join. For provider records, identify the provider and relevant account or integration context as well as the environment. Apply merchant authorization when exposing the resulting records. Two systems can produce identical-looking strings without describing the same transaction.

State the expected relationships explicitly. In this application design, an order can have several attempts. The relationship between attempts, provider transactions and settlement records depends on the actual integration. Where a relationship is unknown, retain an unmatched exception instead of forcing a one-to-one match.

Persist application references before presenting payment instructions where the integration supports that flow. Record provider-generated identifiers when they become available. If a request is unresolved, preserve that uncertainty using the missing-callback recovery checklist.

For support, provide a restricted view with order, attempt, transaction, amount, evidence time and next owner. Finance needs the matching settlement trail when available. Neither view needs API keys or an unrestricted copy of customer data.

Run six acceptance checks

Use fabricated records in an isolated mock or test environment. Record expected result, observed result, evidence location, reviewer and date for each check. The following are proposed tests; none is reported as passed here.

Merchant isolation: Create O-1042 under two merchants. Each authorized lookup must return only the correct merchant's records.
Environment isolation: Reuse a reference string in mock and live-shaped fixtures. The mock test must not connect to production or cross-match environments.
Unresolved creation: Simulate a lost response. The original attempt remains traceable, and retry handling follows the documented contract.
Repeated notification: Supply two observations of one transaction. Preserve both receipts while applying the intended business operation once.
Second real transaction: Supply two distinct transaction identities for one order. Both remain visible, with an owned exception where appropriate.
Settlement gap: Withhold settlement evidence. Finance can trace the confirmed transaction while settlement stays explicitly unreconciled.

A useful final exercise is to ask finance and engineering to reconstruct the fictional trail independently. Compare their answers at the joins: order to attempt, attempt to transaction and transaction to settlement evidence. Any disagreement becomes a specific dictionary correction.

Use the payment API evaluation checklist to turn unresolved field or lifecycle questions into evidence requests. A shared dictionary is ready for use when another team can follow its references without guessing what “reference” means.