DEV Community: KitKeen

I shipped a NuGet package, then rewrote it completely. Here's why.

KitKeen — Sat, 18 Apr 2026 14:26:21 +0000

If you work in fintech and process card transactions, you've seen MCC codes. Merchant Category Code- a four-digit number that tells you what kind of business charged the card. 5411 is a grocery store. 5812 is a restaurant. 7995 is a casino.

Every product that touches transactions eventually needs to turn these codes into something a human can understand. Cashback rules, spend controls, analytics dashboards, compliance reports- they all need the same thing: given a code, what category is this?

I've built this mapping three times in production. Three separate microservices at the same company, each with its own copy. When one got updated, the others didn't. When the business asked "why is 7995 categorized as Entertainment in the app but Gambling in the compliance report?"- nobody had a good answer.

So I extracted it into a NuGet package. Then I looked at what I had actually built, benchmarked it, and rewrote it.

What v1 looked like

The first version used a FrozenDictionary<string, MccCategory>. Seemed reasonable- build once, read forever, immutable.

// v1
private static readonly FrozenDictionary<string, MccCategory> Codes = BuildCodes();

public static MccCategory Categorize(string mccCode)
    => Codes.GetValueOrDefault(mccCode, MccCategory.Other);

It worked. But there were three problems I didn't like.

First: every call allocates or assumes the caller already has a string. In a high-throughput service processing thousands of transactions per second, that adds up.

Second: FrozenDictionary hashes strings. But MCC codes are 4-digit numbers. There's a faster structure for this- one that doesn't need hashing at all.

Third: there was no way for a team with non-standard mappings to override anything without forking the library.

What v2 actually does

MCC codes are integers in the range [0, 9999]. That's a fixed-size space. So instead of a dictionary, v2 uses a plain array indexed directly by the numeric code value:

internal const int TableSize = 10_000;

private readonly MccCategory[] _codes;   // indexed by MCC integer
private readonly bool[] _occupied;       // tracks which slots are in the taxonomy

Lookup is a direct array read:

public MccCategory Categorize(int mccCode)
{
    if ((uint)mccCode >= TableSize || !_occupied[mccCode])
        return MccCategory.Uncategorized;

    return _codes[mccCode];
}

No hash function. No bucket traversal. One bounds check, one bool check, one array read. That's it.

Three overloads, one of which is allocation-free

The real-world caller is often processing a raw string from a payment event, but might have an integer from a database column or a span from a buffer. v2 handles all three:

MccLookup.Categorize(5411);              // int- fastest path
MccLookup.Categorize("5411");            // string- still zero-alloc after parse
MccLookup.Categorize(span);             // ReadOnlySpan<char>- allocation-free

The ReadOnlySpan<char> overload uses a custom parser instead of int.TryParse:

private static bool TryParseMcc(ReadOnlySpan<char> s, out int value)
{
    value = 0;
    if (s.Length == 0 || s.Length > 4)
        return false;

    var result = 0;
    for (var i = 0; i < s.Length; i++)
    {
        var c = s[i];
        if (c < '0' || c > '9') return false;
        result = result * 10 + (c - '0');
    }
    value = result;
    return true;
}

Why not int.TryParse? On netstandard2.0, the ReadOnlySpan<char> overload of int.TryParse doesn't exist. This custom parser works identically across all target frameworks, is measurably faster on the hot path, and rejects non-digit characters explicitly.

Extensibility via IMccLookup and WithCustomCodes

The built-in taxonomy covers ISO 18245. But teams have non-standard codes- internal test MCCs, network-specific extensions, or just a different opinion about which category 5962 belongs to.

v2 exposes IMccLookup and lets you override without touching the default:

IMccLookup custom = MccLookup.WithCustomCodes(new Dictionary<int, MccCategory>
{
    [9999] = MccCategory.Finance,     // add an unknown code
    [7995] = MccCategory.Leisure,     // override the built-in mapping
});

// The built-in default is not modified- it's immutable
custom.Categorize(9999);   // Finance
MccLookup.Categorize(9999); // Uncategorized- unchanged

WithCustomCodes clones the underlying arrays and applies overrides. The original instance is untouched. Thread-safe by design- no locks, no shared mutable state.

