DEV Community: Daniel Parkson Tano

Designing Fee Engines for Different Payment Rails

Daniel Parkson Tano — Fri, 16 Oct 2026 13:44:39 +0000

Making fees transparent when providers calculate and collect them differently.

Fees seem simple until a product supports several payment rails.

One provider may deduct a fixed fee from the recipient amount. Another may charge the platform separately. A bank transfer may use a percentage with a minimum, while a wire transfer uses a flat charge. Some fees may be waived above a transaction threshold or after sufficient monthly activity.

A single fee field cannot explain all of these outcomes.

Separate the amounts in the quote

A payment quote should distinguish:

send amount
customer fee
total sender debit
provider request amount
provider fee
recipient amount
fee currency

These values may be expressed in different currencies. A fee charged in the receiving currency should not be subtracted blindly from the sending wallet.

Model who absorbs the provider fee

Suppose the recipient should receive exactly 1,000 units and the provider deducts 50.

If the platform sends 1,000, the recipient receives 950. If the product promises an exact recipient amount and the platform covers the provider fee, the provider request may need to be 1,050 while the customer quote still shows a recipient amount of 1,000.

That policy should be explicit:

provider_amount = recipient_amount
if fee_policy == "platform_covers_recipient_fee":
    provider_amount += quoted_provider_fee

Do not hide this adjustment in an adapter without recording the quoted and submitted values.

Configure fee rules as data

Fee rules change more frequently than transaction code. Store configurable values such as:

percentage;
flat amount;
minimum fee;
maximum cap;
transaction waiver threshold;
monthly activity threshold; and
rail-specific overrides.

Only one applicable active configuration should exist for a given scope. Changes should be auditable.

Record fee outcomes in the ledger

When a fee is charged, create a financial record. When it is waived, preserve the waiver reason and threshold used.

For monthly maintenance, use a deterministic account-and-period reference so concurrent workers cannot charge the same month twice.

Return concise fee information to clients

The API should provide the values the interface needs without forcing it to recreate fee logic. If a fee or cap is zero, the client can omit it. If a fee is waived, the API can return the effective fee as zero along with short eligibility information.

The backend remains authoritative for calculation; the frontend remains responsible for clear presentation.

The design principle

A fee engine translates commercial policy and provider behavior into explicit financial amounts.

The quote, sender debit, provider submission, recipient credit, and recorded fee must reconcile. If those values are not separately represented, the customer experience and financial reporting will eventually disagree.

LinkedIn post 12A

“Fee” is not one number in a cross-currency payment.

You may need to distinguish:

• customer fee

• total sender debit

• provider fee

• provider request amount

• recipient amount

• fee currency

When the provider deducts a fee from delivery, sending the quoted recipient amount may underpay the recipient.

PaymentFees #Fintech #ProductEngineering #Accounting

Multi-Currency Wallets Without Losing Auditability

Daniel Parkson Tano — Fri, 16 Oct 2026 13:43:26 +0000

Designing conversions as linked financial events instead of balance edits.

Adding a currency to a wallet product is not simply adding another currency code to a transaction table.

Each user can own multiple balances, every currency has different decimal rules, and conversions affect two wallets at once. Historical transactions must retain the rate used at execution, even after market or configured rates change.

Give every user-currency pair one wallet

A database constraint should ensure that a user has no more than one active wallet for a supported currency.

UniqueConstraint(fields=["user", "currency"])

The currency itself should come from controlled configuration containing its code, precision, funding capability, withdrawal capability, display symbol, and activation state.

Treat conversion as a financial transaction

A conversion should create an immutable record containing:

one reference;
source currency and amount;
destination currency and amount;
applied exchange rate;
rate source;
relevant country or market context; and
execution time.

Inside one database transaction, lock the source and destination wallets in a consistent order, debit the source, credit the destination, and write both ledger effects.

Consistent lock ordering reduces deadlock risk when concurrent conversions involve the same currency pair in opposite directions.

Snapshot the applied rate

Never reconstruct a completed conversion using the current exchange rate. The historical record must preserve the rate that produced the destination amount.

If staff can configure an override rate, preserve an audit history showing the previous value, new value, actor, timestamp, and reason. Existing conversions remain unchanged.

Use decimal arithmetic deliberately

Floating-point arithmetic is inappropriate for wallet balances. Use decimal values and define rounding at the business boundary:

wallet storage precision;
quote display precision;
provider submission precision; and
ledger settlement precision.

Round once at the required boundary, then persist the value used. Repeated rounding at multiple layers creates unexplained differences.

Keep the legacy interface separate

When migrating from one balance field to multi-currency wallets, older clients may still expect a primary account balance. A compatibility property can expose the designated primary wallet without making the legacy column authoritative again.

Migration code should be explicit, reversible where practical, and followed by constraints that prevent the old and new systems from drifting.

The design principle

A multi-currency wallet is a collection of currency-specific ledgers connected by immutable conversion records.

The rate, rounding decision, and two wallet effects are part of one financial event. Preserving them together keeps historical balances explainable as currencies and pricing rules evolve.

Securing a Mobile Financial API in Layers

Daniel Parkson Tano — Fri, 16 Oct 2026 13:43:14 +0000

