refunds nobody issued with reason expired_uncaptured_charge

"""Report Stripe refunds that Stripe wrote itself when an authorization expired.

Read only. A paginated GET over Refunds and one lookup per candidate charge, no
writes: give this a RESTRICTED key with read access to Refunds and Charges. The
repair is printed, never performed, because this script holds a credential to a
live payments account.
"""
import argparse
import logging
import os
import sys
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("stripe_expired_capture_refunds")

API = "https://api.stripe.com/v1"

# Set by Stripe when an uncaptured authorization runs out of time. It is the one
# reason value on the Refund object that nobody in your business can choose, and
# so the one that should never be counted in a customer-facing refund rate.
EXPIRED = "expired_uncaptured_charge"

# The reasons a person picks. Everything here is a real refund.
CUSTOMER_REASONS = ("requested_by_customer", "duplicate", "fraudulent")


def classify(refund, charge=None):
    """Sort one Refund into money a human gave back and money that fell off a card.

    Pure, so the whole rule set is readable here and testable without a network.

    `charge` is the Charge this refund belongs to, or None when it was not looked
    up. That distinction is deliberate: an expired refund confirmed against
    `captured == false` is evidence, and an unconfirmed one is a candidate, and
    collapsing the two is how a finding gets contradicted later.

    Returns (state, detail).
    """
    reason = refund.get("reason")

    if reason == EXPIRED:
        if charge is None:
            return ("expired-unverified",
                    "Stripe wrote this when the authorization expired, but the "
                    "charge was not fetched, so captured is unconfirmed")
        captured = charge.get("captured")
        if captured is False:
            return ("expired",
                    "the authorization expired uncaptured: nobody issued this "
                    "refund and no customer asked for it")
        return ("inconsistent",
                "reason says the authorization expired but the charge reports "
                "captured=%r: read the charge before counting this one" % (captured,))

    if reason in CUSTOMER_REASONS:
        return ("customer", "a real refund (%s), belongs in the refund rate" % reason)

    if reason is None:
        return ("unlabelled",
                "no reason recorded: issued through the API or the Dashboard "
                "without one, so it counts as a real refund until proven otherwise")

    return ("other", "unrecognised reason %r, left in the rate" % (reason,))


def get(session, path, **params):
    r = session.get(API + path, params=params, timeout=30)
    if r.status_code == 401:
        raise SystemExit("401 from Stripe: the key is wrong, or is for the other mode")
    r.raise_for_status()
    return r.json()


def page_refunds(session, since, limit):
    """Yield refunds created since a unix timestamp, newest first."""
    seen = 0
    params = {"limit": 100, "created[gte]": since}
    while True:
        page = get(session, "/refunds", **params)
        rows = page.get("data", [])
        for refund in rows:
            yield refund
            seen += 1
        if not page.get("has_more") or not rows or seen >= limit:
            break
        params["starting_after"] = rows[-1]["id"]


def add(bucket, currency, amount):
    bucket[currency] = bucket.get(currency, 0) + (amount or 0)


def money(bucket):
    if not bucket:
        return "nothing"
    return ", ".join("%.2f %s" % (v / 100.0, k.upper()) for k, v in sorted(bucket.items()))


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=90,
                    help="how far back to scan refunds (default 90)")
    ap.add_argument("--max-refunds", type=int, default=2000,
                    help="stop paginating after this many refunds")
    ap.add_argument("--verify-charges", action="store_true",
                    help="fetch each candidate charge to confirm captured is false")
    args = ap.parse_args()

    key = os.environ.get("STRIPE_API_KEY")
    if not key:
        log.error("set STRIPE_API_KEY (use a restricted, read-only key)")
        return 2

    s = requests.Session()
    s.headers.update({"Authorization": "Bearer " + key})

    since = int(time.time()) - args.days * 86400
    charges = {}

    states = {}
    all_money = {}
    expired_money = {}
    scanned = 0

    for refund in page_refunds(s, since, args.max_refunds):
        scanned += 1
        currency = refund.get("currency") or "???"
        add(all_money, currency, refund.get("amount"))

        charge = None
        if args.verify_charges and refund.get("reason") == EXPIRED:
            charge_id = refund.get("charge")
            if isinstance(charge_id, str):
                if charge_id not in charges:
                    charges[charge_id] = get(s, "/charges/" + charge_id)
                charge = charges[charge_id]

        state, detail = classify(refund, charge)
        states[state] = states.get(state, 0) + 1

        if state in ("expired", "expired-unverified"):
            add(expired_money, currency, refund.get("amount"))
            log.warning("%-18s %s  %s", state, refund.get("id", "?"), detail)
        elif state == "inconsistent":
            log.warning("%-18s %s  %s", state, refund.get("id", "?"), detail)

    if not scanned:
        log.info("no refunds in the last %d day(s)", args.days)
        return 0

    log.info("%d refund(s) in %d day(s): %s", scanned, args.days,
             ", ".join("%d %s" % (n, k) for k, n in sorted(states.items())))
    log.info("refunded in total: %s", money(all_money))

    if not expired_money:
        log.info("nothing refunded because an authorization expired")
        return 0

    log.warning("refunded because an authorization expired: %s", money(expired_money))
    for currency, amount in sorted(expired_money.items()):
        total = all_money.get(currency, 0)
        if total:
            log.warning("  %s: %.1f%% of everything refunded in this window",
                        currency.upper(), 100.0 * amount / total)
    log.warning("repair: exclude reason=%s from the customer-facing refund rate "
                "and report it as an operational number instead", EXPIRED)
    log.warning("repair: fix the capture pipeline; the real deadline is "
                "capture_before on the charge, not created plus seven days")
    log.warning("repair: subscribe to charge.refund.updated and alert when a "
                "refund arrives carrying this reason")
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report Stripe refunds that Stripe wrote itself when an authorization expired.
 *
 * Read only. A paginated GET over Refunds and one lookup per candidate charge,
 * no writes: give this a RESTRICTED key with read access to Refunds and Charges.
 * The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// Set by Stripe when an uncaptured authorization runs out of time. The one
