paymentIntents sit in requires_payment_method for weeks

"""Report Stripe PaymentIntents that were created and never confirmed.

Read only. One paginated GET, no writes: give this a RESTRICTED key with read
access to 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_stale_intents")

API = "https://api.stripe.com/v1"
STALE_SECONDS = 7 * 86400
OPEN_STATUSES = ("requires_payment_method", "requires_confirmation")


def classify(intent, now, stale_after=STALE_SECONDS):
    """Classify one PaymentIntent. Pure, so the rules can be tested without a network.

    Returns (state, detail). The split that matters is `last_payment_error`:
    null means nothing was ever attempted, populated means the customer tried and
    was declined. The two look identical in a status count and need opposite fixes.
    """
    status = intent.get("status")
    if status not in OPEN_STATUSES:
        return ("other", "status %r, not an open intent" % (status,))
    created = intent.get("created")
    if not isinstance(created, int):
        return ("unknown", "no created timestamp, so the intent cannot be aged")
    days = int((now - created) // 86400)
    if now - created < stale_after:
        return ("recent", "%s, %dd old, still plausibly live" % (status, days))
    if status == "requires_confirmation":
        return ("unconfirmed",
                "%dd old: confirmation_method is manual and the server never "
                "called confirm" % days)
    err = intent.get("last_payment_error") or {}
    if err:
        reason = err.get("decline_code") or err.get("code") or "no code given"
        return ("declined",
                "%dd old: last attempt was declined (%s) and nothing offered a retry"
                % (days, reason))
    return ("never-attempted",
            "%dd old: created but no payment method was ever attached" % days)


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 payment_intents(session, since, until, cap):
    """Yield PaymentIntents created in [since, until), up to `cap` of them."""
    seen = 0
    params = {"limit": 100, "created[gte]": since, "created[lt]": until}
    while True:
        page = get(session, "/payment_intents", **params)
        data = page.get("data", [])
        for pi in data:
            yield pi
            seen += 1
            if seen >= cap:
                return
        if not page.get("has_more") or not data:
            return
        params["starting_after"] = data[-1]["id"]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=30,
                    help="how far back to scan (default 30)")
    ap.add_argument("--stale-days", type=int, default=7,
                    help="age at which an open intent counts as stale")
    ap.add_argument("--max-intents", type=int, default=5000,
                    help="stop paginating after this many intents")
    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})

    now = int(time.time())
    stale_after = args.stale_days * 86400
    since = now - args.days * 86400
    until = now - stale_after  # only intents old enough to have a verdict

    counts = {}
    codes = {}
    examples = []
    scanned = 0

    for pi in payment_intents(s, since, until, args.max_intents):
        scanned += 1
        state, detail = classify(pi, now, stale_after)
        counts[state] = counts.get(state, 0) + 1
        if state == "declined":
            err = pi.get("last_payment_error") or {}
            code = err.get("decline_code") or err.get("code") or "unknown"
            codes[code] = codes.get(code, 0) + 1
        if state in ("never-attempted", "declined", "unconfirmed") and len(examples) < 10:
            examples.append((pi["id"], detail))

    never = counts.get("never-attempted", 0)
    declined = counts.get("declined", 0)
    unconfirmed = counts.get("unconfirmed", 0)
    stale = never + declined + unconfirmed

    for pid, detail in examples:
        log.warning("%s  %s", pid, detail)

    share = (100.0 * stale / scanned) if scanned else 0.0
    log.info("%d intent(s) older than %dd: %d stale (%.0f%%) - "
             "%d never-attempted, %d declined, %d unconfirmed",
             scanned, args.stale_days, stale, share, never, declined, unconfirmed)

    for code, n in sorted(codes.items(), key=lambda kv: -kv[1]):
        log.warning("  decline %-28s %d", code, n)

    if share > 30:
        log.warning("  over 30%% of intents in this window never went anywhere")
    if never:
        log.warning("  repair: create the PaymentIntent when the customer submits, "
                    "not when the payment page renders")
    if declined:
        log.warning("  repair: retry on the same intent and show "
                    "last_payment_error.message rather than a generic failure")
    if unconfirmed:
        log.warning("  repair: find the job that owes Stripe "
                    "POST %s/payment_intents/{id}/confirm and fix it", API)
    if stale:
        log.warning("  to clear the backlog: POST %s/payment_intents/{id}/cancel "
                    "-d cancellation_reason=abandoned", API)
        return 1
    return 0


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

/**
 * Report Stripe PaymentIntents that were created and never confirmed.
 *
 * Read only. One paginated GET, no writes: give this a RESTRICTED key with read
 * access to PaymentIntents. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';
const STALE_SECONDS = 7 * 86400;
const OPEN_STATUSES = ['requires_payment_method', 'requires_confirmation'];

/**
 * Classify one PaymentIntent. Pure, so the rules can be tested without a network.
 * The split that matters is last_payment_error: null means nothing was ever
 * attempted, populated means the customer tried and was declined. The two look
 * identical in a status count and need opposite fixes.
 */
export function classify(intent, now, staleAfter = STALE_SECONDS) {
  const status = intent.status;
  if (!OPEN_STATUSES.includes(status)) {
    return ['other', `status ${JSON.stringify(status)}, not an open intent`];
  }
  const created = intent.created;
  if (!Number.isInteger(created)) {
    return ['unknown', 'no created timestamp, so the intent cannot be aged'];
  }
  const days = Math.floor((now - created) / 86400);
  if (now - created < staleAfter) {
    return ['recent', `${status}, ${days}d old, still plausibly live`];
  }
  if (status === 'requires_confirmation') {
    return ['unconfirmed',
      `${days}d old: confirmation_method is manual and the server never called confirm`];
  }
  const err = intent.last_payment_error;
  if (err) {
    const reason = err.decline_code ?? err.code ?? 'no code given';
    return ['declined',
      `${days}d old: last attempt was declined (${reason}) and nothing offered a retry`];
  }
  return ['never-attempted',
    `${days}d old: created but no payment method was ever attached`];
}

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* paymentIntents(key, since, until, cap) {
  let seen = 0;
  const params = { limit: 100, 'created[gte]': since, 'created[lt]': until };
  for (;;) {
    const page = await get(key, '/payment_intents', params);
    const data = page.data ?? [];
    for (const pi of data) {
      yield pi;
      seen += 1;
      if (seen >= cap) return;
    }
    if (!page.has_more || data.length === 0) return;
    params.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 days = Number(process.env.DAYS ?? 30);
  const staleDays = Number(process.env.STALE_DAYS ?? 7);
  const staleAfter = staleDays * 86400;
  const now = Math.floor(Date.now() / 1000);
  const since = now - days * 86400;
  const until = now - staleAfter; // only intents old enough to have a verdict

  const counts = new Map();
  const codes = new Map();
  const examples = [];
  let scanned = 0;

  for await (const pi of paymentIntents(key, since, until, 5000)) {
    scanned += 1;
    const [state, detail] = classify(pi, now, staleAfter);
    counts.set(state, (counts.get(state) ?? 0) + 1);
    if (state === 'declined') {
      const err = pi.last_payment_error ?? {};
      const code = err.decline_code ?? err.code ?? 'unknown';
      codes.set(code, (codes.get(code) ?? 0) + 1);
    }
    if (['never-attempted', 'declined', 'unconfirmed'].includes(state) && examples.length < 10) {
      examples.push([pi.id, detail]);
    }
  }

  const never = counts.get('never-attempted') ?? 0;
  const declined = counts.get('declined') ?? 0;
  const unconfirmed = counts.get('unconfirmed') ?? 0;
  const stale = never + declined + unconfirmed;

  for (const [id, detail] of examples) console.warn(`${id}  ${detail}`);

  const share = scanned ? Math.round((100 * stale) / scanned) : 0;
  console.log(`${scanned} intent(s) older than ${staleDays}d: ${stale} stale (${share}%) - ` +
              `${never} never-attempted, ${declined} declined, ${unconfirmed} unconfirmed`);

  for (const [code, n] of [...codes].sort((a, b) => b[1] - a[1])) {
    console.warn(`  decline ${code.padEnd(28)} ${n}`);
  }

  if (share > 30) console.warn('  over 30% of intents in this window never went anywhere');
  if (never) {
    console.warn('  repair: create the PaymentIntent when the customer submits, ' +
                 'not when the payment page renders');
  }
  if (declined) {
    console.warn('  repair: retry on the same intent and show ' +
                 'last_payment_error.message rather than a generic failure');
  }
  if (unconfirmed) {
    console.warn(`  repair: find the job that owes Stripe POST ${API}` +
                 '/payment_intents/{id}/confirm and fix it');
  }
  if (stale) {
    console.warn(`  to clear the backlog: POST ${API}/payment_intents/{id}/cancel ` +
                 '-d cancellation_reason=abandoned');
    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_stale_intents import classify

NOW = 1_800_000_000
DAY = 86400


def pi(status="requires_payment_method", age_d=30, err=None):
    out = {"status": status, "created": NOW - age_d * DAY}
    if err is not None:
        out["last_payment_error"] = err
    return out


def test_old_intent_with_no_error_was_never_attempted():
    state, detail = classify(pi(age_d=30), NOW)
    assert state == "never-attempted"
    assert "no payment method" in detail


def test_old_intent_with_an_error_is_a_missing_retry():
    # Same status, opposite fix: this customer tried and was turned down.
    state, detail = classify(pi(age_d=30, err={"decline_code": "insufficient_funds"}), NOW)
    assert state == "declined"
    assert "insufficient_funds" in detail


def test_requires_confirmation_is_the_servers_omission():
    state, detail = classify(pi(status="requires_confirmation", age_d=30), NOW)
    assert state == "unconfirmed"
    assert "confirm" in detail


def test_a_two_day_old_intent_is_still_live():
    assert classify(pi(age_d=2), NOW)[0] == "recent"


def test_succeeded_intents_are_not_counted():
    assert classify(pi(status="succeeded"), NOW)[0] == "other"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { classify } from './stripe-stale-intents.mjs';

const NOW = 1800000000;
const DAY = 86400;

function pi({ status = 'requires_payment_method', ageD = 30, err = null } = {}) {
  const out = { status, created: NOW - ageD * DAY };
  if (err !== null) out.last_payment_error = err;
  return out;
}

test('old intent with no error was never attempted', () => {
  const [state, detail] = classify(pi({ ageD: 30 }), NOW);
  assert.equal(state, 'never-attempted');
  assert.match(detail, /no payment method/);
});

test('old intent with an error is a missing retry', () => {
  const [state, detail] = classify(
    pi({ ageD: 30, err: { decline_code: 'insufficient_funds' } }), NOW);
  assert.equal(state, 'declined');
  assert.match(detail, /insufficient_funds/);
});

test('requires_confirmation is the server omission', () => {
  const [state, detail] = classify(pi({ status: 'requires_confirmation', ageD: 30 }), NOW);
  assert.equal(state, 'unconfirmed');
  assert.match(detail, /confirm/);
});

test('a two day old intent is still live', () => {
  assert.equal(classify(pi({ ageD: 2 }), NOW)[0], 'recent');
});

test('succeeded intents are not counted', () => {
  assert.equal(classify(pi({ status: 'succeeded' }), NOW)[0], 'other');
});