The latest updates on your projects. Learn more about Vercel for Git ↗︎

Walkthrough

This update enhances payout confirmation by adding currency conversion for "sepa_debit" and "acss_debit" payment methods using Stripe FX quotes with a markup. It stores Stripe charge metadata in invoices, updates invoice display to show non-USD amounts, and adjusts webhook handling to save charge details. A new FX quote utility and a forex markup constant are introduced. Payment method UI and API restrict SEPA Debit to Enterprise plans.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant App
    participant Stripe

    User->>App: Initiate payout confirmation
    App->>App: Determine payout currency based on payment method
    App->>Stripe: Request FX quote if payment method requires conversion
    Stripe-->>App: Return FX quote with exchange rate
    App->>App: Calculate converted payout amount with markup
    App->>Stripe: Create payment intent with converted amount and currency
    Stripe-->>App: Return payment intent details
    App->>App: Create invoice with payment intent and charge metadata
    App->>User: Complete payout confirmation flow

Possibly related PRs

• Support more direct debit methods for payouts #2433: Broadens payout support by adding multiple direct debit methods and refactoring payout fee calculation and payment method handling; modifies the same payout confirmation code and payment method constants.
• Dynamic payout fee on workspace level #2569: Focuses on dynamic payout fee calculation per workspace in the payout confirmation flow; related by modifying the same function but addressing different concerns than currency conversion.

Suggested reviewers

• devkiran

Poem

A bunny hopped through code so bright,
Adding currencies left and right.
With Stripe’s FX rates in tow,
Payouts now convert as they go.
In invoices, charge details hide,
Markups and logs hop side by side.
Oh, what a global bunny ride! 🐇💸

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

@CodeRabbit final review

#!/bin/bash
# Get the core implementation files to analyze the currency conversion logic
echo "=== Core Payout Confirmation Logic ==="
cat apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts

echo -e "\n\n=== FX Quote Utility ==="
cat apps/web/lib/stripe/create-fx-quote.ts

echo -e "\n\n=== Webhook Handler Changes ==="
cat apps/web/app/\(ee\)/api/stripe/webhook/charge-succeeded.ts

echo -e "\n\n=== Invoice Schema Changes ==="
cat packages/prisma/schema/invoice.prisma | grep -A 5 -B 5 "stripeChargeMetadata\|amount.*USD\|fee.*USD\|total.*USD"

echo -e "\n\n=== Constants ==="
cat apps/web/lib/partners/constants.ts | grep -A 2 -B 2 "FOREX"

#!/bin/bash
# Check the invoice display implementation to see how the converted amounts are shown
echo "=== Invoice Display Implementation ==="
cat apps/web/app/\(ee\)/app.dub.co/invoices/\[invoiceId\]/route.tsx

echo -e "\n\n=== Currency Formatter Utility ==="
cat packages/utils/src/functions/currency-formatter.ts

echo -e "\n\n=== Look for error handling patterns ==="
rg -A 3 -B 1 "throw new Error|try.*catch" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts

echo -e "\n\n=== Check for any TODOs or FIXMEs in the implementation ==="
rg -i "todo|fixme|hack|temp" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts apps/web/lib/stripe/create-fx-quote.ts

@steven-tey I've completed a comprehensive final review of the currency conversion implementation. Here's my assessment:

✅ Strengths & Well-Implemented Features

Architecture & Code Quality

• Clean separation of concerns: FX quote logic is properly abstracted into a dedicated utility (create-fx-quote.ts)
• Type safety: Excellent use of TypeScript, Zod validation, and proper error handling
• Database integrity: Proper use of Prisma transactions to ensure data consistency
• Error handling: Comprehensive error cases covered with descriptive messages

Currency Conversion Logic

• Accurate implementation: Proper currency mapping (sepa_debit → EUR, acss_debit → CAD)
• Exchange rate validation: Validates rates are positive and exist before conversion
• Markup application: Correctly applies 0.5% forex markup with proper calculation
• Rounding: Uses Math.round() for final converted amounts (appropriate for currency)

Invoice Display & UX

• Dual currency display: Shows both USD base amount and converted currency amount
• Metadata storage: Stores complete Stripe charge metadata for future reference
• Flexible currency formatter: Updated to support dynamic currencies

⚠️ Areas for Improvement & Potential Issues

1. API Stability Concerns

// Using preview feature flag - potential stability risk
"Stripe-Version": "2025-05-28.basil;fx_quote_preview=v1"