The pre-built category index

GetCodes(MccCategory.Airlines) needs to return all ~351 airline codes. In v1 this meant scanning the entire dictionary. In v2, a secondary index is built at construction time:

private readonly Dictionary<MccCategory, int[]> _codesByCategory;

So GetCodes and GetCodeValues run in O(N) over the codes in that category- not O(10000) over the whole table.

What the package gives you

// Most common: categorize by string
var cat = MccLookup.Categorize("5411");        // Supermarkets

// By integer (no string involved)
var cat = MccLookup.Categorize(5411);          // Supermarkets

// Distinguish known from unknown
if (MccLookup.TryGetCategory("5812", out var c))
    Console.WriteLine(c);                      // FoodAndDining

// Reverse lookup
var codes = MccLookup.GetCodes(MccCategory.Airlines);   // "3000".."3350" + 2 more
var ints  = MccLookup.GetCodeValues(MccCategory.Airlines);

// Custom overrides
IMccLookup lookup = MccLookup.WithCustomCodes(overrides);

No dependencies. No DI registration. Targets .NET 6.0+ and .NET Standard 2.0.

Numbers

27 categories, ~900 MCC codes (ISO 18245 + network-specific)
Array-based O(1) lookup, zero allocations on hot path
ReadOnlySpan<char> overload for buffer-friendly callers
WithCustomCodes for teams with non-standard mappings
.NET 6.0, .NET Standard 2.0, MIT license

The package is on NuGet and the source is on GitHub.

The v1 was fine. The v2 is what I'd actually want to use in a service that handles thousands of transactions per second. Sometimes you need to ship something to understand what it should have been.

Reliability Patterns for Asynchronous APIs in Fintech: A Migration Guide

KitKeen — Sun, 12 Apr 2026 09:37:05 +0000

Disclaimer: The views and opinions expressed in this article are strictly my own and do not reflect the official policy or position of my employer. The architecture, system designs, and workflows discussed have been abstracted, generalized, and simplified for educational purposes. All metrics, timelines, and numbers are approximate or illustrative and do not represent actual company data. No confidential, proprietary, or sensitive business information is disclosed in this post.

Our core banking provider, NexusBank, sent us a notice: their synchronous account-opening API was being deprecated. The deadline was strict- if we didn't migrate to their new asynchronous webhook-based flow within two weeks, new customer KYC in Belgium and Netherlands would stop completely.

If you work in fintech, you know that "account opening" is the critical backend pipeline that assigns a real IBAN to a user. Moving this flow from synchronous to asynchronous is not just about replacing one endpoint request with another. It is a fundamental shift in the reliability paradigm of your system.

When you lose synchronous immediate feedback, you can no longer treat interactions as a single atomic request-response transaction. This article serves as an engineering playbook, detailing the architectural patterns and checklists needed to safely migrate a critical distributed pipeline to an asynchronous model.

1. The Architecture Shift: From Blocking to State Machines

In the old synchronous model, our account-opening pipeline was a linear sequence that was easy to reason about:

[1] Create User Profile →
[2] Request Provider Account (Blocks) → 
[3] Issue Virtual Card

Each step ran in sequence. Step 2 blocked the execution thread until the bank generated and returned the new IBAN.

With the asynchronous provider, this atomic pipeline breaks. The account creation API now returns instantly with just a tracking_id. The actual IBAN arrives via a webhook at an unknown point in the future. Since we can't reliably predict when that happens, blocking a thread is no longer viable.

To handle this without rewriting our entire workflow engine, we split the flow and shifted to a state machine pattern by introducing a targeted "Wait State":

Phase 1: Initiation
[1] Create User Profile → 
[2] Request Provider Account (Async) → *(Pipeline Pauses)*

Phase 2: Completion
*(Webhook Arrives)* → 
[3] Match Tracking ID & Save IBAN → 
[4] Issue Virtual Card

Here is the crucial implementation detail: during Phase 1, we immediately create the account record in our database with an InProgress status and an empty IBAN/BIC.

