Provider Adapter Interface & First Integration (Yellow Card)

[grantfox-oss]

Overview

The internal/fiat/ package exists in the project structure as a fiat rail abstraction with provider adapters, but the interface and adapters are not yet implemented. Without this layer, Fluxa cannot accept local currency deposits or initiate local currency withdrawals — the core value proposition for emerging market cross-border payments. This issue defines the provider interface and implements the first concrete adapter: Yellow Card, which supports fiat-to-crypto on/off ramps across multiple African markets.

What needs to be built

internal/fiat/ — Provider interface

• Provider interface with methods: Name(), SupportedCountries(), GetQuote(), InitiateDeposit(), InitiateWithdrawal(), GetStatus(), HandleWebhook()

• FiatQuote type — local currency amount, USDC equivalent, exchange rate, fee, expiry

• DepositInstruction type — bank account details or mobile money prompt to show the end user

• RailEvent type — normalised event type (deposit.confirmed, withdrawal.sent, etc.) + provider reference
  internal/fiat/yellowcard/ — Yellow Card adapter

• Implements the Provider interface against the Yellow Card API

• GetQuote — calls Yellow Card rates endpoint, returns normalised FiatQuote

• InitiateDeposit — creates a Yellow Card payment channel, returns bank/mobile money instructions

• InitiateWithdrawal — submits a Yellow Card payout to a local bank or mobile money number

• GetStatus — polls Yellow Card for transaction status by provider reference

• HandleWebhook — verifies Yellow Card HMAC signature, parses event, returns normalised RailEvent
internal/transfer/ — Fiat-linked transfer types

• Extend Transaction domain type with optional fiat_rail, fiat_provider_ref, fiat_status fields

• New transfer type: fiat_deposit — creates a deposit instruction via the rail and waits for a deposit.confirmed webhook before crediting the internal wallet

• New transfer type: fiat_withdrawal — debits the internal wallet, then submits a withdrawal via the rail
  New API endpoints

• POST /v1/fiat/deposit — returns deposit instructions for a given country + local amount

• POST /v1/fiat/withdraw — initiates a local currency payout from a Fluxa wallet

• POST /v1/fiat/webhooks/yellowcard — receives and processes Yellow Card webhook events
  db/migrations/

• Extend transactions table: fiat_rail, fiat_provider_ref, fiat_status, local_currency, local_amount

Acceptance criteria

• Yellow Card adapter passes all unit tests with mocked HTTP responses
• POST /v1/fiat/deposit returns valid bank/mobile money instructions for at least Nigeria, Ghana, and Kenya
• Deposit flow completes end-to-end on Yellow Card sandbox: instruction → webhook → wallet credited
• Withdrawal flow completes end-to-end: wallet debited → Yellow Card payout initiated → status tracked
• A second provider can be added by implementing Provider with zero changes to the transfer service
• All fiat transactions have audit rows with local currency amounts and provider references

[Anichris-koded]

Hi, my name is Koded and I specialize in payment integrations, API architecture, and scalable fintech systems. For projects involving a Provider Adapter Interface and integrations such as Yellow Card, I design flexible, maintainable adapter layers that standardize provider interactions while simplifying future integrations. My approach ensures reliable transaction processing, clean abstraction boundaries, and a scalable foundation for supporting multiple payment providers with minimal operational complexity.

[morelucks]

Hello,

I’m a smart contract and full-stack developer interested in contributing to this issue. I have experience contributing on OnlyDust and have participated in Drips Wave 1, Wave 2, as well as GrantFox.

My technical background includes Rust, Soroban, Cairo, Solidity, and TypeScript, with a focus on building secure, scalable, and maintainable blockchain applications.

Based on the scope of this issue, I’m confident I can deliver a complete and well-tested solution within 24 hours of assignment. I prioritize clean code, clear documentation, and efficient implementation.

I’d appreciate the opportunity to contribute and help move this forward.

[oladeeayo]

Hey maintainer, I am interested in working on this issue

[grantfox-oss]

🦊 GrantFox — @oladeeayo has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #23)
2. Your PR will be reviewed by the Savitura maintainers

Good luck! Track your progress on GrantFox.