Recommendation: Monitor Stripe's API changelog and migrate to stable version when available.

2. No Retry Mechanism

The FX quote API call lacks retry logic for transient failures:

// Single API call without retry
const fxQuoteResponse = await fetch("https://api.stripe.com/v1/fx_quotes", {
  // ... no retry logic
});

Recommendation: Implement exponential backoff retry for API resilience.

3. Performance Optimization Opportunities

• No exchange rate caching: Each payout confirmation fetches fresh rates
• Sequential processing: No batch processing for multiple payouts with same currency

Recommendation: Consider caching exchange rates for short periods (5-15 minutes) to reduce API calls.

4. Configuration & Flexibility

// Hardcoded markup percentage
const FOREX_MARKUP_PERCENTAGE = 0.5;

Recommendation: Consider making markup configurable per workspace or payment method.

5. Monitoring & Observability

Limited logging for currency conversion operations:

console.log(`Currency conversion: ${total} usd -> ${convertedTotal} ${currency}...`);

Recommendation: Add structured logging with conversion metadata for better monitoring.

🔒 Security & Compliance

✅ Good practices implemented:

• Proper Stripe API authentication
• Input validation with Zod schemas
• Database transactions for consistency
• No sensitive data exposure in logs

🚀 Recommendations for Future Enhancements

1. Add rate caching with Redis or in-memory cache for better performance
2. Implement retry logic with exponential backoff for API calls
3. Add monitoring for exchange rate fluctuations and conversion volumes
4. Consider batch processing for multiple payouts in same currency
5. Add configuration options for markup percentages per payment method
6. Monitor Stripe API migration path from preview to stable version

📊 Overall Assessment

This is a solid, production-ready implementation that demonstrates good engineering practices. The code is well-structured, properly tested through error handling, and maintains data integrity. The currency conversion logic is mathematically sound and the user experience is enhanced with clear dual-currency display.

The implementation successfully addresses the core requirement of SEPA/ACSS payout currency conversion while maintaining code quality and following established patterns in the codebase.

Grade: A- (Excellent with minor optimization opportunities)

The feature is ready for production deployment with the noted monitoring recommendations for the preview API usage.

@CodeRabbit final review

#!/bin/bash
# Get the core implementation files to analyze the currency conversion logic
echo "=== Core Payout Confirmation Logic ==="
cat apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts

echo -e "\n\n=== FX Quote Utility ==="
cat apps/web/lib/stripe/create-fx-quote.ts

echo -e "\n\n=== Webhook Handler Changes ==="
cat apps/web/app/\(ee\)/api/stripe/webhook/charge-succeeded.ts

echo -e "\n\n=== Invoice Schema Changes ==="
cat packages/prisma/schema/invoice.prisma | grep -A 5 -B 5 "stripeChargeMetadata\|amount.*USD\|fee.*USD\|total.*USD"

echo -e "\n\n=== Constants ==="
cat apps/web/lib/partners/constants.ts | grep -A 2 -B 2 "FOREX"

#!/bin/bash
# Check the invoice display implementation to see how the converted amounts are shown
echo "=== Invoice Display Implementation ==="
cat apps/web/app/\(ee\)/app.dub.co/invoices/\[invoiceId\]/route.tsx

echo -e "\n\n=== Currency Formatter Utility ==="
cat packages/utils/src/functions/currency-formatter.ts

echo -e "\n\n=== Look for error handling patterns ==="
rg -A 3 -B 1 "throw new Error|try.*catch" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts

echo -e "\n\n=== Check for any TODOs or FIXMEs in the implementation ==="
rg -i "todo|fixme|hack|temp" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts apps/web/lib/stripe/create-fx-quote.ts

@steven-tey I've completed a comprehensive final review of the currency conversion implementation. Here's my assessment:

✅ Strengths & Well-Implemented Features

Architecture & Code Quality

• Clean separation of concerns: FX quote logic is properly abstracted into a dedicated utility (create-fx-quote.ts)
• Type safety: Excellent use of TypeScript, Zod validation, and proper error handling
• Database integrity: Proper use of Prisma transactions to ensure data consistency
• Error handling: Comprehensive error cases covered with descriptive messages

Currency Conversion Logic

• Accurate implementation: Proper currency mapping (sepa_debit → EUR, acss_debit → CAD)
• Exchange rate validation: Validates rates are positive and exist before conversion
• Markup application: Correctly applies 0.5% forex markup with proper calculation
• Rounding: Uses Math.round() for final converted amounts (appropriate for currency)

