SetupIntents are created but never confirmed by the client

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

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

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

STUCK_STATUSES = ("requires_payment_method", "requires_confirmation", "requires_action")
BROKEN_RATIO = 0.20   # above this, it is the confirm path rather than abandonment
MIN_AGE_HOURS = 24    # younger than this is a customer still typing


def verdict(total, requires_payment_method, requires_confirmation, requires_action):
    """Classify a window of SetupIntents. Pure, so it can be tested offline.

    Ties are broken in a fixed order rather than by whichever bucket a dict
    happened to yield first: requires_action wins, then requires_confirmation.
    Both are specific code defects, while requires_payment_method is the bucket
    ordinary abandonment also lands in, so it is the least informative of the
    three and should never win a tie.

    Returns (state, detail).
    """
    stuck = requires_payment_method + requires_confirmation + requires_action
    if not total:
        return ("clear", "no SetupIntents created in the window")
    if not stuck:
        return ("clear", "all %d SetupIntent(s) in the window resolved" % total)
    ratio = stuck / float(total)
    pct = ratio * 100
    if ratio < BROKEN_RATIO:
        return ("abandonment",
                "%d of %d SetupIntents (%.0f%%) are stuck, under the %.0f%% that "
                "separates a broken confirm path from ordinary drop-off"
                % (stuck, total, pct, BROKEN_RATIO * 100))
    if requires_action >= requires_confirmation and requires_action >= requires_payment_method:
        return ("return-url",
                "%d of %d (%.0f%%) stuck, mostly at requires_action: the 3DS handoff "
                "starts and never comes back. Check next_action.type and the "
                "return_url landing page." % (stuck, total, pct))
    if requires_confirmation >= requires_payment_method:
        return ("unconfirmed",
                "%d of %d (%.0f%%) stuck, mostly at requires_confirmation: "
                "confirmSetup() is never being called for these."
                % (stuck, total, pct))
    return ("no-payment-method",
            "%d of %d (%.0f%%) stuck at requires_payment_method, above the "
            "abandonment threshold: read last_setup_error.code before blaming "
            "the customers." % (stuck, total, pct))


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-intents", type=int, default=2000,
                    help="stop paginating after this many SetupIntents")
    ap.add_argument("--min-age-hours", type=float, default=MIN_AGE_HOURS,
                    help="ignore SetupIntents 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 = int(time.time() - args.min_age_hours * 3600)
    buckets = dict.fromkeys(STUCK_STATUSES, 0)
    errors = {}
    next_actions = {}
    total = 0
    params = {"limit": 100, "created[lt]": cutoff}
    for si in page_all(s, "/setup_intents", args.max_intents, **params):
        total += 1
        status = si.get("status")
        if status not in buckets:
            continue
        buckets[status] += 1
        err = (si.get("last_setup_error") or {}).get("code")
        if err:
            errors[err] = errors.get(err, 0) + 1
        action = (si.get("next_action") or {}).get("type")
        if action:
            next_actions[action] = next_actions.get(action, 0) + 1

    state, detail = verdict(total, buckets["requires_payment_method"],
                            buckets["requires_confirmation"],
                            buckets["requires_action"])
    line = "%-18s %s" % (state, detail)
    if state == "clear":
        log.info(line)
        return 0

    log.warning(line)
    for status in STUCK_STATUSES:
        log.warning("  %-24s %d", status, buckets[status])
    for code, count in sorted(errors.items(), key=lambda kv: -kv[1]):
        log.warning("  last_setup_error %-20s %d", code, count)
    for action, count in sorted(next_actions.items(), key=lambda kv: -kv[1]):
        log.warning("  next_action %-25s %d", action, count)
    log.warning("  confirm on the client and treat only 'succeeded' as success:")
    log.warning("  await stripe.confirmSetup({elements, confirmParams: {return_url}})")
    log.warning("  persist from the setup_intent.succeeded webhook, not the browser")
    log.warning("  clear the backlog: POST %s/setup_intents/{id}/cancel "
                "-d cancellation_reason=abandoned", API)
    return 1


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

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

export const STUCK_STATUSES = [
  'requires_payment_method', 'requires_confirmation', 'requires_action',
];
const BROKEN_RATIO = 0.20; // above this it is the confirm path, not abandonment
const MIN_AGE_HOURS = 24;  // younger than this is a customer still typing

/**
 * Classify a window of SetupIntents. Pure, so it can be tested offline.
 *
 * Ties are broken in a fixed order rather than by whichever bucket an object
 * happened to yield first: requiresAction wins, then requiresConfirmation. Both
 * are specific code defects, while requiresPaymentMethod is the bucket ordinary
 * abandonment also lands in, so it should never win a tie.
 */
export function verdict(total, requiresPaymentMethod, requiresConfirmation, requiresAction) {
  const stuck = requiresPaymentMethod + requiresConfirmation + requiresAction;
  if (!total) return ['clear', 'no SetupIntents created in the window'];
  if (!stuck) return ['clear', `all ${total} SetupIntent(s) in the window resolved`];
  const ratio = stuck / total;
  const pct = (ratio * 100).toFixed(0);
  if (ratio < BROKEN_RATIO) {
    return ['abandonment',
      `${stuck} of ${total} SetupIntents (${pct}%) are stuck, under the ` +
      `${(BROKEN_RATIO * 100).toFixed(0)}% that separates a broken confirm path ` +
      'from ordinary drop-off'];
  }
  if (requiresAction >= requiresConfirmation && requiresAction >= requiresPaymentMethod) {
    return ['return-url',
      `${stuck} of ${total} (${pct}%) stuck, mostly at requires_action: the 3DS ` +
      'handoff starts and never comes back. Check next_action.type and the ' +
      'return_url landing page.'];
  }
  if (requiresConfirmation >= requiresPaymentMethod) {
    return ['unconfirmed',
      `${stuck} of ${total} (${pct}%) stuck, mostly at requires_confirmation: ` +
      'confirmSetup() is never being called for these.'];
  }
  return ['no-payment-method',
    `${stuck} of ${total} (${pct}%) stuck at requires_payment_method, above the ` +
    'abandonment threshold: read last_setup_error.code before blaming the customers.'];
}

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 = Math.floor(Date.now() / 1000 - MIN_AGE_HOURS * 3600);
  const buckets = Object.fromEntries(STUCK_STATUSES.map((s) => [s, 0]));
  const errors = new Map();
  const nextActions = new Map();
  let total = 0;

  for (const si of await pageAll(key, '/setup_intents', 2000, { 'created[lt]': cutoff })) {
    total += 1;
    if (!(si.status in buckets)) continue;
    buckets[si.status] += 1;
    const err = si.last_setup_error?.code;
    if (err) errors.set(err, (errors.get(err) ?? 0) + 1);
    const action = si.next_action?.type;
    if (action) nextActions.set(action, (nextActions.get(action) ?? 0) + 1);
  }

  const [state, detail] = verdict(total, buckets.requires_payment_method,
    buckets.requires_confirmation, buckets.requires_action);
  const line = `${state.padEnd(18)} ${detail}`;
  if (state === 'clear') { console.log(line); return; }

  console.warn(line);
  for (const status of STUCK_STATUSES) {
    console.warn(`  ${status.padEnd(24)} ${buckets[status]}`);
  }
  for (const [code, count] of [...errors].sort((a, b) => b[1] - a[1])) {
    console.warn(`  last_setup_error ${code.padEnd(20)} ${count}`);
  }
  for (const [action, count] of [...nextActions].sort((a, b) => b[1] - a[1])) {
    console.warn(`  next_action ${action.padEnd(25)} ${count}`);
  }
  console.warn("  confirm on the client and treat only 'succeeded' as success:");
  console.warn('  await stripe.confirmSetup({elements, confirmParams: {return_url}})');
  console.warn('  persist from the setup_intent.succeeded webhook, not the browser');
  console.warn(`  clear the backlog: POST ${API}/setup_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_setup_intents_stuck import verdict


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


def test_everything_resolved_is_clear():
    state, detail = verdict(312, 0, 0, 0)
    assert state == "clear"
    assert "312" in detail


def test_nineteen_percent_is_ordinary_drop_off():
    assert verdict(100, 19, 0, 0)[0] == "abandonment"


def test_twenty_percent_is_a_broken_path():
    # The boundary is inclusive. One percentage point either side is the
    # difference between a report nobody acts on and one that names the bug.
    state, detail = verdict(100, 20, 0, 0)
    assert state == "no-payment-method"
    assert "last_setup_error" in detail


def test_a_pile_at_requires_confirmation_names_the_client():
    state, detail = verdict(100, 5, 40, 2)
    assert state == "unconfirmed"
    assert "confirmSetup" in detail


def test_requires_action_points_at_the_return_url():
    state, detail = verdict(100, 5, 10, 40)
    assert state == "return-url"
    assert "return_url" in detail


def test_a_tie_is_broken_deterministically():
    # Level buckets must not depend on iteration order: requires_action first,
    # then requires_confirmation.
    assert verdict(100, 20, 20, 20)[0] == "return-url"
    assert verdict(100, 20, 20, 0)[0] == "unconfirmed"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-setup-intents-stuck.mjs';

test('an empty window is clear', () => {
  assert.equal(verdict(0, 0, 0, 0)[0], 'clear');
});

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

test('nineteen percent is ordinary drop off', () => {
  assert.equal(verdict(100, 19, 0, 0)[0], 'abandonment');
});

test('twenty percent is a broken path', () => {
  const [state, detail] = verdict(100, 20, 0, 0);
  assert.equal(state, 'no-payment-method');
  assert.match(detail, /last_setup_error/);
});

test('a pile at requires_confirmation names the client', () => {
  const [state, detail] = verdict(100, 5, 40, 2);
  assert.equal(state, 'unconfirmed');
  assert.match(detail, /confirmSetup/);
});

test('requires_action points at the return_url', () => {
  const [state, detail] = verdict(100, 5, 10, 40);
  assert.equal(state, 'return-url');
  assert.match(detail, /return_url/);
});

test('a tie is broken deterministically', () => {
  assert.equal(verdict(100, 20, 20, 20)[0], 'return-url');
  assert.equal(verdict(100, 20, 20, 0)[0], 'unconfirmed');
});