// reason value on the Refund object nobody in your business can choose.
export const EXPIRED = 'expired_uncaptured_charge';

const CUSTOMER_REASONS = ['requested_by_customer', 'duplicate', 'fraudulent'];

/**
 * Sort one Refund into money a human gave back and money that fell off a card.
 * Pure. `charge` is the Charge it belongs to, or null when it was not fetched.
 */
export function classify(refund, charge = null) {
  const reason = refund.reason ?? null;

  if (reason === EXPIRED) {
    if (charge === null || charge === undefined) {
      return ['expired-unverified',
        'Stripe wrote this when the authorization expired, but the charge was ' +
        'not fetched, so captured is unconfirmed'];
    }
    if (charge.captured === false) {
      return ['expired',
        'the authorization expired uncaptured: nobody issued this refund and ' +
        'no customer asked for it'];
    }
    return ['inconsistent',
      `reason says the authorization expired but the charge reports ` +
      `captured=${JSON.stringify(charge.captured)}: read the charge before ` +
      'counting this one'];
  }

  if (CUSTOMER_REASONS.includes(reason)) {
    return ['customer', `a real refund (${reason}), belongs in the refund rate`];
  }

  if (reason === null) {
    return ['unlabelled',
      'no reason recorded: issued through the API or the Dashboard without one, ' +
      'so it counts as a real refund until proven otherwise'];
  }

  return ['other', `unrecognised reason ${JSON.stringify(reason)}, left in the rate`];
}

