Multi-Currency Refund API: How to Solve Cross-Border Refund Reconciliation

// Multi-Currency Refund Calculation Engine
interface OriginalTransaction {
  orderId: string;
  originalAmountUsd: number;
  customerCurrency: string;
  customerAmount: number;
  exchangeRate: number;
  rateTimestamp: string;
}

interface RefundResult {
  refundAmountCustomer: number;
  refundAmountUsd: number;
  rateUsed: number;
  rateSource: 'original' | 'current' | 'blended';
  fxAdjustment: number;
  fxAdjustmentPercent: number;
}

async function calculateRefund(
  transaction: OriginalTransaction,
  refundPercent: number,
  apiKey: string,
  policy: 'original' | 'current' | 'blended' = 'original'
): Promise<RefundResult> {
  // 1. Calculate base refund in customer currency
  const baseRefund = transaction.customerAmount * refundPercent;

  let rateUsed: number;
  let rateSource: RefundResult['rateSource'];

  if (policy === 'original') {
    // Refund at the rate the customer originally paid
    rateUsed = transaction.exchangeRate;
    rateSource = 'original';
  } else if (policy === 'current') {
    // Fetch live rate for current refund
    const response = await fetch(
      'https://currency-exchange.app/api/v1/convert',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': apiKey,
        },
        body: JSON.stringify({
          from: 'USD',
          to: transaction.customerCurrency,
          amount: transaction.originalAmountUsd * refundPercent,
        }),
      }
    );
    const data = await response.json();
    rateUsed = data.rate;
    rateSource = 'current';
  } else {
    // Blended: average of original and current rates
    const response = await fetch(
      'https://currency-exchange.app/api/v1/convert',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': apiKey,
        },
        body: JSON.stringify({
          from: 'USD',
          to: transaction.customerCurrency,
          amount: 1,
        }),
      }
    );
    const data = await response.json();
    rateUsed = (transaction.exchangeRate + data.rate) / 2;
    rateSource = 'blended';
  }

  const refundAmountUsd = baseRefund / rateUsed;
  const originalUsdRefund =
    transaction.originalAmountUsd * refundPercent;
  const fxAdjustment = refundAmountUsd - originalUsdRefund;
  const fxAdjustmentPercent =
    (fxAdjustment / originalUsdRefund) * 100;

  return {
    refundAmountCustomer: Math.round(baseRefund * 100) / 100,
    refundAmountUsd: Math.round(refundAmountUsd * 100) / 100,
    rateUsed: Math.round(rateUsed * 10000) / 10000,
    rateSource,
    fxAdjustment: Math.round(fxAdjustment * 100) / 100,
    fxAdjustmentPercent:
      Math.round(fxAdjustmentPercent * 100) / 100,
  };
}

# Refund Dispute Resolution with Historical Rates
import requests
from datetime import datetime, timedelta