This is critical: the system must have a persistent local database object to act as an anchor. You never want to hold memory or threads ransom waiting for a callback. When the webhook eventually arrives, it finds this pending record, updates the status, fills in the IBAN, and gracefully triggers the pipeline to resume.

2. Handling Transport Unreliability and Fallbacks

Asynchronous integrations are common in fintech, but the primary engineering challenge is delivery guarantees. Webhooks can be delayed, delivered out of order, or simply lost.

We already knew NexusBank webhooks occasionally experienced production delays. You cannot rely purely on the provider calling you back. You must design a deterministic fallback path.

Our fallback policy:

Webhook arrives
  ├─ COMPLETED / REJECTED
  │    └─ process terminal status, resume orchestration
  │
  └─ INITIATED / IN_PROGRESS (provider still working)
       └─ schedule retry in 30 min
            └─ poll provider status API directly
                 ├─ terminal status → process
                 └─ still pending → retry
                      └─ 12 hours elapsed?
                           ├─ no  → schedule another retry
                           └─ yes → emit escalation event
                                     → create ops investigation ticket

By introducing a polling fallback mechanism that terminates after 12 hours, we bounded our waiting time. If a webhook is permanently lost, the system automatically creates a Jira ticket (AccountOpeningWebhookNotReceived) with a deep link for manual investigation. No orphaned records, no silent failures.

3. Deduplication: Cache for Burst Protection

Providers often guarantee "at-least-once" delivery, making duplicate webhooks inevitable. A duplicate webhook can cause severe logical errors if processed twice.

To handle this, we implemented a cache-based deduplication layer with a specific key structure:

account_opening_request_id_{aorId}_{status}

Why include status in the key? Because a single request ID legitimately transitions through multiple states over time (INITIATED -> IN_PROGRESS -> SUCCEEDED). Processing the "same request" with a "new status" is a valid state transition.

Why Cache instead of the Database? The purpose of this specific lock is to absorb immediate retry bursts (e.g., the provider sending the same webhook three times in two seconds), not long-term state idempotency. The cache key expires after 15 minutes. Long-term idempotency is handled inherently by our database's orchestration state (a SUCCEEDED account cannot be transitioned to SUCCEEDED twice). The cache simply acts as a fast, lightweight shield against transient network spam.

4. Testing Distributed Workflows with a Sandbox

Testing async integrations by mocking external APIs locally often fails to catch edge cases in the webhook processing layer.

Instead of relying on fragile mocks, we built a dedicated Sandbox Endpoint (POST /company/account-opening/set-status-sandbox) in our non-production environments. You send it a request ID and a target status. It publishes a simulated internal webhook message that flows through the exact same production processing pipeline as a real external webhook.

This simulated message hits the deduplication locks, triggers state transitions, and advances the orchestration pipeline. This allowed us to write repeatable, end-to-end integration tests without depending on third-party staging environments.

5. Safe Rollouts via Feature Flags

Migrating a core flow with a hard deadline leaves no room for "big bang" release failures. I wrapped the dispatching logic behind dynamic feature flags scoped by market:

var isAsyncEnabled = await featureFlags.IsEnabledAsync(
    Features.AsyncAccountOpening,
    marketCode,
    ct);

if (!isAsyncEnabled)
    return await syncOpenAccountService.ExecuteAsync(context, ct);

return await asyncOpenAccountService.ExecuteAsync(context, ct);

This approach allowed us to deploy the new microservices before the deadline alongside the legacy code. We rolled out to Netherlands (companies, then freelancers) and then Belgium. At each step, if we detected malformed webhook payloads or provider instability, the feature flag allowed us to instantly reroute traffic back to the legacy sync flow- zero service interruptions and no emergency rollback deployments required.

Takeaways Checklist for Backend Teams

Moving to webhook-driven architectures requires an intentional design shift:

State Representation: Does your system explicitly track an "In Progress" database state that acts as an anchor for incoming callbacks?
Burst Protection: Are you deduplicating rapid webhook retries (e.g., using a short-lived cache lock with a composite key of ID + Status)?
Bounded Waiting: Do you have a fallback mechanism (like polling) to catch missing webhooks and prevent indefinite pipeline hanging?
Automated Escalation: What happens when the bounds are exceeded? (e.g., automatically generating an Ops Jira ticket).
End-to-End Testing: Can you inject simulated webhooks deep into your pipeline to test the actual handling logic?

