Payment Settlement FX Reconciliation in 2026: Rate Timestamps, Historical Replays, and Exception Queues

Source Files and Failure Points

Step-by-Step Workflow

API Examples

curl "https://api.currency-exchange.app/v1-convert-currency?from=EUR&to=USD&amount=1240.50&date=2026-05-15" \
  -H "x-api-key: YOUR_API_KEY"

curl -i "https://api.currency-exchange.app/v1-get-currency-exchange-rate?from=EUR&to=USD&date=2026-05-15&skipCache=true" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api.currency-exchange.app/v1-list-currencies?code=EUR&code=USD&code=JPY&active=true&pageSize=50" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api.currency-exchange.app/v1-download-api-usage?from=2026-05-01&to=2026-05-31&service=currency&format=csv" \
  -H "x-api-key: YOUR_API_KEY"

TypeScript Reconciliation Function

type SettlementRow = {
  paymentId: string;
  settlementId: string;
  sourceAmount: number;
  sourceCurrency: string;
  settlementAmount: number;
  settlementCurrency: string;
  policyDate: string;
  processorFee?: number;
};

type FxEvidence = {
  paymentId: string;
  policyDate: string;
  exchangeRate: number;
  expectedSettlementAmount: number;
  varianceAmount: number;
  rateTime: string;
  provider?: string;
  cached?: boolean;
  rateLimitRemaining: string | null;
  status: 'approved' | 'review';
};

function roundMoney(value: number) {
  return Math.round(value * 100) / 100;
}

export async function reconcileSettlementRow(row: SettlementRow): Promise<FxEvidence> {
  const url = new URL('https://api.currency-exchange.app/v1-convert-currency');
  url.searchParams.set('from', row.sourceCurrency);
  url.searchParams.set('to', row.settlementCurrency);
  url.searchParams.set('amount', String(row.sourceAmount));
  url.searchParams.set('date', row.policyDate);

  const response = await fetch(url, {
    headers: { 'x-api-key': process.env.FX_API_KEY ?? '' },
  });

  if (!response.ok) {
    throw new Error(`FX replay failed for payment ${row.paymentId}: ${response.status}`);
  }

  const data = (await response.json()) as {
    exchangeRate: number;
    convertedAmount: number;
    rateTime: string;
    provider?: string;
    cached?: boolean;
  };

  const expectedSettlementAmount = roundMoney(data.convertedAmount - (row.processorFee ?? 0));
  const varianceAmount = roundMoney(row.settlementAmount - expectedSettlementAmount);
  const status = Math.abs(varianceAmount) <= 1 ? 'approved' : 'review';

  return {
    paymentId: row.paymentId,
    policyDate: row.policyDate,
    exchangeRate: data.exchangeRate,
    expectedSettlementAmount,
    varianceAmount,
    rateTime: data.rateTime,
    provider: data.provider,
    cached: data.cached,
    rateLimitRemaining: response.headers.get('X-RateLimit-Remaining'),
    status,
  };
}

The tolerance in this example is illustrative, not a recommendation. Finance should set tolerances by currency, processor, contract, and materiality. Some workflows need exact review; others accept rounding variance. The important part is that every approved or reviewed row carries the rate evidence.

Spreadsheet Review Queue

Spreadsheets are still useful when they are the review surface, not the source of truth for manual rates. A script, warehouse job, or no-code step can call the API, write evidence columns, and let finance approve exception rows.

payment_id,settlement_id,source_amount,source_currency,settlement_amount,settlement_currency,policy_date,exchange_rate,rate_time,expected_amount,variance,status,reviewer,override_reason

That structure works for Google Sheets, Excel, CSV exports, BI staging tables, and ERP imports. Keep the workflow honest: if the integration is a script or middleware job, call it that. Do not market it internally as a native connector.

Exception Matrix

Where the Workflow Runs

Choose the Date Policy Before You Automate

Historical exchange-rate access is useful only when the date rule is explicit. Finance, support, product, and engineering should agree on the policy before a worker starts filling cells or writing warehouse rows. The API can replay a date; it cannot decide which business event should govern the settlement explanation.

FAQ