class RefundDisputeResolver:
    """Resolve refund disputes using historical exchange rates."""

    BASE_URL = "https://currency-exchange.app/api/v1"

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.headers = {
            "Content-Type": "application/json",
            "x-api-key": api_key,
        }

    def get_rate_at_date(
        self, date: str, from_curr: str, to_curr: str
    ) -> float:
        """Fetch the historical rate for a specific date."""
        response = requests.post(
            f"{self.BASE_URL}/convert",
            headers=self.headers,
            json={
                "from": from_curr,
                "to": to_curr,
                "amount": 1,
                "date": date,  # Historical date
            },
        )
        response.raise_for_status()
        return response.json()["rate"]

    def resolve_dispute(
        self,
        original_purchase_date: str,
        refund_request_date: str,
        original_rate: float,
        claimed_refund_amount: float,
        customer_currency: str = "JPY",
        base_currency: str = "USD",
        original_amount_usd: float = 100,
    ) -> dict:
        """Build a dispute resolution report."""
        # Fetch independent rate records
        purchase_rate = self.get_rate_at_date(
            original_purchase_date, base_currency, customer_currency
        )
        refund_rate = self.get_rate_at_date(
            refund_request_date, base_currency, customer_currency
        )

        # Calculate what the refund should be under each policy
        refund_at_original = (
            original_amount_usd * original_rate
        )
        refund_at_purchase_rate = (
            original_amount_usd * purchase_rate
        )
        refund_at_current = (
            original_amount_usd * refund_rate
        )

        rate_drift = (
            (refund_rate - purchase_rate) / purchase_rate * 100
        )

        return {
            "dispute_id": f"DR-{datetime.now().strftime('%Y%m%d%H%M')}",
            "rate_at_purchase": round(purchase_rate, 4),
            "rate_at_refund": round(refund_rate, 4),
            "rate_drift_percent": round(rate_drift, 2),
            "original_rate_used": original_rate,
            "refund_at_original_rate": round(refund_at_original, 2),
            "refund_at_purchase_date_rate": round(
                refund_at_purchase_rate, 2
            ),
            "refund_at_current_rate": round(refund_at_current, 2),
            "claimed_amount": claimed_refund_amount,
            "recommendation": self._recommend(
                claimed_refund_amount, refund_at_original,
                rate_drift
            ),
            "audit_trail": [
                {"date": original_purchase_date,
                 "rate": purchase_rate, "source": "historical"},
                {"date": refund_request_date,
                 "rate": refund_rate, "source": "historical"},
            ],
        }

    def _recommend(
        self, claimed: float, expected: float, drift: float
    ) -> str:
        if abs(claimed - expected) / expected < 0.01:
            return "REFUND_CLAIMED_VALID"
        elif drift > 2.0:
            return "FAVOR_CUSTOMER_USE_CURRENT_RATE"
        else:
            return "USE_ORIGINAL_RATE_PER_POLICY"

// Partial Refund: Multi-Item Return Across Currencies
interface OrderLineItem {
  productId: string;
  priceUsd: number;
  priceCustomer: number;
  customerCurrency: string;
  exchangeRate: number;
  quantity: number;
}

interface PartialRefundItem {
  productId: string;
  quantityReturned: number;
}

async function calculatePartialRefund(
  orderItems: OrderLineItem[],
  returnItems: PartialRefundItem[],
  customerCurrency: string,
  apiKey: string
): Promise<{
  totalRefund: number;
  totalRefundUsd: number;
  itemBreakdown: Array<{
    productId: string;
    refundCustomer: number;
    refundUsd: number;
  }>;
}> {
  // Fetch current rate once for the entire refund
  const rateResponse = await fetch(
    'https://currency-exchange.app/api/v1/convert',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey,
      },
      body: JSON.stringify({
        from: 'USD',
        to: customerCurrency,
        amount: 1,
      }),
    }
  );
  const currentRateData = await rateResponse.json();
  const currentRate = currentRateData.rate;

  let totalRefund = 0;
  let totalRefundUsd = 0;
  const itemBreakdown: Array<{
    productId: string;
    refundCustomer: number;
    refundUsd: number;
  }> = [];

  for (const returnItem of returnItems) {
    const orderItem = orderItems.find(
      (i) => i.productId === returnItem.productId
    );
    if (!orderItem) continue;

    // Calculate proportional refund at original rate
    const unitPriceCustomer =
      orderItem.priceCustomer / orderItem.quantity;
    const unitPriceUsd =
      orderItem.priceUsd / orderItem.quantity;

    const refundCustomer =
      unitPriceCustomer * returnItem.quantityReturned;
    const refundUsd =
      unitPriceUsd * returnItem.quantityReturned;

    // Round in customer's favor (always round up)
    const roundedRefund =
      Math.ceil(refundCustomer * 100) / 100;

    totalRefund += roundedRefund;
    totalRefundUsd += refundUsd;

    itemBreakdown.push({
      productId: returnItem.productId,
      refundCustomer: roundedRefund,
      refundUsd,
    });
  }

  return { totalRefund, totalRefundUsd, itemBreakdown };
}

# Fetch current rate for refund calculation
curl -X POST https://currency-exchange.app/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"from": "USD", "to": "JPY", "amount": 100}'

# Response: {"rate": 149.42, "result": 14942.00}

# Verify historical rate for dispute resolution
curl -X POST https://currency-exchange.app/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"from": "USD", "to": "JPY", "amount": 1, "date": "2026-02-15"}'

# Response: {"rate": 151.38, "result": 151.38}