PaymentMethods are created but never attached to a customer

"""Report Stripe PaymentMethods that were never attached to a Customer.

Read only. GETs only, no writes: give this a RESTRICTED key with read access to
PaymentMethods and PaymentIntents. 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_orphaned_payment_methods")

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

MIN_AGE_HOURS = 24    # younger than this is a checkout still in progress
WARN_RATIO = 0.25     # a quarter of cards discarded is a code path, not residue
HIGH_RATIO = 0.50


def verdict(orphans, attached, unsaved_intents, reuse_errors):
    """Classify the orphan population. Pure, so the ratios can be tested offline.

    orphans        unattached card PaymentMethods older than MIN_AGE_HOURS
    attached       card PaymentMethods with a customer set
    unsaved_intents PaymentIntents with a customer but no setup_future_usage
    reuse_errors   PaymentIntents that failed with payment_method_unexpected_state

    Returns (state, detail).
    """
    total = orphans + attached
    if reuse_errors:
        return ("burned",
                "%d PaymentIntent(s) failed with payment_method_unexpected_state: "
                "a consumed pm_ is already being charged a second time. %d orphan(s) "
                "on the account." % (reuse_errors, orphans))
    if not total:
        return ("clear",
                "no card PaymentMethods older than %d hours to judge" % MIN_AGE_HOURS)
    ratio = orphans / float(total)
    if ratio >= HIGH_RATIO:
        return ("leaking",
                "%d of %d card PaymentMethods (%.0f%%) were never attached. This is "
                "the current behaviour of the checkout, not old residue."
                % (orphans, total, ratio * 100))
    if unsaved_intents:
        return ("unsaved",
                "%d PaymentIntent(s) charged a known customer with setup_future_usage "
                "unset, so those cards were discarded after one use. %d orphan(s) so "
                "far." % (unsaved_intents, orphans))
    if ratio >= WARN_RATIO:
        return ("orphaned",
                "%d of %d card PaymentMethods (%.0f%%) have no customer. Reusing any "
                "of them will fail." % (orphans, total, ratio * 100))
    if orphans:
        return ("residue",
                "%d of %d card PaymentMethods have no customer. Small enough to be "
                "history rather than the live path." % (orphans, total))
    return ("clear", "every card PaymentMethod in the window is attached to a customer")


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_all(session, path, limit, **params):
    """Yield objects from a paginated list endpoint until `limit` is reached."""
    seen = 0
    while True:
        page = get(session, path, **params)
        data = page.get("data", [])
        for obj in data:
            yield obj
            seen += 1
        if not data or not page.get("has_more") or seen >= limit:
            return
        params["starting_after"] = data[-1]["id"]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-objects", type=int, default=2000,
                    help="stop paginating each list after this many objects")
    ap.add_argument("--min-age-hours", type=float, default=MIN_AGE_HOURS,
                    help="ignore unattached PaymentMethods younger than this")
    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})

    cutoff = time.time() - args.min_age_hours * 3600.0
    orphans = attached = 0
    sample = []
    for pm in page_all(s, "/payment_methods", args.max_objects, type="card", limit=100):
        if pm.get("customer"):
            attached += 1
        elif (pm.get("created") or 0) < cutoff:
            orphans += 1
            if len(sample) < 5:
                sample.append(pm.get("id"))

    unsaved = reuse_errors = 0
    for pi in page_all(s, "/payment_intents", args.max_objects, limit=100):
        if pi.get("customer") and not pi.get("setup_future_usage"):
            unsaved += 1
        err = pi.get("last_payment_error") or {}
        if err.get("code") == "payment_method_unexpected_state":
            reuse_errors += 1

    state, detail = verdict(orphans, attached, unsaved, reuse_errors)
    line = "%-9s %s" % (state, detail)
    if state == "clear":
        log.info(line)
        return 0

    log.warning(line)
    for pm_id in sample:
        log.warning("  orphan %s", pm_id)
    log.warning("  save the card as part of the payment rather than storing the id:")
    log.warning("  POST %s/payment_intents -d customer=cus_X "
                "-d setup_future_usage=off_session", API)
    log.warning("  to store a card without charging it:")
    log.warning("  POST %s/setup_intents -d customer=cus_X -d usage=off_session", API)
    return 1


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

/**
 * Report Stripe PaymentMethods that were never attached to a Customer.
 *
 * Read only. GETs only, no writes: give this a RESTRICTED key with read access
 * to PaymentMethods and PaymentIntents. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

export const MIN_AGE_HOURS = 24; // younger than this is a checkout in progress
const WARN_RATIO = 0.25;
const HIGH_RATIO = 0.50;

/**
 * Classify the orphan population. Pure, so the ratios can be tested offline.
 * Returns [state, detail].
 */
export function verdict(orphans, attached, unsavedIntents, reuseErrors) {
  const total = orphans + attached;
  if (reuseErrors) {
    return ['burned',
      `${reuseErrors} PaymentIntent(s) failed with payment_method_unexpected_state: ` +
      `a consumed pm_ is already being charged a second time. ${orphans} orphan(s) ` +
      'on the account.'];
  }
  if (!total) {
    return ['clear', `no card PaymentMethods older than ${MIN_AGE_HOURS} hours to judge`];
  }
  const ratio = orphans / total;
  const pct = (ratio * 100).toFixed(0);
  if (ratio >= HIGH_RATIO) {
    return ['leaking',
      `${orphans} of ${total} card PaymentMethods (${pct}%) were never attached. ` +
      'This is the current behaviour of the checkout, not old residue.'];
  }
  if (unsavedIntents) {
    return ['unsaved',
      `${unsavedIntents} PaymentIntent(s) charged a known customer with ` +
      `setup_future_usage unset, so those cards were discarded after one use. ` +
      `${orphans} orphan(s) so far.`];
  }
  if (ratio >= WARN_RATIO) {
    return ['orphaned',
      `${orphans} of ${total} card PaymentMethods (${pct}%) have no customer. ` +
      'Reusing any of them will fail.'];
  }
  if (orphans) {
    return ['residue',
      `${orphans} of ${total} card PaymentMethods have no customer. Small enough ` +
      'to be history rather than the live path.'];
  }
  return ['clear', 'every card PaymentMethod in the window is attached to a customer'];
}

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();
}

export async function pageAll(key, path, limit, params = {}) {
  const out = [];
  const q = { limit: 100, ...params };
  for (;;) {
    const page = await get(key, path, q);
    const data = page.data ?? [];
    out.push(...data);
    if (data.length === 0 || !page.has_more || out.length >= limit) return out;
    q.starting_after = data[data.length - 1].id;
  }
}

async function main() {
  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 cutoff = Date.now() / 1000 - MIN_AGE_HOURS * 3600;
  let orphans = 0;
  let attached = 0;
  const sample = [];
  for (const pm of await pageAll(key, '/payment_methods', 2000, { type: 'card' })) {
    if (pm.customer) attached += 1;
    else if ((pm.created ?? 0) < cutoff) {
      orphans += 1;
      if (sample.length < 5) sample.push(pm.id);
    }
  }

  let unsaved = 0;
  let reuseErrors = 0;
  for (const pi of await pageAll(key, '/payment_intents', 2000)) {
    if (pi.customer && !pi.setup_future_usage) unsaved += 1;
    if (pi.last_payment_error?.code === 'payment_method_unexpected_state') reuseErrors += 1;
  }

  const [state, detail] = verdict(orphans, attached, unsaved, reuseErrors);
  const line = `${state.padEnd(9)} ${detail}`;
  if (state === 'clear') { console.log(line); return; }

  console.warn(line);
  for (const id of sample) console.warn(`  orphan ${id}`);
  console.warn('  save the card as part of the payment rather than storing the id:');
  console.warn(`  POST ${API}/payment_intents -d customer=cus_X -d setup_future_usage=off_session`);
  console.warn('  to store a card without charging it:');
  console.warn(`  POST ${API}/setup_intents -d customer=cus_X -d usage=off_session`);
  process.exitCode = 1;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing key, and set a
// non-zero exit code that fails the whole test file 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_orphaned_payment_methods import verdict


def test_nothing_to_judge_is_clear():
    assert verdict(0, 0, 0, 0)[0] == "clear"


def test_all_attached_is_clear():
    state, detail = verdict(0, 40, 0, 0)
    assert state == "clear"
    assert "attached" in detail


def test_a_failed_reuse_outranks_every_hygiene_finding():
    # Small orphan count, tiny ratio, but a customer is failing at checkout now.
    state, detail = verdict(1, 999, 0, 3)
    assert state == "burned"
    assert "payment_method_unexpected_state" in detail


def test_half_the_cards_orphaned_is_the_live_path():
    state, detail = verdict(50, 50, 0, 0)
    assert state == "leaking"
    assert "50%" in detail


def test_the_warn_ratio_is_inclusive():
    # 24% is residue, 25% is a code path. Off by one on this boundary reports
    # an active leak as history.
    assert verdict(2, 8, 0, 0)[0] == "residue"
    assert verdict(25, 75, 0, 0)[0] == "orphaned"


def test_unsaved_intents_are_named_even_with_few_orphans():
    state, detail = verdict(3, 97, 12, 0)
    assert state == "unsaved"
    assert "setup_future_usage" in detail

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-orphaned-payment-methods.mjs';

test('nothing to judge is clear', () => {
  assert.equal(verdict(0, 0, 0, 0)[0], 'clear');
});

test('all attached is clear', () => {
  const [state, detail] = verdict(0, 40, 0, 0);
  assert.equal(state, 'clear');
  assert.match(detail, /attached/);
});

test('a failed reuse outranks every hygiene finding', () => {
  const [state, detail] = verdict(1, 999, 0, 3);
  assert.equal(state, 'burned');
  assert.match(detail, /payment_method_unexpected_state/);
});

test('half the cards orphaned is the live path', () => {
  const [state, detail] = verdict(50, 50, 0, 0);
  assert.equal(state, 'leaking');
  assert.match(detail, /50%/);
});

test('the warn ratio is inclusive', () => {
  assert.equal(verdict(2, 8, 0, 0)[0], 'residue');
  assert.equal(verdict(25, 75, 0, 0)[0], 'orphaned');
});

test('unsaved intents are named even with few orphans', () => {
  const [state, detail] = verdict(3, 97, 12, 0);
  assert.equal(state, 'unsaved');
  assert.match(detail, /setup_future_usage/);
});