Incidents in webhook architectures are rarely caused by business logic bugs; they are caused by false assumptions about transport reliability. Design for failure from day one.

We had a bug in production for 16 days. It made more money than most features I've shipped.

KitKeen — Fri, 03 Apr 2026 12:08:05 +0000

Disclaimer: To keep my lawyers happy and respect my NDA, I’ve "randomized" the actual dollar amounts in this story. While the €350k+ figures are placeholders, the 73% growth and the "accidental" logic behind it are 100% real.

+70% revenue. Not from a new feature. Not from a redesign. Not from a growth hack some PM spent three quarters planning.

From a bug. A config error that sat in production for sixteen days, silently funnelling every new user in one of our European markets into the most expensive plan.

When someone finally noticed, the team wanted a hotfix and a post-mortem. I wanted to see what's in the database.

5% vs 43%

Here's what I found.

Before the bug, 5% of new users in that market picked the premium plan. That was the normal baseline. Everyone else scrolled down to the cheapest option and hit Continue.

During the bug- when premium was the default- 43% kept it.

Forty-three percent.

The onboarding screen wasn't hiding anything. The price was right there. "Change plan" was one click away. Nobody was forced into anything. Almost half the users just looked at the premium plan and thought: yeah, this works for me.

I didn't believe it at first. Classic survivorship bias, right? They selected it, but did they actually pay?

They did.

About 40% opened and activated their accounts
Of those who stayed on the premium default, nearly half made real payments within the first month.
Only 16% downgraded later

The funnel shape was identical to the control group. Same activation rate, same payment rate. The only thing that changed was how many people entered the premium funnel. And that number was nearly 9x higher because of a bug.

The number no one expected

I pulled the revenue numbers for both cohorts over the same period.

Normal users: ~€340,000/month.
Bug users: ~€590,000/month.

Over 70% uplift. Same product. The only difference was which plan showed up first.

Let that sink in. A config error- an actual production defect- generated more incremental revenue than entire features that took months to build.

I didn't file a post-mortem. I filed a proposal.

This is where most stories end. Bug found, bug fixed, regression test added, everyone moves on. That's what a responsible engineer does.

I did the irresponsible thing. I went to the product team and said: don't fix this. Let me turn it into a controlled experiment.

The bug had accidentally created a perfect A/B test- no controls, no tracking, no consent framework, but a screaming signal. If we could reproduce it properly- with feature flags, per-country segmentation, and real cohort tracking- we'd know whether this was noise or an actual insight about how users make decisions.

They said yes.

The implementation

The whole thing was embarrassingly simple.

A feature-toggled tariff resolver that runs at registration time. Three conditions checked in sequence:

function resolveTariff(user):

    if not experiment.isEnabled(user.country):
        return defaultPlan()

    if user.type not in experiment.targetSegments:
        return defaultPlan()

    return experiment.plan    // premium

If any condition fails- default plan. No impact on anyone outside the experiment. No latency. A few in-memory lookups against cached config.

Each country had its own toggle. Kill one market without touching another. Add a new country without a deploy- just a config change.

That's it. That's the whole feature. A senior engineer could review this in ten minutes. A junior could build it in a day.

The hard part was never the code. The hard part was not fixing the bug.

It worked. Again.

The original market went first- we already had the accidental baseline. The experiment ran for a full billing cycle: real payments, not just plan selections.

The 43% selection rate from the bug period reproduced almost exactly under controlled conditions. Revenue uplift held.

We expanded to a second European market. Same results.

The product team's conclusion:

"The experiment was rather successful. We make the premium plan the recommended default during onboarding. We start the A/B experiment in the next market to check whether we'll get the same effect."

The "experiment" became the default. The feature flag stayed- as a kill switch, not an experiment.

What this actually taught me

I've shipped features with months of work behind them that moved metrics by low single digits. This one was a three-condition if statement that moved revenue by more than 70%.

