Forem: Yusuf Adeniyi

Designing for Failure: Building Reliable Crypto-to-Utility Payments with Provider Failover

Yusuf Adeniyi — Thu, 08 Jan 2026 12:02:49 +0000

Introduction

On paper, a crypto-to-utility pipeline is a simple sequence: verify the on-chain transaction, trigger a biller's API, and return a success state.

In production, "simple" integrations are where the most expensive failures happen. When handling user funds, reliability isn't a feature; it’s the foundation. As the lead engineer, I built Elites Africa with a Multi-Provider Failover strategy from day one. To balance high availability with latency constraints, I architected the system around a primary provider with a ‘hot’ secondary backup. This ensures we can recover from a provider failure in real-time without exceeding the timeout thresholds that degrade the user experience.

The Architecture: Designing for Failure

I built the system to handle everything from airtime and data to electricity and Chowdeck (food delivery wallet) funding. Given the nature of crypto payments, the user expectation for "instant value" is high.

The Lifecycle

Selection & Intent: The user picks a service (e.g., MTN Data). Instead of a live fetch, we serve this from our local cache to keep the UI snappy.
The Crypto Leg: We leverage the Coinley SDK for the wallet handshake. Once the success callback triggers, our backend takes over.
Synchronous Execution: Instead of relying on asynchronous webhooks that delay user certainty, we process bill payments synchronously. When a provider fails, we detect it immediately and can retry or refund without leaving users waiting.
Logging & Attempts: Every request is wrapped in a PaymentAttempt entity. This gives us a granular audit trail of exactly which provider failed and why.

The Problem: Data Fragmentation

When we integrated our second provider, we hit a wall. Provider A might represent an MTN 1GB plan as mtn-data-1gb, while Provider B uses an integer ID like 444402.

If the primary provider fails, you can't simply "retry" with the second provider using the first one's metadata. The systems are fundamentally incompatible in their naming conventions and response structures. Without a translation layer, failover logic is dead on arrival.

The Solution: Internal Code Mapping

To solve this, I implemented an Internal Abstraction Layer. We stopped treating provider codes as the source of truth. Instead, we introduced a standardized internal schema that represents the logical service. At runtime, the system resolves internalCode → provider-specific metadata based on provider availability

The Mapping Strategy:

Category	Internal Code Pattern	Example
Airtime	`{network}-airtime`	`mtn-airtime`
Data	`{network}-data-{value}`	`glo-data-1000`
Electricity	`{disco}-electricity`	`ikeja-electricity`

We run a weekly synchronization script that pulls fresh metadata from all providers and maps them to these internal codes. This allows the backend to be provider-agnostic. When a payment fails on Provider A, the system looks up the same internalCode for Provider B and executes the retry instantly.

Engineering Trade-offs

Every architecture has its "debt." Here is how we weighed our decisions:

Synchronous Processing vs. Event-Driven: By choosing synchronous calls, we prioritize user certainty over server throughput. The trade-off is increased latency during provider timeouts, but in fintech, a slow success is better than a fast "maybe."
Database vs. Live Fetch: Storing plans locally allows for provider switching without redeploying code. The downside is the "stale data" risk, which we mitigate with our weekly cron syncs.
Partial Catalog Failover (80/20 Rule): Not all plans exist on all providers (e.g., certain niche data bundles). Our fallback logic currently covers about 80% of our catalog. For the remaining 20%, we’ve accepted that a failure on the primary provider will result in a refund or manual intervention; a conscious choice to avoid over-engineering for edge cases.

Closing Thoughts

After 7 years in engineering, you realize that the "happy path" is easy. The real work is in the edge cases. At Elites Africa, we didn't just build a bill payment platform; we built a system that assumes providers will fail and has a plan for when they do.

True architectural maturity isn't about the newest tech stack; it's about how gracefully your system fails.

My Git Workflow and Essential Commands

Yusuf Adeniyi — Fri, 01 Aug 2025 09:00:39 +0000

Learning to use Git effectively isn’t always straightforward—especially for many of us developers. Git has a vast set of commands, and honestly, no one knows them all. However, some essential commands like git pull and git push are used regularly.