Invoice Display & UX

• Dual currency display: Shows both USD base amount and converted currency amount
• Metadata storage: Stores complete Stripe charge metadata for future reference
• Flexible currency formatter: Updated to support dynamic currencies

⚠️ Areas for Improvement & Potential Issues

1. API Stability Concerns

// Using preview feature flag - potential stability risk
"Stripe-Version": "2025-05-28.basil;fx_quote_preview=v1"

Recommendation: Monitor Stripe's API changelog and migrate to stable version when available.

2. No Retry Mechanism

The FX quote API call lacks retry logic for transient failures:

// Single API call without retry
const fxQuoteResponse = await fetch("https://api.stripe.com/v1/fx_quotes", {
  // ... no retry logic
});

Recommendation: Implement exponential backoff retry for API resilience.

3. Performance Optimization Opportunities

• No exchange rate caching: Each payout confirmation fetches fresh rates
• Sequential processing: No batch processing for multiple payouts with same currency

Recommendation: Consider caching exchange rates for short periods (5-15 minutes) to reduce API calls.

4. Configuration & Flexibility

// Hardcoded markup percentage
const FOREX_MARKUP_PERCENTAGE = 0.5;

Recommendation: Consider making markup configurable per workspace or payment method.

5. Monitoring & Observability

Limited logging for currency conversion operations:

console.log(`Currency conversion: ${total} usd -> ${convertedTotal} ${currency}...`);

Recommendation: Add structured logging with conversion metadata for better monitoring.

🔒 Security & Compliance

✅ Good practices implemented:

• Proper Stripe API authentication
• Input validation with Zod schemas
• Database transactions for consistency
• No sensitive data exposure in logs

🚀 Recommendations for Future Enhancements

1. Add rate caching with Redis or in-memory cache for better performance
2. Implement retry logic with exponential backoff for API calls
3. Add monitoring for exchange rate fluctuations and conversion volumes
4. Consider batch processing for multiple payouts in same currency
5. Add configuration options for markup percentages per payment method
6. Monitor Stripe API migration path from preview to stable version

📊 Overall Assessment

This is a solid, production-ready implementation that demonstrates good engineering practices. The code is well-structured, properly tested through error handling, and maintains data integrity. The currency conversion logic is mathematically sound and the user experience is enhanced with clear dual-currency display.

The implementation successfully addresses the core requirement of SEPA/ACSS payout currency conversion while maintaining code quality and following established patterns in the codebase.

Grade: A- (Excellent with minor optimization opportunities)

The feature is ready for production deployment with the noted monitoring recommendations for the preview API usage.

@CodeRabbit final review, any logical errors you can find?

#!/bin/bash
# Analyze the core currency conversion logic for logical errors
echo "=== Analyzing Currency Mapping Logic ==="
cat apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts | grep -A 10 -B 5 "PAYMENT_METHOD_CURRENCY_MAPPING\|currency.*=\|exchangeRate"

echo -e "\n=== Analyzing Exchange Rate Calculation ==="
cat apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts | grep -A 15 -B 5 "convertedTotal.*=\|Math.round\|FOREX_MARKUP_RATE"

echo -e "\n=== Analyzing FX Quote Validation ==="
cat apps/web/lib/stripe/create-fx-quote.ts | grep -A 10 -B 5 "exchange_rate\|rates\|fxQuoteSchema"

echo -e "\n=== Check for potential division by zero or invalid rates ==="
rg "exchangeRate.*[*/]|/.*exchangeRate|rates\[" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts apps/web/lib/stripe/create-fx-quote.ts

echo -e "\n=== Check invoice display logic for currency handling ==="
cat apps/web/app/\(ee\)/app.dub.co/invoices/\[invoiceId\]/route.tsx | grep -A 8 -B 3 "stripeChargeMetadata\|currency.*!==.*USD\|nonUsdTransactionDisplay"

const currency = paymentMethodToCurrency[paymentMethod.type] || "usd";

const PAYMENT_METHOD_CURRENCY_MAPPING = {
  sepa_debit: "eur",
  acss_debit: "cad"
} as const;

const currency = PAYMENT_METHOD_CURRENCY_MAPPING[paymentMethod.type] || "usd";

const exchangeRate = fxQuote.rates[currency].exchange_rate;

const rateData = fxQuote.rates[currency];
if (!rateData) {
  throw new Error(`Exchange rate for ${currency} not found in FX quote response`);
}
const exchangeRate = rateData.exchange_rate;