async function get(key, path, params = {}) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
  if (res.status === 401) {
    throw new Error('401 from Stripe: the key is wrong, or is for the other mode');
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

async function* pageRefunds(key, since, limit) {
  let seen = 0;
  const params = { limit: 100, 'created[gte]': since };
  for (;;) {
    const page = await get(key, '/refunds', params);
    const rows = page.data ?? [];
    for (const refund of rows) { yield refund; seen += 1; }
    if (!page.has_more || rows.length === 0 || seen >= limit) break;
    params.starting_after = rows[rows.length - 1].id;
  }
}

function add(bucket, currency, amount) {
  bucket.set(currency, (bucket.get(currency) ?? 0) + (amount ?? 0));
}

function money(bucket) {
  if (bucket.size === 0) return 'nothing';
  return [...bucket.entries()].sort()
    .map(([k, v]) => `${(v / 100).toFixed(2)} ${k.toUpperCase()}`).join(', ');
}

async function main() {
  const days = Number(process.argv[2] ?? 90);
  const verify = process.argv.includes('--verify-charges');

  const key = process.env.STRIPE_API_KEY;
  if (!key) {
    console.error('set STRIPE_API_KEY (use a restricted, read-only key)');
    process.exitCode = 2;
    return;
  }

  const since = Math.floor(Date.now() / 1000) - days * 86400;
  const charges = new Map();
  const states = new Map();
  const allMoney = new Map();
  const expiredMoney = new Map();
  let scanned = 0;

  for await (const refund of pageRefunds(key, since, 2000)) {
    scanned += 1;
    const currency = refund.currency ?? '???';
    add(allMoney, currency, refund.amount);

    let charge = null;
    if (verify && refund.reason === EXPIRED && typeof refund.charge === 'string') {
      if (!charges.has(refund.charge)) {
        charges.set(refund.charge, await get(key, `/charges/${refund.charge}`));
      }
      charge = charges.get(refund.charge);
    }

    const [state, detail] = classify(refund, charge);
    states.set(state, (states.get(state) ?? 0) + 1);

    if (state === 'expired' || state === 'expired-unverified') {
      add(expiredMoney, currency, refund.amount);
      console.warn(`${state.padEnd(18)} ${refund.id ?? '?'}  ${detail}`);
    } else if (state === 'inconsistent') {
      console.warn(`${state.padEnd(18)} ${refund.id ?? '?'}  ${detail}`);
    }
  }

  if (scanned === 0) {
    console.log(`no refunds in the last ${days} day(s)`);
    return;
  }

  const summary = [...states.entries()].sort().map(([k, n]) => `${n} ${k}`).join(', ');
  console.log(`${scanned} refund(s) in ${days} day(s): ${summary}`);
  console.log(`refunded in total: ${money(allMoney)}`);

  if (expiredMoney.size === 0) {
    console.log('nothing refunded because an authorization expired');
    return;
  }

  console.warn(`refunded because an authorization expired: ${money(expiredMoney)}`);
  for (const [currency, amount] of [...expiredMoney.entries()].sort()) {
    const total = allMoney.get(currency) ?? 0;
    if (total) {
      console.warn(`  ${currency.toUpperCase()}: ` +
        `${((100 * amount) / total).toFixed(1)}% of everything refunded in this window`);
    }
  }
  console.warn(`repair: exclude reason=${EXPIRED} from the customer-facing refund ` +
               'rate and report it as an operational number instead');
  console.warn('repair: fix the capture pipeline; the real deadline is ' +
               'capture_before on the charge, not created plus seven days');
  console.warn('repair: subscribe to charge.refund.updated and alert when a ' +
               'refund arrives carrying this reason');
  process.exitCode = 1;
}

// Only run when invoked directly, so importing this module from the test file
// does not fire main(), fail on the missing key, and set a non-zero exit code
// that fails the whole test run even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from stripe_expired_capture_refunds import classify


def refund(reason="requested_by_customer"):
    out = {"id": "re_1", "amount": 4900, "currency": "usd", "charge": "ch_1"}
    if reason is not None:
        out["reason"] = reason
    return out


def test_expired_reason_with_an_uncaptured_charge_is_confirmed():
    state, detail = classify(refund("expired_uncaptured_charge"), {"captured": False})
    assert state == "expired"
    assert "no customer asked" in detail


def test_expired_reason_without_the_charge_is_only_a_candidate():
    # The whole point: unverified is not the same finding as verified.
    state, detail = classify(refund("expired_uncaptured_charge"))
    assert state == "expired-unverified"
    assert "unconfirmed" in detail


def test_expired_reason_on_a_captured_charge_is_flagged_not_counted():
    state, detail = classify(refund("expired_uncaptured_charge"), {"captured": True})
    assert state == "inconsistent"
    assert "captured=True" in detail


def test_a_customer_refund_stays_in_the_rate():
    state, detail = classify(refund("requested_by_customer"), {"captured": True})
    assert state == "customer"
    assert "refund rate" in detail


def test_a_refund_with_no_reason_is_not_treated_as_expired():
    assert classify(refund(None))[0] == "unlabelled"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { classify } from './stripe-expired-capture-refunds.mjs';

function refund(reason = 'requested_by_customer') {
  const out = { id: 're_1', amount: 4900, currency: 'usd', charge: 'ch_1' };
  if (reason !== null) out.reason = reason;
  return out;
}

test('expired reason with an uncaptured charge is confirmed', () => {
  const [state, detail] = classify(refund('expired_uncaptured_charge'), { captured: false });
  assert.equal(state, 'expired');
  assert.match(detail, /no customer asked/);
});

test('expired reason without the charge is only a candidate', () => {
  const [state, detail] = classify(refund('expired_uncaptured_charge'));
  assert.equal(state, 'expired-unverified');
  assert.match(detail, /unconfirmed/);
});

test('expired reason on a captured charge is flagged, not counted', () => {
  const [state, detail] = classify(refund('expired_uncaptured_charge'), { captured: true });
  assert.equal(state, 'inconsistent');
  assert.match(detail, /captured=true/);
});

test('a customer refund stays in the rate', () => {
  const [state, detail] = classify(refund('requested_by_customer'), { captured: true });
  assert.equal(state, 'customer');
  assert.match(detail, /refund rate/);
});

test('a refund with no reason is not treated as expired', () => {
  assert.equal(classify(refund(null))[0], 'unlabelled');
});