Why authentication is only one part of protecting mobile payment traffic.

A valid access token proves that a credential was accepted. It does not prove that the request is fresh, came from the expected application, originated from a trusted device, or has not been automated at an abusive rate.

Mobile financial APIs need defense in depth. Each layer answers a different security question, and no single signal should carry more confidence than it deserves.

Validate the request context

Before business logic runs, the gateway can examine:

client application type;
application version and build;
device identifier format;
content type for mutations;
timestamp and nonce;
request signature;
IP and device reputation; and
request rate.

These checks should produce clear internal reasons while returning restrained customer-facing errors.

Sign the request, not only the session

An HMAC signature can bind the HTTP method, path, timestamp, nonce, and request body to a shared application secret or derived signing key.

signature = HMAC(method + path + timestamp + nonce + body_hash)

The server independently reconstructs the signed content and uses constant-time comparison. A valid signature helps detect body modification and requests created outside the expected client.

Exact signing rules and enforcement thresholds should remain private.

Prevent replay

A correctly signed request can still be dangerous if captured and submitted again.

Replay protection requires:

a limited timestamp window;
a nonce unique within that window; and
an atomic cache write that rejects an existing nonce.

Financial endpoints must still be idempotent because replay protection and transaction idempotency defend different boundaries.

Rate-limit atomically

A rate limiter that performs get, then increments, then set can lose updates across concurrent workers. An atomic cache increment produces a reliable count for each IP and device window.

Limits can adapt to device reputation, but exact thresholds and risk weights should not be published.

Combine signals carefully

Device properties, unusual request patterns, outdated clients, and reputation can contribute to a composite risk decision. Treat weak signals as risk contributions rather than absolute proof of compromise.

The enforcement model may allow, warn, block, or temporarily blacklist. False positives need an operational recovery path.

Keep the hot path efficient

Security middleware runs on every request. Batch cache reads, short-lived in-process caching for clean devices, bounded background persistence, and guarded debug logging can reduce avoidable overhead.

Performance optimizations must never cache a blocked decision incorrectly. Any blacklist or high-risk event should invalidate the local clean-device cache immediately.

The design principle

Authentication identifies a session. Layered request security evaluates whether each request is structurally valid, fresh, appropriately signed, correctly routed, and behaviorally acceptable.

The strongest design combines independent controls while keeping business endpoints idempotent and the security hot path observable.

Tracking Payment Liquidity with FIFO Funding Lots

Daniel Parkson Tano — Fri, 16 Oct 2026 13:42:44 +0000

Moving beyond aggregate balances to understand the real cost of every payout.

A payout account may show enough money to complete a transfer, but that balance alone cannot explain what the transfer costs.

Liquidity is often acquired in separate batches. Each batch may have a different exchange rate, funding date, provider cost, or settlement source. When a payout consumes that liquidity, finance teams need to know which funds were used and what margin remained.

An aggregate balance answers “how much is available?” A funding-lot ledger answers “where did it come from, what did it cost, and which transactions consumed it?”

Represent liquidity as inventory

A funding lot can contain:

reference
funding date
original amount
remaining amount
acquisition rate
status
source metadata

The remaining amount changes as payouts consume the lot, while the original amount and acquisition rate remain part of the audit history.

Allocate oldest liquidity first

FIFO allocation is easy to describe and subtle to implement. One payout may consume the remainder of one lot and continue into the next.

with database_transaction():
    lots = lock_open_lots().order_by("funded_at", "created_at")
    remaining = payout_amount

    for lot in lots:
        if remaining <= 0:
            break

        used = min(remaining, lot.remaining_amount)
        create_allocation(lot=lot, reference=reference, amount=used)
        lot.remaining_amount -= used
        lot.save()
        remaining -= used

Row locks prevent two payouts from consuming the same remaining liquidity concurrently.

Make allocation retry-safe

Before allocating, calculate how much has already been assigned to the transaction reference. A retried task should allocate only the difference.

The database should also prevent the same transaction-lot relationship from being inserted twice accidentally.

Distribute financial values across lots

If one payout spans multiple lots, its revenue and provider fee must be distributed proportionally. Assigning the full revenue or fee to each allocation overstates the transaction.

For each allocation, calculate:

share of the total payout;
attributed customer revenue;
provider-fee share;
cost at the lot’s acquisition rate;
payout cost excluding provider fee; and
resulting FX margin.

The final allocation should absorb rounding differences so the parts equal the original transaction totals exactly.

Reconcile derived values

Financial rules evolve. A reconciliation service should be able to rebuild remaining lot balances and derived allocation values from authoritative transactions without deleting valid live history.

Manual overrides must be explicit and traceable. A corrected revenue value should be marked as an override rather than becoming indistinguishable from a calculated value.

The design principle

Liquidity is financial inventory. Funding lots and immutable allocations make its movement explainable.

This structure supports treasury visibility, transaction-level cost attribution, controlled reconciliation, and reliable margin analysis without relying on today’s aggregate balance to reconstruct yesterday’s economics.

Combining Automated Payment Rails with Human Fallback

Daniel Parkson Tano — Sat, 10 Oct 2026 07:23:47 +0000

