The Big Currency Update: Source and Destination Currencies

pythonclass Transaction(Base):
    amount = Column(Float)       # But which amount?
    currency = Column(String(3)) # But which currency?

pythonclass Transaction(Base):
    # Source: what the customer pays
    source_amount = Column(Float, nullable=False)
    source_currency = Column(String(3), nullable=False)

    # Destination: what the merchant receives
    destination_amount = Column(Float, nullable=True)
    destination_currency = Column(String(3), nullable=True)

    # Legacy fields (kept for backward compatibility during migration)
    amount = Column(Float, nullable=True)       # Deprecated
    currency = Column(String(3), nullable=True)  # Deprecated

pythontransaction = Transaction(
    source_amount=10.00,
    source_currency="USD",
    destination_amount=6200.00,
    destination_currency="XOF",
)

sql-- Migration: add currency columns
ALTER TABLE transactions ADD COLUMN source_amount FLOAT;
ALTER TABLE transactions ADD COLUMN source_currency VARCHAR(3);
ALTER TABLE transactions ADD COLUMN destination_amount FLOAT;
ALTER TABLE transactions ADD COLUMN destination_currency VARCHAR(3);

-- Backfill from legacy columns
UPDATE transactions
SET source_amount = amount,
    source_currency = currency
WHERE source_amount IS NULL;

python# services/payment.py
async def create_payment(data: PaymentCreate, app: App) -> Transaction:
    transaction = Transaction(
        id=generate_transaction_id(),
        app_id=app.id,
        user_id=app.user_id,
        source_amount=data.amount,
        source_currency=data.currency,
        reference=data.reference,
        status="pending",
        # Legacy fields (kept during transition)
        amount=data.amount,
        currency=data.currency,
    )

    # Route to provider
    provider = await route_payment(app, data)

    # If provider supports currency conversion, get destination
    if provider.supports_conversion:
        conversion = await provider.get_conversion(
            amount=data.amount,
            from_currency=data.currency,
            to_currency=app.settlement_currency,
        )
        transaction.destination_amount = conversion.amount
        transaction.destination_currency = conversion.currency

    db.add(transaction)
    await db.commit()
    return transaction

python# providers/stripe_adapter.py
class StripeAdapter(BaseProvider):
    async def process_payment(self, transaction: Transaction, credentials: dict) -> PaymentResult:
        intent = await stripe.PaymentIntent.create(
            amount=to_smallest_unit(transaction.source_amount, transaction.source_currency),
            currency=transaction.source_currency.lower(),
            # Stripe handles conversion internally
        )

        return PaymentResult(
            provider_id=intent.id,
            status=map_stripe_status(intent.status),
            source_amount=transaction.source_amount,
            source_currency=transaction.source_currency,
            # Stripe's conversion (if applicable)
            destination_amount=from_smallest_unit(
                intent.amount_received, intent.currency
            ) if intent.amount_received else None,
            destination_currency=intent.currency.upper() if intent.currency != transaction.source_currency.lower() else None,
        )

python# schemas/transaction.py
class TransactionResponse(BaseModel):
    id: str
    status: str

    # New currency fields
    source_amount: float
    source_currency: str
    destination_amount: float | None = None
    destination_currency: str | None = None

    # Legacy (deprecated, will be removed in v2)
    amount: float | None = None
    currency: str | None = None

    created_at: datetime

    class Config:
        json_schema_extra = {
            "example": {
                "id": "tx_abc123",
                "status": "completed",
                "source_amount": 10.00,
                "source_currency": "USD",
                "destination_amount": 6200.00,
                "destination_currency": "XOF",
                "amount": 10.00,  # Deprecated
                "currency": "USD",  # Deprecated
            }
        }

python# Deprecation warning in response headers
@router.get("/transactions/{id}")
async def get_transaction(id: str):
    transaction = await get_transaction_or_404(id)
    response = TransactionResponse.from_orm(transaction)

    return JSONResponse(
        content=response.dict(),
        headers={
            "Deprecation": "true",
            "Sunset": "2026-06-01",
            "Link": '<https://docs.0fee.dev/migration/currency-update>; rel="deprecation"',
        } if response.amount is not None else {}
    )

pythonclass Transaction(Base):
    exchange_rate = Column(Float, nullable=True)  # e.g., 620.0 for USD->XOF

python# Fee is always calculated on source amount
fee_amount = transaction.source_amount * 0.0099
fee_currency = transaction.source_currency

typescript// Frontend: transaction amount display
function formatTransactionAmount(tx: Transaction): string {
    const source = `${formatCurrency(tx.source_amount, tx.source_currency)}`;

    if (tx.destination_currency && tx.destination_currency !== tx.source_currency) {
        const dest = `${formatCurrency(tx.destination_amount, tx.destination_currency)}`;
        return `${source} -> ${dest}`;
    }

    return source;
}

// Example outputs:
// "$10.00 USD"                    (same currency)
// "$10.00 USD -> 6,200 XOF"      (cross-currency)