Skip to content
EncryptTechBD
Home Industries Our Work Blog Pricing About Contact Discuss Your Project
বাংলা (BN)
Payments & Reconciliation 6 min read

Payment API idempotency: cost guide for Bangladesh

Why duplicate charges happen, what idempotency work involves, and a scope-based cost model and calculator for Bangladeshi merchants.

E
EncryptTechBD · 0 comments
Hands using a calculator beside a laptop with accounting software
Photo: Wilfred Iven / StockSnap

A customer taps "Pay", the connection drops, and the app shows an error. The customer taps again. If the payment API is not designed for that sequence, the second tap becomes a second charge. The network behaved normally. The integration did not.

Idempotency is the property that makes a repeated request produce the same result instead of a new transaction. It sounds like a small technical detail until you count the refunds, support calls and reconciliation differences it prevents. This guide explains what the work involves, where the cost sits, and how to test whether a quote covers it.

What idempotency actually requires

An idempotency key is a client-generated identifier attached to a payment request. The payment service stores the key with the request and the response. If the same key arrives again, the service returns the original result rather than creating a new charge. That only works when several conditions hold.

  • One key per payment intent: generated before the first request and reused on every retry.
  • A request fingerprint: a hash of the amount, currency, customer and method, so a different request cannot reuse the key.
  • Conflict handling: the same key with different details is rejected, not silently accepted.
  • Retention: the key lives long enough to cover network retries and support investigations.
  • Scope: keys are unique per merchant and environment, not shared across stores.
  • A state machine: initiated, authorised, captured, failed, refunded and disputed are explicit states.
  • Webhook deduplication: a repeated callback does not create a second order or refund.

Where the cost comes from

The cost is not one endpoint. It is the design that surrounds the endpoint.

  • Number of gateways and wallets: each has its own request format, status model and support for idempotency keys.
  • API quality: a documented sandbox and stable error codes cost less to integrate than a panel-only service.
  • Retry paths: mobile networks, browser refreshes, queue retries and staff re-entry all create repeat requests.
  • Webhook handling: signature verification, replay windows and out-of-order events need code and tests.
  • Ledger and reconciliation: the payment record must match the order, the gateway and the bank or wallet.
  • Refunds and partial refunds: these need their own idempotent keys and approval rules.
  • Testing: failure injection takes time, but it is the only way to know the design works.
  • Monitoring: duplicate attempts and unresolved exceptions need someone watching them.

A scope-based cost model

  1. Discovery: map the payment flow, retry points, refund rules and current exception process.
  2. Gateway adapters: one unit per gateway or wallet, including authentication and status queries.
  3. Idempotency store: key generation, request fingerprint, retention and conflict response.
  4. Payment state machine: explicit states, allowed transitions and audit history.
  5. Webhook handler: signature check, replay protection and idempotent processing.
  6. Reconciliation: order, gateway and settlement matching with an exception queue.
  7. Failure testing: timeouts, duplicate taps, replayed callbacks and process crashes.
  8. Observability: logs, metrics, alerts and a runbook for the support team.
  9. Contingency and monthly support: an agreed allowance for API differences and ongoing fixes.

Ask for person-days per line, not a lump sum. A quote that omits reconciliation is a quote for the easy half.

A calculator you can fill in

Measure the duplicate rate from your own logs before you estimate the benefit. Count payment attempts that produced more than one successful charge, then divide by total successful payments.

duplicates per month = successful payments x measured duplicate rate

cost per duplicate = order value + refund or chargeback cost + support minutes x loaded hourly cost

annual exposure = duplicates per month x cost per duplicate x 12

Compare that exposure with the one-off build cost plus twelve months of run cost. If the payback is longer than the expected life of the integration, fix the highest-risk flow first instead of rebuilding everything. The point of the calculator is to rank the work, not to produce a precise number.

Test evidence that matters

  • The same key and the same body produce one charge and the original response.
  • The same key with a different amount is rejected and logged.
  • A timeout followed by a retry does not create a second charge.
  • A replayed webhook does not create a second order.
  • Out-of-order events settle on a consistent final state.
  • A crash between the gateway response and the local record is recoverable by querying status.
  • Two concurrent requests from the same customer do not both succeed.
  • A refund retry does not refund twice.

Ask for the test report, not a verbal assurance. The report should name the scenario, the expected result and what was observed.

Questions for the gateway and the integrator

  • Does the API support client-generated idempotency keys, and for how long?
  • What does it return when the same key is reused with different details?
  • Are webhooks signed, and what is the replay window?
  • Can we query the final status of a transaction by our own reference?
  • What settlement file is available, and how are fees and reversals represented?
  • Is there a sandbox that behaves like production for failures and timeouts?
  • Who supports a payment exception, and what is the escalation path?

A 90-day plan

Weeks one and two: instrument the current flow and count duplicate attempts and unresolved exceptions. Weeks three and four: design the state machine and key rules for one gateway. Weeks five to seven: build the adapter, store and webhook handler. Weeks eight and nine: run failure tests and a small pilot. Weeks ten and eleven: add the second gateway and refunds. Week twelve: reconcile, document and hand over the runbook.

Metrics

  • Duplicate charge rate and the number of duplicate attempts blocked.
  • Unresolved payment exceptions and their age.
  • Reconciliation differences between order, gateway and settlement.
  • Webhook failure rate and retry success rate.
  • Refund cycle time and support contacts per thousand payments.

Where this fits in our work

If you need payment flows that survive retries and reconcile cleanly, start with Commerce Systems. The pricing page explains how scope is built. For the daily control that catches what the API misses, read daily payment reconciliation.

Sources

Services that deliver this

Want this implemented properly?

Pricing →

Every engagement starts with a written scope. If a requirement is outside it, we quote it separately before starting.

Responses (0)

No comments yet. Add the first one below.

Leave a response

Your email address will not be published. Required fields are marked *.

Keep reading

More field notes