While Git proficiency comes with experience, learning key commands and best practices early can significantly improve your workflow and make you a better developer. In this guide, I’ll share some Git commands I use regularly, starting with the basics and moving to more advanced ones. I hope it helps anyone reading this.

🧱 Basic Git Commands

git init
Initialize a new Git repository in your current directory.

git status
Shows the current state of your working directory and staging area.
Tip: Run this often to check what’s staged, modified, or untracked.

git clone <repository>
Downloads a remote repository to your local machine.
Example: git clone https://github.com/user/repo.git

git add .
Stage all changes in your working directory.

git add <filepath>
Stage a specific file for commit.

git commit -m "message"
Commit staged changes with a descriptive message.

git log
View the commit history.

git checkout <branch>
Switch to an existing branch.
Tip: Consider using git switch <branch> for a more intuitive experience.

git checkout -b <branch>
Create and switch to a new branch.

git branch
List all branches.

git branch -D <branch>
Delete a branch.

git branch -M <old> <new>
Rename a branch from <old> to <new>.

git pull
Fetch and merge changes from the remote branch.
Tip: Use git pull --rebase to avoid unnecessary merge commits.

git push
Push your local commits to the remote repository.

git fetch
Retrieve changes from the remote without merging.

git merge <branch>
Merge another branch into your current branch.

🚀 Advanced Git Commands

These are often extensions of basic commands with extra arguments or specific use cases.

`git add -p <filepath>`

Stage parts of a file instead of the whole file. It opens an interactive mode where you select specific "hunks" (sections of code) to stage.

Common options:

y: stage this hunk
n: don’t stage this hunk
q: quit (don’t stage this or remaining hunks)
a: stage this hunk and all later hunks
d: don’t stage this hunk or later ones
s: split the hunk into smaller chunks
e: manually edit the hunk
?: show help

Mini story: When I first started, I pushed large commits with unrelated changes. Using git add -p helped me group changes logically, making code review easier.

`git commit --amend` or `git commit -a --no-edit`

Add new staged changes to the previous commit, especially if related.
Warning: Only use this for commits not yet pushed to remote repositories.

`git log branchA..branchB`

Shows commits in branchB not in branchA. Combine with --oneline for readability:

git log --oneline branchA..branchB

`git diff branchA..branchB`

Shows code changes in branchB that aren’t in branchA.

`git diff --name-only branchA..branchB`

Shows filenames only that differ between two branches.

`git cherry-pick <commit1> <commit2>`

Apply specific commits from another branch onto your current branch. Useful when releasing select features or fixes.

`git stash`

Temporarily saves uncommitted changes to work on something else.

git stash push -m "WIP on feature X"
git stash pop

`git rebase -i`

Interactive rebase lets you clean up commit history—squash, reorder, or remove commits.

✅ Best Practices and Advice

1. Commit Often, but Meaningfully

Keep commits small and focused on a single purpose.

2. Write Clear Commit Messages

Explain the “why,” not just the “what.”

Good: Fix login error when password is empty

Bad: fix bug

3. Never Rebase Shared Branches

Rebasing rewrites history; only do it on local branches not pushed to others.

4. Use Branches for Features and Fixes

Keep your main branch clean. Create new branches for features or bug fixes.

5. Pull Often, Push When Ready

Regularly run git pull --rebase to minimize conflicts. Push only when your code is ready.

6. Clean Up Before Merging

Use git rebase -i or squash commits to tidy history before merging.

Tip: GitHub's Squash and merge feature can do this for you automatically during pull request merges.

7. Learn by Breaking (Locally)

Experiment freely. You can recover lost commits using git reflog.

8. Use `.gitignore` Wisely

Exclude environment files, dependencies, or secrets to keep your repo clean.

Useful Resources

💬 Got Questions or Tips?
I wrote this guide to share how I use Git day-to-day and to help others who might be feeling overwhelmed by all the commands. If you have questions, feedback, or your own Git tips, feel free to drop them in the comments. I'd love to hear how you use Git or what helped you learn it!

Final Thoughts

This is not an exhaustive list of Git commands, but it includes the ones I use the most. Git has a steep learning curve at first, but understanding just a handful of useful commands and when to use them can greatly improve your workflow and confidence.