There's a lesson here that most backend engineers never learn, because we're trained to think our value is in the complexity of what we build. Distributed systems, event sourcing, saga patterns, microservice choreography- that's the hard stuff, and the hard stuff is what matters. Right?

Wrong. The most impactful thing I did that year was stare at a SQL query for twenty minutes. The code I wrote afterward was trivial. A junior could do it. What a junior couldn't do- and what most seniors don't do- is pause before the fix and ask: what is the bug actually telling us?

Every production incident has a signal in it. Most of the time the signal is: something is broken, fix it. But occasionally- rarely- the signal is: your assumptions about user behaviour are wrong, and the bug just proved it.

No product manager would have proposed "show every user the most expensive plan by default." It sounds predatory. It sounds like a dark pattern. Except the data shows the opposite- users weren't tricked. They made informed decisions. They just needed better defaults.

The uncomfortable takeaway

If you're a backend engineer and you've never looked at the business impact of your code- you're flying blind.

Not because revenue is your job. It's not. But because understanding what your code does to the business changes the kind of decisions you make. It's the difference between "I fixed the bug" and "I found a pricing insight worth millions a year."

I could have closed the ticket in an hour. Instead, I spent a day in the data, wrote a proposal, and changed the default pricing strategy across multiple markets.

The code was the easiest part. The observation was the whole thing.

Building a KYC questionnaire that knows what the regulator will ask before they ask it

KitKeen — Sun, 29 Mar 2026 10:06:39 +0000

If you've never worked in fintech: KYC stands for Know Your Customer. It's the legal requirement for financial institutions to verify who their customers are before providing services. Anti-money laundering, fraud prevention, sanctions screening - all of it starts with KYC. When a business opens an account, the bank needs to understand what that business does, where its money comes from, and whether it poses any compliance risk.

Before this feature shipped, a new business customer could complete onboarding, submit their application - and then wait for the banking partner's compliance team to start asking questions.

Our banking partner performs compliance reviews on all new business accounts. As part of that review, their compliance team would send questions about business activity, industry type, international transactions, licensing, certifications. The customer would answer. Sometimes the partner would come back with another round. Multiple rounds of back-and-forth, each round adding days to the timeline.

The critical detail: these questions weren't random. The compliance team asked them based on the customer's industry. A restaurant got asked about cash handling. A financial intermediary got asked about cross-border transaction volumes. A construction company got asked about subcontractors. An IT consultancy got asked about data processing agreements. The questions were predictable. We just weren't collecting the answers before the partner asked for them.

The solution was to intercept the question-answer cycle before it started. Collect the compliance questions during onboarding - before the review even begins - so when the application lands at the banking partner, the answers are already there.

The problem with "right questions"

Not every business needs to answer the same questions. A software consultancy and a money services company have very different compliance profiles. Asking the same 30 questions to everyone wastes the customer's time and produces noise in the compliance review.

The questionnaire had to be adaptive. The question set for each customer is determined by their industry classification - in Europe, that's the NACE code. Think of it as a standardised label for what a company does: restaurants, software development, financial services, construction, logistics, etc. Every registered business has one.

Each industry classification maps to a specific set of question groups. A money transfer business gets questions about transaction monitoring and correspondent banking. A restaurant gets questions about cash revenue ratios. An e-commerce company gets questions about chargebacks and payment providers. One industry might require a dozen groups, another might need half that. The question set is assembled at generation time based on this mapping, not hardcoded per customer.

The question hierarchy

Questions aren't flat. Many have sub-questions that only make sense given a specific answer.

"Does your company conduct business internationally?" has a follow-up question about destination countries - but only if the answer is yes. Asking about destination countries when the answer is no creates noise and confuses customers.

We model this with decimal question numbers. Question 1 is a parent. Questions 1.1 and 1.2 are its children. The hierarchy is encoded in the decimal, not in a separate parent-child field.

Question 1: Does your company conduct business internationally? (Bool)
  Question 1.1: If yes, which countries? (Text) - Condition: true
  Question 1.2: If no, why not? (Text) - Condition: false

At submission time, the validator prunes the tree. If the customer answers "no" to question 1, question 1.1 is removed from the contract before storage. The customer never sees questions that don't apply to them, and the stored answers form a clean, consistent set.

