Stripe Payout Reconciliation: Matching Deposits to Orders

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function reconcilePayout(payoutId: string) {
  const lines = [];

  for await (const txn of stripe.balanceTransactions.list({
    payout: payoutId,
    expand: ["data.source"],
    limit: 100,
  })) {
    const source = txn.source as any;

    switch (txn.type) {
      case "charge":
      case "payment": {
        // Your join: PaymentIntent ID to your orders table.
        const order = await db.orders.findByPaymentIntent(source.payment_intent);
        lines.push({ order, gross: txn.amount, fee: txn.fee, net: txn.net });
        break;
      }
      case "payment_refund":
      case "refund": {
        // Which line items, and how much tax? Only your refunds table knows,
        // and only for refunds your code wrote down.
        const refund = await db.refunds.findByStripeId(source.id);
        const order = await db.orders.findByPaymentIntent(source.payment_intent);
        lines.push({ order, refund, net: txn.net });
        break;
      }
      case "refund_failure": {
        // The refund failed and the money came back. Your refunds table
        // still says refunded unless a webhook handler caught the failure.
        const refund = await db.refunds.findByStripeId(source.id);
        lines.push({ refund, net: txn.net });
        break;
      }
      case "adjustment": {
        // Disputes, dispute reversals, and corrections all arrive here.
        if (source?.object === "dispute") {
          const order = await db.orders.findByPaymentIntent(source.payment_intent);
          lines.push({ order, dispute: source.id, net: txn.net });
        } else {
          lines.push({ unmatched: txn.description, net: txn.net });
        }
        break;
      }
      default:
        // stripe_fee, tax_fee, and the rest belong to no order.
        lines.push({ unmatched: txn.type, net: txn.net });
    }
  }

  return lines;
}

const FLINT = "https://api.withflintpay.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.FLINT_API_KEY}`,
  "Flint-Version": "2026-09-07",
};
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function reconcilePayout(payoutId) {
  const payout = (await (await fetch(`${FLINT}/payouts/${payoutId}`, { headers })).json()).data;

  const rows = [];
  let pageToken;
  for (;;) {
    const url = new URL(`${FLINT}/balance-transactions`);
    url.searchParams.set("payout_id", payoutId);
    url.searchParams.set("expand", "order");
    url.searchParams.set("page_size", "100");
    if (pageToken) url.searchParams.set("page_token", pageToken);

    const res = await fetch(url, { headers });
    if (res.status === 503) {
      // Contents aren't prepared yet. This is not an empty payout.
      await sleep(Number(res.headers.get("Retry-After") ?? 60) * 1000);
      continue;
    }
    if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);

    const page = await res.json();
    rows.push(...page.data);
    if (!page.next_page_token) break;
    pageToken = page.next_page_token;
  }

  const byType = {};
  for (const row of rows) {
    byType[row.type] = (byType[row.type] ?? 0) + row.net_money.amount;
  }
  const net = rows.reduce((sum, row) => sum + row.net_money.amount, 0);
  if (net !== payout.amount_money.amount) {
    throw new Error(`Payout ${payoutId} doesn't tie out: ${net} vs ${payout.amount_money.amount}`);
  }
  return { byType, rows };
}

{
  "data": [
    {
      "balance_transaction_id": "btxn_1kmn0aExample",
      "type": "payment",
      "amount_money": {"amount": 5000, "currency": "USD"},
      "fee_money": {"amount": 225, "currency": "USD"},
      "net_money": {"amount": 4775, "currency": "USD"},
      "order_id": "ord_1kmn0aExample",
      "payout_id": "po_1kmn0aExample",
      "related_resource": {"resource_type": "payment_intent", "resource_id": "pi_1kmn0aExample"},
      "order": {
        "order_id": "ord_1kmn0aExample",
        "payment_status": "paid",
        "refund_status": "none",
        "settlement_amounts": {
          "paid_money": {"amount": 5000, "currency": "USD"},
          "refunded_money": {"amount": 0, "currency": "USD"},
          "outstanding_money": {"amount": 0, "currency": "USD"}
        }
      }
    },
    {
      "balance_transaction_id": "btxn_1kmn0bExample",
      "type": "refund",
      "amount_money": {"amount": -1299, "currency": "USD"},
      "fee_money": {"amount": 0, "currency": "USD"},
      "net_money": {"amount": -1299, "currency": "USD"},
      "order_id": "ord_1kmn0bExample",
      "payout_id": "po_1kmn0aExample",
      "related_resource": {"resource_type": "refund", "resource_id": "ref_1kmn0aExample"},
      "order": {
        "order_id": "ord_1kmn0bExample",
        "payment_status": "paid",
        "refund_status": "partially_refunded",
        "settlement_amounts": {
          "paid_money": {"amount": 3098, "currency": "USD"},
          "refunded_money": {"amount": 1299, "currency": "USD"},
          "outstanding_money": {"amount": 0, "currency": "USD"}
        }
      }
    }
  ],
  "next_page_token": "pt_1kmn0aExample"
}

// After refunding part of one line, in your refund handler.
await stripe.tax.transactions.createReversal({
  mode: "partial",
  original_transaction: order.stripeTaxTransactionId,
  reference: `${order.id}-refund-${refund.id}`,
  line_items: [
    {
      original_line_item: line.stripeTaxLineItemId,
      reference: line.id,
      amount: -refundedAmount,
      amount_tax: -refundedTax, // your code computes this share
    },
  ],
});

curl -X POST https://api.withflintpay.com/v1/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-ord-1042-mug" \
  -d '{
    "refund_type": "targets",
    "order_id": "ord_1kmn0bExample",
    "reason": "defective_product",
    "line_items": [
      {"order_line_item_id": "li_1kmn0aExample", "quantity": 1}
    ]
  }'

{
  "line_item_allocations": [
    {
      "order_line_item_id": "li_1kmn0aExample",
      "quantity": 1,
      "refunded_money": {"amount": 1299, "currency": "USD"},
      "tax_refund_mode": "automatic",
      "automatic_refund": {
        "subtotal_money": {"amount": 1200, "currency": "USD"},
        "discount_money": {"amount": 0, "currency": "USD"},
        "tax_money": {"amount": 99, "currency": "USD"},
        "total_money": {"amount": 1299, "currency": "USD"}
      }
    }
  ]
}