Designing one transaction lifecycle that can move safely between API-based payouts and operational fulfillment.

Payment coverage is rarely uniform. One destination may support an immediate API payout. Another may require a human agent. An automated rail may also reject a transaction after the customer has already committed funds.

Treating automated and manual fulfillment as unrelated products creates duplicated logic and fragmented transaction history. A better design represents them as different fulfillment strategies inside one customer-facing lifecycle.

Start with one authoritative transaction

The customer should create one transfer with one reference, quote, recipient, funding record, and status history.

The routing layer then selects a fulfillment strategy:

def route_transfer(order):
    if automated_rail_supports(order.destination, order.method):
        return submit_automated_payout(order)

    return queue_for_agent(order)

The route used should be persisted on the transaction. A later configuration change must not obscure how an existing transfer was fulfilled.

Define when fallback is safe

Fallback should not occur after every provider error.

The system must distinguish:

not submitted: no external payment was created, so fallback may be safe;
definitively rejected: the provider confirms no payout will occur;
unknown outcome: a timeout occurred and the provider may still process the request;
processing: an external payment exists and must be reconciled;
completed: terminal success; fallback is forbidden.

Falling back during an unknown outcome can pay the recipient twice. Reconciliation must resolve ambiguity before a second rail is allowed.

Preserve the financial contract

Changing fulfillment strategy must not silently change what the customer authorized.

The transaction should retain:

sender debit;
recipient amount;
quoted exchange rate;
customer fee;
payout method;
recipient destination; and
funding status.

An agent may use a different internal settlement rate, but that operational rate should not rewrite the customer’s original quote.

Assign manual work transactionally

When a transfer enters an agent queue, competing workers or agents must not claim it simultaneously.

The assignment path should lock the order, verify that it is still eligible, select an available agent, write the assignment, and create the queue record atomically.

Agent selection can consider capability, destination, payout method, availability, and current workload. Exact scoring rules should remain internal because they are operational and potentially security-sensitive.

Coordinate linked transactions

Sometimes a manual fulfillment record is linked to another product record, such as a virtual-account withdrawal. One record represents the customer request; the other represents the payout workflow.

The architecture must define:

which record owns the funds reservation;
which action confirms that payment was sent;
which action completes the customer request;
how cancellation propagates; and
how duplicate completion is prevented.

A linked transaction should be completed through an idempotent service, not through independent status assignments on both records.

Keep staff intervention auditable

Staff may need to confirm a payment when an agent application is unavailable or a provider integration fails. This action should require explicit permission and record:

the staff actor;
completion timestamp;
reason or note;
optional evidence;
affected transaction references; and
whether linked records were updated.

The operation should lock the transaction and return safely if it was already completed.

Notify from the authoritative transition

Customer and agent notifications should be triggered by the service that owns the state transition. If each interface sends its own message, retries can create duplicate or contradictory notifications.

Notifications are secondary effects. A notification failure should not roll back an already valid financial completion, but it should be observable and retryable.

The design principle

Automation and human operations can share one reliable transaction model.

The routing decision selects how the obligation will be fulfilled. It does not create a second customer promise. Safe fallback requires certainty about the first rail, preserved financial terms, transactional assignment, linked-state coordination, and an auditable operational path.

Separating Available, Held, Actual, and Displayed Balances

Daniel Parkson Tano — Sat, 10 Oct 2026 07:23:33 +0000

Why one balance field cannot represent every financial truth in a virtual-account product.

“What is the balance?” sounds like a simple question until the system includes pending deposits, withdrawals awaiting completion, provider-reported funds, fees, manual reconciliation, and temporary account restrictions.

These values describe different truths. Compressing them into one number makes failures difficult to recover and discrepancies difficult to explain.

Define each balance explicitly

A virtual-account system may need at least four concepts:

ledger balance: the result of locally applied credits and debits;
held amount: funds reserved for operations that have not completed;
available balance: the amount that can be spent now;
actual balance: the latest balance reported by the external account provider.

Some products may also maintain a displayed balance when customer presentation must be separated from internal debt or reconciliation handling.

The relationship can be expressed as:

available balance = ledger balance - active holds

The provider-reported actual balance should not overwrite the local ledger automatically. A difference may indicate pending events, fees, reversals, or a reconciliation issue that needs investigation.

Use holds for asynchronous withdrawals

When a customer requests a withdrawal, the platform may need to reserve funds before the external payment reaches a terminal state.

Immediately applying a final debit creates ambiguity if the provider later rejects the request. Leaving the full balance spendable creates an overspending risk.

A hold provides the intermediate state:

with database_transaction():
    account = lock_account(account_id)

    if account.available_balance < total_required:
        raise InsufficientFunds()

    account.hold_amount += total_required
    record_hold(reference, total_required)

On success, consume the hold and create the final debit. On failure or cancellation, release it. Each action should use a stable transaction key so retries remain safe.

Preserve before-and-after values

Every balance mutation should record its effect:

reference
direction
amount
balance before
balance after
transaction type
metadata
timestamp

The ledger then explains both the current customer balance and the path used to reach it.

Treat provider balances as reconciliation evidence

External balance updates are valuable but may arrive on a different timeline from individual transaction events.

The platform can store:

latest provider-reported balance;
time of the last successful sync;
local ledger balance; and
calculated difference.

Staff can then investigate discrepancies without silently changing customer funds.

If an authorized adjustment is required, it should be represented by a reconciliation entry with a reason, actor, reference, and before-and-after values.

Keep fees in the ledger

Transaction fees and monthly maintenance charges are financial events. They should not be hidden arithmetic applied only when the balance is serialized.

A fee engine can determine whether a fee applies based on transaction rail, amount, account configuration, or prior-period activity. The resulting charge or exemption should be recorded so staff and customers can understand what occurred.

For recurring fees, use a deterministic reference per account and billing period. This prevents two workers from charging the same month twice.

Model temporary restrictions separately

Sometimes an account should accept deposits but temporarily block outgoing transfers. That is an account capability decision, not a negative balance and not necessarily a debt.

Explicit flags or account states such as deposit-only, outgoing hold, or suspended provide clearer behavior than manipulating the balance to force withdrawals to fail.

The design principle

Balances are views of a ledger under specific rules.

Available, held, actual, and displayed amounts answer different questions. Modeling them explicitly improves withdrawal safety, reconciliation, fee transparency, and operational control without losing the audit trail behind customer funds.

Building a Provider-Agnostic Payout Architecture

Daniel Parkson Tano — Sat, 10 Oct 2026 07:23:18 +0000

Keeping the customer experience stable while payment rails, bank directories, fees, and status semantics change underneath it.

The first integration with a payment provider often becomes tightly coupled to the product. Provider-specific field names enter database models, bank codes are assumed to be universal, and technical errors flow directly to customers.

The second provider exposes every one of those assumptions.

A provider-agnostic architecture does not pretend all providers are identical. It gives the application a stable domain contract while allowing each adapter to preserve the differences that matter.

Separate product intent from provider commands

The product wants to perform operations such as:

list supported banks;
resolve an account;
initiate a bank payout;
retrieve a transaction status; and
create deposit instructions.

The provider adapter translates those operations into the external API’s authentication, paths, payloads, signatures, and response structure.

class PayoutProvider:
    def list_banks(self): ...
    def resolve_account(self, bank_code, account_number): ...
    def send(self, destination, amount, narration): ...
    def get_status(self, provider_reference): ...

Application services depend on this contract instead of importing a provider client directly.

Keep collection and disbursement configurable independently

The best provider for accepting deposits may not be the best provider for payouts. Operational issues may affect one direction without affecting the other.

Separate configuration for collection and disbursement gives operations a controlled switch without forcing a release or changing the customer flow.

The chosen provider should be written onto every transaction. Current configuration selects new work; it should not rewrite history.

Treat bank directories as provider-owned

Bank names and codes are not always universal across providers. Two providers may represent the same institution differently.

The bank selected during account creation should therefore retain its provider context:

recipient account
  account number
  account name
  provider
  provider bank code
  provider bank name

When the active payout provider changes, accounts created with another provider should not be silently submitted using incompatible identifiers. The product can filter saved recipients by provider or ask the customer to validate a new provider-specific destination.

This is safer than guessing that similar names or codes refer to the same institution.

Cache directories with provider-specific keys

Bank lists are read frequently and change less often than transaction state, so caching is useful. The cache key must include the provider:

cache_key = f"bank-directory:{provider}:v2"

Otherwise, switching providers can continue serving the previous provider’s list until the shared cache expires. A controlled force-refresh action is also useful for operations.

Normalize statuses, preserve raw responses

Providers use different status vocabularies. The adapter should expose a small internal state while preserving the raw response for staff diagnostics.

The same applies to errors. Customer-facing responses should use stable product language. Internal logs and transaction metadata can retain the exact provider error under access control.

This prevents technical messages, provider account restrictions, and internal liquidity information from leaking to customers.

Model provider-specific fee behavior explicitly

One rail may deduct its fee from the amount delivered. Another may debit the fee separately. A common fee field does not guarantee common economic behavior.

The transaction should distinguish:

amount the customer sends;
platform fee charged to the customer;
amount requested from the provider;
provider fee;
expected recipient amount; and
actual recipient amount when known.

Provider adapters can then construct the correct payout amount without changing how the application quotes the transfer.

The design principle

Provider independence comes from isolating differences, not erasing them.

The domain layer defines the stable customer and transaction contract. Adapters own provider authentication and semantics. Transactions preserve the rail actually used. Provider-owned reference data stays scoped to that rail.

With those boundaries, switching providers becomes an operational decision rather than a rewrite of the payment product.

Reconciling Payments When Webhooks Never Arrive

Daniel Parkson Tano — Sat, 10 Oct 2026 07:22:24 +0000

Designing a recovery path for asynchronous transactions that remain stuck in processing.

Webhooks provide a fast way to learn that an external payment changed state. They do not guarantee that every event will reach the application.

A callback can be delayed by a network failure, rejected because of a signature or configuration problem, or lost during an outage. The provider may complete the payment while the local transaction remains in processing.

Without a second source of confirmation, the transaction can remain stuck indefinitely even though the money has already moved.

Reliable payment systems therefore need active reconciliation in addition to passive webhook handling.

Record enough information to ask again