Some questions are container nodes - they exist to define the hierarchy but are never shown to the user. Only leaf questions generate actual form inputs. A boolean flag on each question distinguishes containers from visible inputs.

One group per step

The questionnaire can span multiple question groups depending on industry. Rather than dumping everything on one screen, each question group is a separate onboarding step.

A customer sees their progress at the top - "Step 3 of 7" or "Step 5 of 12" depending on the industry. Each step is independently validated and submitted. Answers are stored per-step. The customer can stop mid-questionnaire and resume later without losing progress. Completed steps are marked hidden - the answers are preserved for the compliance audit trail, but the customer can't edit them after submission.

The routing logic tracks which compliance steps are still pending. When the customer completes a step, it finds the next incomplete one and routes there. When all compliance steps are done, onboarding picks up from where it left off.

Preventing duplicates

Question generation runs once per customer. But onboarding flows have concurrent paths - multiple events can trigger at the same time, and we had to ensure we didn't generate duplicate question sets.

Two layers of protection:

┌─────────────────────────────────────────────────────────┐
│              Generate questionnaire request              │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
              ┌─────────────────┐     YES
              │  Cache lock set? ├────────────► Drop request
              └────────┬────────┘
                  NO   │
                       ▼
             Set cache lock (short TTL)
                       │
                       ▼
          ┌────────────────────────┐     YES
          │  Completion flag set?  ├────────────► Drop request
          └────────────┬───────────┘
                  NO   │
                       ▼
             Generate questions
                       │
                       ▼
           Set completion flag (persistent)
                       │
                       ▼
                    Done ✓

First, a distributed cache lock with a short TTL using set-if-not-exists semantics. The first request to generate the questionnaire for a given onboarding ID wins. Concurrent requests within the TTL window are dropped.

Second, a persistent completion flag written to the onboarding metadata after generation completes. Even if the cache expires, the flag prevents re-generation.

The rollout

We didn't enable this for all customers at once. The feature was introduced during an ongoing product with existing customers, and asking existing customers to answer compliance questions mid-flight would have been disruptive.

Two feature toggles controlled the rollout. The first controls eligibility by customer creation date - customers created before the launch date are excluded. Hard boundary, no percentage, no A/B. The second controls traffic within eligible customers - started at 0%, increased gradually as we validated the system in production. The two toggles are independent: scope (who is eligible) and volume (what percentage see it) are controlled separately.

The numbers

Thousands of customers completed the questionnaire during the rollout period.

The banking partner's compliance review started with all required information already in the application. No rounds of questions. No waiting for customer responses. The back-and-forth that previously stretched across days of email exchanges was replaced by a single session during onboarding - at the point where the customer was already engaged and focused on getting their account open.

The technical work - industry-based question mapping, conditional logic, multi-step navigation, distributed deduplication - existed to serve one outcome: anticipating what the regulator would ask, and collecting those answers before the review even began.

What changed in the code

Before this feature, question generation was a static config:

// Before: same questions for every customer
var questions = LoadDefaultComplianceQuestions();
SendToPartner(application, questions);
// Partner replies: "We also need to know about X, Y, Z"
// Customer gets emailed. Waits. Answers. Waits again.

After:

// After: industry-adaptive generation
var industry = GetIndustryClassification(customer);
var questionGroups = MapIndustryToQuestionGroups(industry);
var tree = BuildConditionalTree(questionGroups);

// Customer answers during onboarding
var answers = CollectAnswersDuringOnboarding(tree);
var pruned = PruneByConditions(tree, answers);

SendToPartner(application, pruned);
// Partner receives complete data. No follow-up needed.

The difference in flow:

BEFORE:
Customer → Submit app → Partner reviews → Questions round 1
→ Customer replies (days) → More questions → Customer replies (days)
→ Approved
Total: days to weeks of back-and-forth

AFTER:
Customer → Answer compliance questions during onboarding → Submit app
→ Partner reviews (answers already attached) → Approved
Total: single onboarding session

No new infrastructure. No external dependencies. Just a question mapping layer, a conditional tree, and a deduplication guard - inserted into the existing onboarding pipeline.