// Comment says "convert the amount to EUR/CAD" 
const fxQuote = await createFxQuote({
  fromCurrency: currency,  // EUR/CAD
  toCurrency: "usd",       // USD
});
// But then we divide USD by EUR→USD rate
convertedTotal = Math.round((total / exchangeRate) * (1 + FOREX_MARKUP_RATE));

const fxQuote = await createFxQuote({
  fromCurrency: "usd",     // We're converting FROM USD
  toCurrency: currency,    // TO EUR/CAD
});
const exchangeRate = fxQuote.rates["usd"].exchange_rate; // USD to target currency rate
convertedTotal = Math.round((total * exchangeRate) * (1 + FOREX_MARKUP_RATE));

// Comment says "use the cached rate from Redis" but there's no Redis logic
if (!exchangeRate || exchangeRate <= 0) {
  throw new Error(`Failed to get exchange rate from Stripe for ${currency}.`);
}

#!/bin/bash
# Look for the currency mapping definition and verify the logic flow
echo "=== Finding Currency Mapping Definition ==="
rg -A 5 -B 5 "paymentMethodToCurrency|PAYMENT_METHOD_CURRENCY_MAPPING" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts

echo -e "\n=== Check for missing null checks in FX quote access ==="
rg -A 3 -B 3 "fxQuote\.rates\[.*\]" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts

echo -e "\n=== Verify total amount units (cents vs dollars) ==="
rg -A 3 -B 3 "amount.*\*.*fee|total.*=.*amount" apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts

echo -e "\n=== Check conversion direction logic ==="
echo "Looking at the FX quote request parameters vs usage:"
cat apps/web/app/\(ee\)/api/cron/payouts/confirm/confirm-payouts.ts | grep -A 8 -B 2 "createFxQuote"

@steven-tey I need to correct my previous analysis after seeing the complete code. Here are the actual logical errors I found:

✅ Corrections to My Previous Assessment

Currency Mapping Definition

My initial assessment was wrong - the mapping IS defined:

const paymentMethodToCurrency = {
  sepa_debit: "eur", 
  acss_debit: "cad",
} as const;

Conversion Direction Logic

The direction is actually mathematically correct:

• USD total ÷ (EUR→USD rate) = EUR amount ✅
• Example: $100 USD ÷ 1.1 (EUR→USD rate) = €90.91 EUR ✅

🚨 Real Logical Errors Found

1. Unsafe Property Access (Critical)

const exchangeRate = fxQuote.rates[currency].exchange_rate;

❌ Error: No null/undefined check for fxQuote.rates[currency]. If Stripe doesn't include the expected currency key, this throws a runtime error.

Fix needed:

const rateData = fxQuote.rates[currency];
if (!rateData) {
  throw new Error(`Exchange rate for ${currency} not found in FX quote response`);
}
const exchangeRate = rateData.exchange_rate;

2. Type Safety Issue (Medium)

const currency = paymentMethodToCurrency[paymentMethod.type] || "usd";

❌ Error: paymentMethod.type might not be a key in paymentMethodToCurrency, causing TypeScript issues and potential runtime undefined access.

Better approach:

const currency = paymentMethodToCurrency[paymentMethod.type as keyof typeof paymentMethodToCurrency] || "usd";

3. Inconsistent Error Message (Low)

// Comment says "use the cached rate from Redis" but no Redis logic exists
if (!exchangeRate || exchangeRate <= 0) {
  throw new Error(`Failed to get exchange rate from Stripe for ${currency}.`);
}

4. Missing Edge Case Handling (Medium)

No validation that the currency conversion should actually happen:

if (["sepa_debit", "acss_debit"].includes(paymentMethod.type)) {

This hardcoded check could get out of sync with the currency mapping.

Better approach:

const currency = paymentMethodToCurrency[paymentMethod.type] || "usd";
if (currency !== "usd") {
  // Perform currency conversion
}

🎯 Severity Assessment

1. Critical: Unsafe property access → runtime crash
2. Medium: Type safety and edge case handling
3. Low: Misleading comments

The primary concern is the unsafe property access that could cause production failures if Stripe's API response format changes or doesn't include expected currencies.

✅ What's Actually Working Well

• Currency mapping is properly defined
• Mathematical conversion logic is correct
• Exchange rate validation (> 0) is implemented
• Proper rounding for currency values
• Error handling for missing/invalid rates

The core logic is sound, but needs defensive programming for API response handling.