Reconciliation starts when the transaction is created. The local record should preserve:

the internal business reference;
the provider used for this particular attempt;
the provider transaction identifier;
the current normalized state;
the request and response timestamps; and
a sanitized provider-response summary.

The recorded provider matters. Querying whichever provider is currently configured can produce an incorrect result after the platform switches rails. A processing transaction must always be reconciled against the provider that originally accepted it.

Reconcile outside the customer request

Opening a transaction history screen should not block while the server calls several external providers. Instead, the API can return the current local state and enqueue a background refresh for eligible processing transactions.

def request_status_refresh(payment):
    lock_key = f"status-refresh:{payment.id}"

    if not cache.add(lock_key, "queued", timeout=30):
        return False

    reconcile_payment.delay(payment.id)
    return True

The short-lived cache lock prevents repeated screen refreshes from creating a burst of identical provider calls. The worker removes the lock after processing so a later request can check again if the payment remains unresolved.

Use one normalization path

Webhook processing and active reconciliation should not maintain separate definitions of success.

Both paths should translate the external result into the same internal vocabulary and call the same guarded transition service:

def apply_provider_result(payment, external_result):
    normalized = normalize_status(external_result)

    if normalized == "completed":
        complete_once(payment, external_result)
    elif normalized == "failed":
        fail_once(payment, external_result)
    else:
        keep_processing(payment, external_result)

This avoids a dangerous situation where a webhook considers one status successful while the polling worker considers it pending.

Bound retries without inventing failure

A provider can continue returning pending for a legitimate transaction. After several checks, the worker may stop retrying automatically, but it should not convert uncertainty into failure without evidence.

Useful outcomes include:

terminal success: complete the local transaction once;
terminal failure: apply the defined failure or refund path once;
still processing: retry with delay up to a defined limit;
unavailable provider: record the operational error and retry later;
unknown status: preserve processing and flag the transaction for review.

Retry exhaustion means automated reconciliation paused. It does not prove that the payment failed.

Make reconciliation safe to repeat

The provider may send the missing webhook while the status worker is running. Both paths can discover the same terminal result at nearly the same time.

The final transition must therefore lock the transaction and protect its financial side effect with an idempotency key. Reconciliation should be safe to run repeatedly, including from a staff action.

Give operations controlled visibility

Some transactions will require manual investigation. Staff need access to:

local and provider references;
the provider recorded on the transaction;
the latest normalized and external statuses;
timestamps for prior checks;
the last safe provider error; and
an action to request another status refresh.

Provider errors should remain internal. Customers need a stable, understandable transaction state rather than raw infrastructure messages.

The design principle

Webhooks are the low-latency path. Reconciliation is the completeness path.

Using both creates a convergent lifecycle: whether the platform learns the result through a callback, a background poll, or an authorized staff check, the same protected transition brings the transaction to the same local state.

This does not make external systems reliable. It makes their unreliability manageable.

Idempotency Beyond the HTTP Header

Daniel Parkson Tano — Sun, 04 Oct 2026 09:16:17 +0000

Designing retry-safe financial operations across clients, workers, databases, and external providers.

Payment clients retry requests. Load balancers retry requests. Background workers retry tasks. Users press a button again when the screen appears stuck. Providers may time out after accepting an operation, leaving the caller unsure whether it succeeded.

Retries are normal. Duplicate financial effects are not.

An idempotency header is useful, but it is only the beginning of an idempotency design.

Define the operation being protected

An idempotency key needs a scope. The same string may be valid for one operation and invalid for another.

A practical internal record can include:

class IdempotencyRecord:
    operation: str
    owner_key: str
    idempotency_key: UUID
    request_hash: str
    completed: bool
    resource_id: str | None

The pair (operation, owner_key) identifies the business attempt being protected. Examples might include creating one external account for a user and currency, submitting one payout request, or provisioning one wallet on a network.

The external idempotency key is then stable for retries of that same attempt.

Bind the key to the request body

Reusing an idempotency key with a different payload is not a harmless retry.

Imagine the first request attempts to send 100 units and the second attempts to send 1,000 using the same key. Returning the result of the first request would surprise the caller. Sending the second request with the same external key may be rejected by the provider. Executing both defeats idempotency entirely.

Canonicalize and hash the request:

def request_hash(payload):
    canonical = json.dumps(
        payload,
        sort_keys=True,
        separators=(",", ":"),
        default=str,
    )
    return sha256(canonical.encode()).hexdigest()

When a retry arrives:

same operation, owner, and hash: reuse the existing attempt;
same operation and owner but different hash while pending: reject the conflict;
completed attempt: return the stored result or begin a clearly defined new operation.

Lock creation of the idempotency record

Two workers can attempt to create the same record simultaneously. The application therefore needs both a database uniqueness constraint and transactional locking.

with database_transaction():
    record, created = (
        IdempotencyRecord.objects
        .select_for_update()
        .get_or_create(
            operation=operation,
            owner_key=owner_key,
            defaults={"request_hash": request_hash(payload)},
        )
    )

The database constraint is the final arbiter. Code-level checks improve behavior and error messages, but they do not replace uniqueness.

Persist the resulting external resource

An idempotency record is more useful when it stores the resource created by the operation.

