Duplicate Merchant Payment References: Finding and Fixing Collisions

Header image: conceptual illustration.

Two orders share the same merchant-generated reference. A provider callback arrives with that reference, and the integration cannot tell which order it belongs to. This is an identifier collision, not simply a repeated API request.

Reference collisions can occur after a counter resets, a test identifier is reused in production, a prefix is removed during export, or two services generate identifiers independently. Resolving them safely requires knowing what each identifier represents and where it is unique.

Define the identifier hierarchy

Use separate identities for the customer order, each payment attempt, the provider payment resource, incoming notification events and financial postings. One order can have several attempts. One payment can generate several events. One event can be delivered repeatedly.

A merchant reference should resolve to one intended object within an explicit scope. That scope may include provider, merchant account and environment. A short numeric reference that is unique in one merchant account is not necessarily unique across a multi-provider operation.

SSLCommerz's integration documentation describes its merchant transaction identifier as unique. Check the provider's current constraints, including maximum length and accepted characters, before choosing an identifier strategy. Do not truncate a longer internal identifier without testing whether uniqueness survives.

Separate collision prevention from idempotency

An idempotency key describes repeated requests for one intended operation. An order reference identifies an order. Reusing an order reference for a different order is unsafe even if every API request has a unique idempotency key.

Conversely, assigning a new order reference on every network retry can obscure that the requests concerned the same purchase. Preserve the logical order and distinguish a genuinely new attempt from a retransmission of an uncertain request. The payment idempotency guide covers the latter mechanism.

Enforce uniqueness at the authoritative data boundary rather than relying only on a browser-generated value. Validate the normalized representation sent to the provider, not just the longer local string. Include the account and environment where resource identifiers could otherwise collide.

Investigate an existing collision conservatively

1. Identify every local record using the reference, including archived and imported records.
2. Retrieve the provider resources in the correct merchant account and environment.
3. Compare original request context, attempt identifiers, amounts, currencies and creation evidence.
4. Determine whether the issue is a true collision, duplicated import, repeated event or presentation-only abbreviation.
5. Hold uncertain mappings outside automated crediting and obtain an authorized correction.
6. Preserve the original mapping and correction history so future callbacks remain explainable.

Do not silently rename historical provider references. The provider may continue sending events with the original value, and reconciliation files may retain it. A corrective alias needs an explicit, auditable relationship to the original resource.

Worked hypothetical collision

Invented example: Two demo orders both export reference DEMO-1042 because separate services restarted their counters. One expects BDT 800 and the other BDT 1,100. A webhook includes DEMO-1042 and a provider resource identifier.

The worker does not choose an order based on amount alone. It retrieves the resource under the expected merchant account and compares the recorded initiation context. If the mapping can be established, an authorized correction links the resource to one order while preserving the conflicting records for audit.

If both demo orders expected BDT 800 and initiation evidence were missing, amount matching would not resolve the ambiguity. The case remains in exception review rather than crediting whichever record the database returns first.

Prevent recurrence during imports and migrations

Import jobs should retain source-system identities, not manufacture new references from row numbers. Test case-folding, punctuation removal and spreadsheet conversion: a reference displayed as a number may lose leading zeros. Define whether those changes are harmless presentation or meaningful identity differences.

Use the provider resource identifier as a separate reconciliation field. Compare collisions by account scope as well as reference text. A dashboard can display a shortened reference for convenience, but exports and support searches need access to the preserved original.

The reconciliation guide provides the broader exception-handling context. A collision investigation should end with both the technical mapping and its financial effect accounted for.

Reference integrity checklist

• Order, attempt, event and provider-resource identifiers have distinct definitions.
• Uniqueness includes the relevant account and environment scope.
• Provider length and character constraints do not destroy uniqueness.
• Retries preserve the original operation identity.
• Imports preserve leading zeros and source references.
• Unknown or many-to-one mappings stop automatic fulfillment.
• Historical corrections are auditable and compatible with later notifications.

Frequently asked questions

Is a duplicate reference always a duplicate charge?

No. It can be a naming collision, an import problem or repeated delivery. Verify the actual provider resources and ledger effects.

Can we match by amount and time instead?

They are useful supporting evidence, but they do not guarantee a unique match. Ambiguous candidates require review.