Suppose the external request succeeds but the API response is lost. On retry, the application should be able to determine whether an external resource was already linked locally rather than blindly creating another one.

The completed record can retain:

the local resource identifier;
the external resource identifier;
a sanitized response summary; and
completion time.

This allows safe replay and operational investigation.

Protect the ledger independently

Provider request idempotency does not automatically make the local financial effect idempotent.

The external transfer may be created once while its success webhook is delivered multiple times. Therefore, use separate idempotency boundaries:

Command idempotency prevents duplicate provider operations.
Event idempotency prevents processing the same provider event repeatedly.
Ledger idempotency prevents applying the same credit or debit twice.
Notification idempotency prevents duplicate customer messages.

These keys may derive from the same business reference, but they protect different effects.

Decide what completion means

An operation is not always complete when the provider accepts it.

For asynchronous payments, useful stages include:

request safely submitted;
external resource created;
financial operation processing;
terminal result received; and
local ledger effect applied.

The idempotency record should reflect the boundary it protects. Marking everything completed immediately after an HTTP response can make later recovery difficult.

Do not use random keys without durable storage

Generating a new UUID for every retry provides uniqueness, not idempotency. The caller must reuse the same key for the same logical operation, or the server must derive and persist a stable association.

The key’s lifecycle matters more than its randomness.

The design principle

Idempotency is a business guarantee that repeated execution produces one intended effect. The HTTP header is simply one mechanism for carrying that intent across a network boundary.

A reliable implementation defines the operation’s scope, binds it to a canonical request, serializes competing attempts, stores the result, and independently protects downstream financial effects.

The resulting behavior is deterministic even when the network is not. A timeout can be retried without creating a new business operation, a conflicting payload is rejected, and downstream effects remain independently protected. This is a stronger guarantee than assuming retries will be rare.

Designing Explicit State Machines for Money Movement

Daniel Parkson Tano — Sun, 04 Oct 2026 09:14:57 +0000

Turning scattered status updates into enforceable payment lifecycle rules.

Payment systems often begin with a status column and a few convenient values: pending, successful, and failed.

As the product grows, more states appear. A customer has authorized the payment, but the provider has not completed it. An agent has accepted an order but has not paid the recipient. Funds are reserved while an external transfer is processing. A transaction expires, but the customer can still dispute it.

If every endpoint updates the status independently, the status field stops representing a lifecycle. It becomes a collection of guesses.

An explicit state machine makes the permitted paths visible and enforceable.

Status should describe business progress

A useful payment state describes what the platform knows and which actions remain valid.

A simplified lifecycle might be:

pending -> processing -> completed
   |           |
   |           +------> failed
   +------------------> cancelled
   +------------------> expired

processing or expired -> disputed

The exact states depend on the product. What matters is that transitions are intentional.

For example:

pending: the transaction exists but no party has committed to fulfillment;
processing: an external provider or human operator is actively fulfilling it;
completed: the financial obligation has been satisfied;
failed: fulfillment ended unsuccessfully;
cancelled: the transaction was intentionally stopped while cancellation was still valid;
expired: the allowed action window ended;
disputed: normal completion rules are suspended for investigation.

Put transition rules in the domain layer

Endpoints should request transitions rather than assign statuses directly.

class Transfer:
    def mark_paid(self):
        if self.status not in {"pending", "processing"}:
            raise InvalidTransition()
        self.paid_at = now()
        self.status = "processing"

    def complete(self):
        if self.status != "processing":
            raise InvalidTransition()
        self.completed_at = now()
        self.status = "completed"

    def dispute(self, reason):
        if self.status in {"completed", "cancelled", "disputed"}:
            raise InvalidTransition()
        self.status = "disputed"
        self.dispute_reason = reason

This keeps API endpoints, webhooks, background workers, and staff tools from inventing different transition rules.

Terminal states need strong protection

Completed, cancelled, and failed transactions are usually terminal. A delayed event should not reopen them.

Terminal protection should be checked while the transaction is locked:

with database_transaction():
    transfer = lock_transfer(reference)

    if transfer.status in TERMINAL_STATES:
        return transfer

    transfer.apply_provider_result(result)
    transfer.save()

Without the lock, two actors may both observe a non-terminal state and trigger conflicting side effects.

Side effects belong to transitions

A status change is rarely the only effect. Completing a withdrawal may also:

convert a hold into a debit;
write a ledger entry;
complete a linked transaction;
record a receipt;
notify the customer; and
close an operator task.

These effects should be coordinated by one transition service. If each caller independently updates related records, the system can end up with a completed transaction, an unreleased hold, and a still-open operational task.

Where possible, financial and state changes should be atomic. Notifications and other external work can be queued after the database commit.

Expiration is a state transition, not a UI timer

A countdown displayed in an application is not authoritative. The backend must determine whether the deadline has passed and whether expiration is still legal.

Only eligible states should expire. A transaction already processing with an external rail should not be expired merely because its original initiation deadline passed. Doing so creates a race between an expiration task and a late success event.

Background expiration workers should lock each candidate and re-check its state before applying the transition.

Linked transactions require one completion authority

Financial products sometimes represent one customer action through two linked records. For example, a withdrawal request may be fulfilled through a marketplace transfer.

The dangerous design lets either record complete independently. That can duplicate notifications, ledger mutations, or payouts.

Instead, define:

which transaction owns the customer-facing lifecycle;
which one represents fulfillment;
which transition completes the linked record;
how retries detect that completion already occurred; and
how cancellation and disputes propagate.

Preserve timestamps for meaningful transitions

updated_at is not enough. Store timestamps that answer operational questions:

when was the order accepted?
when did the customer mark it paid?
when did processing start?
when was it completed?
when did it expire?

These timestamps support support investigations, service-level monitoring, dispute handling, and future analytics.

The design principle

A transaction status is a compressed representation of business truth. It should change only through named transitions that enforce prerequisites and coordinate their financial effects.

When the state machine is explicit, asynchronous providers, human operators, background jobs, and staff tools can all participate without silently contradicting one another.

This structure also makes failures easier to reason about. Instead of asking which endpoint last edited a status string, engineers can inspect a defined transition, its prerequisites, and the side effects that should have occurred with it. That clarity is valuable during development, operations, and reconciliation.

Webhooks Are Notifications, Not Your Source of Truth

Daniel Parkson Tano — Sun, 04 Oct 2026 09:08:47 +0000

Building payment workflows that remain correct when events are duplicated, delayed, missing, or delivered out of order.

Payment integrations often look simple in a sequence diagram:

Create a transaction.
Send it to a payment provider.
Receive a webhook.
Mark the transaction successful.

The difficult part begins when production stops following the diagram.

A webhook may arrive twice. A “processing” event may arrive after a “successful” event. The provider may accept an API request with HTTP 200 while the underlying payment remains pending. A status check may return a transport-level success code that has nothing to do with the financial result. In some cases, the final webhook may never arrive.

When money is involved, a webhook cannot be treated as a command to change a balance. It is evidence about an external event. The local transaction record must decide whether that evidence permits a state transition and whether the related financial effect has already happened.

Store the transaction before trusting asynchronous events

Every external payment should map to an internal transaction created before the asynchronous lifecycle begins. That record should contain enough stable identifiers to match later provider events without relying on mutable fields such as a description or customer-entered name.

A simplified record might contain:

class Payment:
    reference: str
    provider_reference: str | None
    status: str
    amount: Decimal
    currency: str
    credited_at: datetime | None

The local reference identifies the business operation. The provider reference identifies the external attempt. They serve different purposes and should not be silently substituted for each other.

Separate transport success from financial success

An HTTP success response can mean:

the provider received the request;
the request passed initial validation;
the operation was queued;
the provider returned a status payload successfully; or
the financial transaction completed.

Only the last meaning should trigger a final credit or completion.

I prefer translating provider responses into a small internal vocabulary:

PENDING = {"accepted", "queued", "processing"}
SUCCESS = {"settled", "completed"}
FAILURE = {"failed", "rejected", "cancelled"}

The real mapping varies by provider, but the rule remains constant: unknown and intermediate states should not be promoted to success.

This is especially important when a provider exposes both a general response code and a transaction status. A successful status-check request does not prove that the payment succeeded.

Make every financial effect idempotent

Webhook delivery is normally at least once. Therefore, the same success event must be safe to process repeatedly.

Checking only the transaction status is helpful but incomplete. Two workers can read the same pending status before either one commits. Both may then attempt the credit.

A stronger design protects the financial effect with its own deterministic identity:

with database_transaction():
    payment = lock_payment(reference)

    if ledger_entry_exists(key=f"deposit:{payment.reference}"):
        return "already processed"

    if payment.status in TERMINAL_STATES:
        return "ignored"

    create_ledger_credit(
        key=f"deposit:{payment.reference}",
        amount=payment.amount,
        currency=payment.currency,
    )
    payment.status = "completed"
    payment.save()

The row lock prevents concurrent transitions. The unique ledger key prevents duplicate financial effects even if application logic is retried.

Protect terminal states from older events

External systems do not always deliver events in chronological order. Once a transaction reaches a trusted terminal state, older events must not move it backward.

For example:

ALLOWED_TRANSITIONS = {
    "pending": {"processing", "completed", "failed"},
    "processing": {"completed", "failed"},
    "completed": set(),
    "failed": set(),
}

This prevents a delayed “processing” notification from reopening a completed transaction. It also stops a late failure from automatically reversing a payment that has already been independently confirmed, unless the product explicitly supports a separate reversal workflow.

Preserve raw evidence without exposing it to customers

Webhook payloads are useful for investigation, reconciliation, and provider support. Retain them with appropriate access controls, but don't make them the customer-facing transaction model.

Store both:

a normalized internal status and safe customer message;
the original provider event for staff diagnostics.

This separation prevents technical provider errors, internal account balances, or implementation details from leaking into the customer experience.

Add an active recovery path

Even a perfect webhook handler cannot process an event that never arrives. Transactions that remain in a non-terminal state need background reconciliation.

A recovery worker can:

Find processing transactions older than a safe threshold.
Query the provider using the recorded provider reference.
Normalize the returned state.
Apply the same guarded transition used by webhook processing.
Retry with limits when the provider remains inconclusive.

The webhook and reconciliation paths should converge on the same domain function. Otherwise, each path develops different rules for crediting, failure, and refunds.

The design principle

The transaction record is authoritative for what the platform has applied. The provider remains authoritative for what happened on its rail. Webhooks and status checks are two ways of collecting provider evidence; neither should bypass local invariants.

That distinction turns webhook handling from a collection of callbacks into a reliable payment lifecycle.

The practical outcome of this architecture is predictable behavior under uncertainty. Duplicate delivery becomes harmless, intermediate states remain intermediate, and a missing callback becomes a reconciliation problem instead of an indefinitely stuck payment. Those are properties that can be verified through invariants and tests without relying on an unsupported performance claim.

Making Wallet Mutations Safe Under Concurrency

Daniel Parkson Tano — Sun, 04 Oct 2026 09:08:12 +0000

Why checking a balance and then updating it is not enough in a financial system.

A wallet can be represented by one database column. A safe wallet cannot.

Consider a user with a balance of 100. Two withdrawal requests for 80 arrive almost simultaneously. Each request reads the balance before the other commits. Both see 100, both pass validation, and both subtract 80.

The application performed the expected check twice, yet it still spent the same money twice.

This is the central concurrency problem in wallet systems: validation and mutation must be one indivisible operation against a locked financial record.

Put the invariant inside the transaction

The basic invariant is straightforward:

A debit may commit only when the locked balance is greater than or equal to the debit amount.

A sanitized implementation looks like this:

with database_transaction():
    wallet = Wallet.objects.select_for_update().get(
        user_id=user_id,
        currency=currency,
    )

    if wallet.balance < amount:
        raise InsufficientFunds()

    before = wallet.balance
    wallet.balance -= amount
    wallet.save()

    LedgerEntry.objects.create(
        wallet=wallet,
        reference=reference,
        direction="debit",
        amount=amount,
        balance_before=before,
        balance_after=wallet.balance,
    )

The row lock serializes competing mutations for the same wallet. Validation uses the balance that is current while the lock is held, rather than a stale value read earlier in the request.

Make the mutation idempotent

Concurrency safety prevents two different operations from overspending the wallet. Idempotency prevents one operation from being applied twice.

A deterministic mutation key can be derived from stable business data:

raw = f"{user_id}:{currency}:{direction}:{transaction_type}:{reference}"
mutation_key = sha256(raw.encode()).hexdigest()

The ledger should enforce uniqueness on that key. An application-level existence check is useful for a clear response, but the unique database constraint is the final protection against racing workers.

with database_transaction():
    if LedgerEntry.objects.filter(idempotency_key=mutation_key).exists():
        return "already applied"

    wallet = lock_wallet(user_id, currency)
    apply_mutation(wallet, amount)
    create_ledger_entry(idempotency_key=mutation_key)

If two workers pass the existence check at the same time, the uniqueness constraint still prevents both ledger rows from being committed.

Keep balance history with the mutation

A wallet table answers “what is the balance now?” It does not explain how the balance arrived there.

Every mutation should record:

the business reference;
direction and transaction type;
currency and amount;
balance before;
balance after;
idempotency key;
timestamp; and
relevant sanitized metadata.

This creates an audit trail that supports customer support, reconciliation, incident investigation, and financial reporting.

The balance and ledger entry should commit in the same database transaction. A balance change without an audit entry is difficult to explain. An audit entry without the corresponding balance change is equally dangerous.

Treat each currency as a separate wallet

Multi-currency systems become easier to reason about when each user-currency pair has one authoritative wallet record.

UniqueConstraint(fields=["user", "currency"])

Conversions should be recorded as linked financial movements rather than an unexplained overwrite:

debit the source wallet;
record the source amount;
record the applied exchange rate;
credit the destination wallet;
record the destination amount;
preserve one conversion reference across both effects.

The conversion rate is part of the transaction’s history. Looking up today’s rate later cannot reconstruct what the customer received at execution time.

Model holds separately from completed debits

Some operations need to reserve money before completion. A withdrawal may be awaiting an external provider or manual review. Immediately treating the reservation as a final debit makes failure recovery harder.

A clearer model distinguishes:

total or actual balance;
held balance;
available balance; and
completed ledger balance.

Available funds can then be expressed as:

available = balance - active_holds

On success, the hold becomes a committed debit. On failure, the hold is released. Both transitions should be idempotent.

Do not hide negative states with arithmetic tricks

Operational adjustments, chargebacks, and debt recovery introduce another challenge. A system may need to represent an amount owed without presenting an impossible or misleading wallet state.

The safest approach is to model debt, holds, and display policy explicitly. Mixing them into a single balance field makes future credits, support investigations, and reconciliation much harder.

The design principle

A financial mutation is not an assignment such as balance = balance - amount. It is a domain operation with concurrency rules, an immutable identity, an audit record, and explicit failure behavior.

The database is not merely storage in this design. Its transaction boundaries, row locks, and constraints are part of the payment system’s correctness model.

The value of this design is structural: concurrent requests cannot safely bypass the locked balance check, and a repeated business operation cannot silently create a second ledger mutation. Correctness comes from enforceable database guarantees rather than assumptions about how often a request will be retried.