a bank account sits at status errored and payouts stop

"""Report connected accounts whose payout destination Stripe has stopped using.

Read only. GETs only, no writes: give this a RESTRICTED key with read access to
Connected accounts, Bank accounts, Payouts and Balance. 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_external_account_errored")

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

DAY = 86400

# Statuses where Stripe has stopped sending scheduled payouts to this
# destination. Same symptom, three different repairs, which is why the table is
# the check rather than a comparison against the one status everybody knows.
HALTED = {
    "errored":
        "a payout to this destination failed. Editing the account or routing "
        "number on the existing object does not clear this: attach a NEW external "
        "account and set default_for_currency on it.",
    "verification_failed":
        "the ownership details behind this destination could not be verified. "
        "Attach a new external account whose holder details match the account.",
    "tokenized_account_number_deactivated":
        "the tokenized account number behind this destination was deactivated. "
        "Re-link the bank through Financial Connections to mint a new one.",
}

# Statuses where payouts can be sent. `new` simply means Stripe has not yet had
# reason to validate it, which is not a problem.
HEALTHY = ("new", "validated", "verified")


def verdict(external, last_payout_created, available_amount, now):
    """Classify one external account. Pure. Returns (state, detail).

    `last_payout_created` and `available_amount` are the corroborating evidence
    and may be None, meaning it was not looked up. That is deliberate: the
    evidence is only fetched for destinations that already look halted, so the
    classifier has to be honest about the difference between "no money stranded"
    and "nobody checked".
    """
    if external is None:
        return ("no-destination",
                "no external account attached at all: there is nothing for a payout "
                "to be sent to")

    status = (external.get("status") or "").lower()

    if status in HALTED:
        bits = ["status %s" % status, HALTED[status]]
        if available_amount:
            bits.append("%d (minor units) sitting in the available balance"
                        % available_amount)
        if last_payout_created is not None:
            bits.append("last payout %d day(s) ago"
                        % ((now - last_payout_created) // DAY))
        elif available_amount is not None:
            bits.append("no payout has ever been attempted")
        if not external.get("default_for_currency"):
            bits.append("not the default destination for %s, so cleanup rather than "
                        "the cause" % (external.get("currency") or "its currency"))
        state = "stranded" if available_amount else "halted"
        return (state, " | ".join(bits))

    if status in HEALTHY:
        return ("healthy", "status %s: payouts can be sent here" % status)

    return ("unknown", "unrecognised status %r: read it before assuming it is fine"
            % (external.get("status"),))


def get(session, path, account=None, **params):
    headers = {"Stripe-Account": account} if account else None
    r = session.get(API + path, params=params, headers=headers, 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 accounts(session, cap):
    """Yield connected accounts, paginating until Stripe stops or the cap is hit."""
    seen = 0
    params = {"limit": 100}
    while True:
        page = get(session, "/accounts", **params)
        data = page.get("data", [])
        for acct in data:
            yield acct
            seen += 1
            if seen >= cap:
                return
        if not data or not page.get("has_more"):
            return
        params["starting_after"] = data[-1]["id"]


def evidence(session, account_id):
    """Balance and last payout for one account. Only called when it may matter."""
    balance = get(session, "/balance", account=account_id)
    available = sum(b.get("amount", 0) for b in balance.get("available", []) or [])
    payouts = get(session, "/payouts", account=account_id, limit=1)
    data = payouts.get("data", [])
    return (data[0].get("created") if data else None), available


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--account", help="check one connected account instead of all")
    ap.add_argument("--max-accounts", type=int, default=5000,
                    help="stop paginating after this many accounts")
    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())

    if args.account:
        targets = [{"id": args.account}]
    else:
        targets = list(accounts(s, args.max_accounts))

    counts = {}
    destinations = 0

    for acct in targets:
        acct_id = acct.get("id")
        banks = get(s, "/accounts/%s/external_accounts" % acct_id,
                    object="bank_account", limit=100).get("data", [])
        if not banks:
            state, detail = verdict(None, None, None, now)
            counts[state] = counts.get(state, 0) + 1
            log.warning("%s  %-14s %s", acct_id, state, detail)
            continue

        for bank in banks:
            destinations += 1
            # The evidence costs two extra calls, so only spend them where the
            # status already says payouts have stopped.
            if (bank.get("status") or "").lower() in HALTED:
                last_payout, available = evidence(s, acct_id)
            else:
                last_payout, available = None, None
            state, detail = verdict(bank, last_payout, available, now)
            counts[state] = counts.get(state, 0) + 1
            if state == "healthy":
                continue
            log.warning("%s %s  %-14s %s", acct_id, bank.get("id", "ba_?"),
                        state, detail)

    halted = counts.get("halted", 0)
    stranded = counts.get("stranded", 0)
    log.info("%d account(s), %d destination(s): %d halted, %d stranded",
             len(targets), destinations, halted, stranded)

    if halted or stranded:
        log.warning("  repair: attach fresh details rather than editing the frozen "
                    "object, then make the new one default:")
        log.warning("  POST %s/accounts/{id} with external_account={{BANK_TOKEN}}", API)
        log.warning("  POST %s/accounts/{id}/external_accounts/{ba_id} with "
                    "default_for_currency=true", API)
        log.warning("  check: a flat count of failed payouts is not recovery when the "
                    "destination is frozen, because nothing is being attempted")
    if counts.get("no-destination"):
        log.warning("  %d account(s) have no bank account attached at all",
                    counts["no-destination"])
    return 1 if (halted or stranded or counts.get("no-destination")
                 or counts.get("unknown")) else 0


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

/**
 * Report connected accounts whose payout destination Stripe has stopped using.
 *
 * Read only. GETs only, no writes: give this a RESTRICTED key with read access
 * to Connected accounts, Bank accounts, Payouts and Balance. The repair is
 * printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

const DAY = 86400;

// Statuses where Stripe has stopped sending scheduled payouts to this
// destination. Same symptom, three different repairs.
const HALTED = {
  errored:
    'a payout to this destination failed. Editing the account or routing number ' +
    'on the existing object does not clear this: attach a NEW external account ' +
    'and set default_for_currency on it.',
  verification_failed:
    'the ownership details behind this destination could not be verified. Attach ' +
    'a new external account whose holder details match the account.',
  tokenized_account_number_deactivated:
    'the tokenized account number behind this destination was deactivated. ' +
    'Re-link the bank through Financial Connections to mint a new one.',
};

// Statuses where payouts can be sent. `new` means Stripe has had no reason to
// validate it yet, which is not a problem.
const HEALTHY = ['new', 'validated', 'verified'];

/**
 * Classify one external account. Pure. Returns [state, detail].
 * The evidence arguments may be null, meaning nobody looked: it is only fetched
 * for destinations that already look halted, and the classifier has to keep
 * "no money stranded" distinct from "not checked".
 */
export function verdict(external, lastPayoutCreated, availableAmount, now) {
  if (external === null || external === undefined) {
    return ['no-destination',
      'no external account attached at all: there is nothing for a payout to be ' +
      'sent to'];
  }

  const status = (external.status ?? '').toLowerCase();

  if (Object.prototype.hasOwnProperty.call(HALTED, status)) {
    const bits = [`status ${status}`, HALTED[status]];
    if (availableAmount) {
      bits.push(`${availableAmount} (minor units) sitting in the available balance`);
    }
    if (lastPayoutCreated !== null && lastPayoutCreated !== undefined) {
      bits.push(`last payout ${Math.floor((now - lastPayoutCreated) / DAY)} day(s) ago`);
    } else if (availableAmount !== null && availableAmount !== undefined) {
      bits.push('no payout has ever been attempted');
    }
    if (!external.default_for_currency) {
      bits.push(`not the default destination for ${external.currency ?? 'its currency'}, ` +
                'so cleanup rather than the cause');
    }
    return [availableAmount ? 'stranded' : 'halted', bits.join(' | ')];
  }

  if (HEALTHY.includes(status)) {
    return ['healthy', `status ${status}: payouts can be sent here`];
  }

  return ['unknown',
    `unrecognised status ${JSON.stringify(external.status)}: read it before ` +
    'assuming it is fine'];
}

async function get(key, path, { account, ...params } = {}) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const headers = { Authorization: `Bearer ${key}` };
  if (account) headers['Stripe-Account'] = account;
  const res = await fetch(url, { headers });
  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* accounts(key, cap = 5000) {
  let seen = 0;
  const params = { limit: 100 };
  for (;;) {
    const page = await get(key, '/accounts', params);
    const data = page.data ?? [];
    for (const acct of data) {
      yield acct;
      seen += 1;
      if (seen >= cap) return;
    }
    if (data.length === 0 || !page.has_more) return;
    params.starting_after = data[data.length - 1].id;
  }
}

async function evidence(key, accountId) {
  const balance = await get(key, '/balance', { account: accountId });
  const available = (balance.available ?? []).reduce((t, b) => t + (b.amount ?? 0), 0);
  const payouts = await get(key, '/payouts', { account: accountId, limit: 1 });
  const data = payouts.data ?? [];
  return [data.length ? data[0].created : null, available];
}

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 now = Math.floor(Date.now() / 1000);
  const targets = [];
  for await (const acct of accounts(key)) targets.push(acct);

  const counts = new Map();
  let destinations = 0;

  for (const acct of targets) {
    const banks = (await get(key, `/accounts/${acct.id}/external_accounts`,
      { object: 'bank_account', limit: 100 })).data ?? [];

    if (banks.length === 0) {
      const [state, detail] = verdict(null, null, null, now);
      counts.set(state, (counts.get(state) ?? 0) + 1);
      console.warn(`${acct.id}  ${state.padEnd(14)} ${detail}`);
      continue;
    }

    for (const bank of banks) {
      destinations += 1;
      // The evidence costs two extra calls, so only spend them where the status
      // already says payouts have stopped.
      const halted = Object.prototype.hasOwnProperty.call(
        HALTED, (bank.status ?? '').toLowerCase());
      const [lastPayout, available] = halted
        ? await evidence(key, acct.id) : [null, null];
      const [state, detail] = verdict(bank, lastPayout, available, now);
      counts.set(state, (counts.get(state) ?? 0) + 1);
      if (state === 'healthy') continue;
      console.warn(`${acct.id} ${bank.id ?? 'ba_?'}  ${state.padEnd(14)} ${detail}`);
    }
  }

  const halted = counts.get('halted') ?? 0;
  const stranded = counts.get('stranded') ?? 0;
  console.log(`${targets.length} account(s), ${destinations} destination(s): ` +
    `${halted} halted, ${stranded} stranded`);

  if (halted || stranded) {
    console.warn('  repair: attach fresh details rather than editing the frozen ' +
                 'object, then make the new one default:');
    console.warn(`  POST ${API}/accounts/{id} with external_account={{BANK_TOKEN}}`);
    console.warn(`  POST ${API}/accounts/{id}/external_accounts/{ba_id} with ` +
                 'default_for_currency=true');
    console.warn('  check: a flat count of failed payouts is not recovery when the ' +
                 'destination is frozen, because nothing is being attempted');
  }
  if (counts.get('no-destination')) {
    console.warn(`  ${counts.get('no-destination')} account(s) have no bank account ` +
                 'attached at all');
  }
  if (halted || stranded || counts.get('no-destination') || counts.get('unknown')) {
    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_external_account_errored import HALTED, verdict

NOW = 1767225600  # 2026-01-01T00:00:00Z


def bank(status, default=True, currency="usd"):
    return {"id": "ba_1", "status": status, "currency": currency,
            "default_for_currency": default}


def test_a_validated_account_is_healthy():
    state, detail = verdict(bank("validated"), None, None, NOW)
    assert state == "healthy"
    assert "payouts can be sent" in detail


def test_new_is_not_an_error():
    # `new` only means Stripe has had no reason to validate it yet.
    assert verdict(bank("new"), None, None, NOW)[0] == "healthy"


def test_every_halting_status_is_caught_and_carries_its_own_repair():
    for status in HALTED:
        state, detail = verdict(bank(status), None, None, NOW)
        assert state == "halted", status
        assert status in detail


def test_errored_says_not_to_edit_the_existing_object():
    _, detail = verdict(bank("errored"), None, None, NOW)
    assert "does not clear this" in detail
    assert "NEW external account" in detail


def test_a_balance_behind_a_frozen_destination_is_stranded():
    state, detail = verdict(bank("errored"), NOW - 45 * 86400, 812340, NOW)
    assert state == "stranded"
    assert "812340" in detail
    assert "45 day(s) ago" in detail


def test_evidence_that_was_never_gathered_is_not_reported_as_no_money():
    # available_amount None means nobody looked. Saying "no payout has ever been
    # attempted" in that case would be an invention.
    _, detail = verdict(bank("errored"), None, None, NOW)
    assert "no payout has ever been attempted" not in detail
    _, detail = verdict(bank("errored"), None, 0, NOW)
    assert "no payout has ever been attempted" in detail


def test_a_frozen_non_default_destination_is_flagged_as_cleanup():
    _, detail = verdict(bank("verification_failed", default=False), None, None, NOW)
    assert "not the default destination for usd" in detail


def test_no_bank_account_at_all_is_its_own_answer():
    state, _ = verdict(None, None, None, NOW)
    assert state == "no-destination"


def test_an_unrecognised_status_is_not_assumed_healthy():
    assert verdict(bank("some_new_status"), None, None, NOW)[0] == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-external-account-errored.mjs';

const NOW = 1767225600; // 2026-01-01T00:00:00Z

const bank = (status, defaultForCurrency = true, currency = 'usd') => ({
  id: 'ba_1', status, currency, default_for_currency: defaultForCurrency,
});

test('a validated account is healthy', () => {
  const [state, detail] = verdict(bank('validated'), null, null, NOW);
  assert.equal(state, 'healthy');
  assert.match(detail, /payouts can be sent/);
});

test('new is not an error', () => {
  assert.equal(verdict(bank('new'), null, null, NOW)[0], 'healthy');
});

test('every halting status is caught and carries its own repair', () => {
  for (const status of ['errored', 'verification_failed',
    'tokenized_account_number_deactivated']) {
    const [state, detail] = verdict(bank(status), null, null, NOW);
    assert.equal(state, 'halted', status);
    assert.ok(detail.includes(status));
  }
});

test('errored says not to edit the existing object', () => {
  const [, detail] = verdict(bank('errored'), null, null, NOW);
  assert.match(detail, /does not clear this/);
  assert.match(detail, /NEW external account/);
});

test('a balance behind a frozen destination is stranded', () => {
  const [state, detail] = verdict(bank('errored'), NOW - 45 * 86400, 812340, NOW);
  assert.equal(state, 'stranded');
  assert.match(detail, /812340/);
  assert.match(detail, /45 day\(s\) ago/);
});

test('evidence that was never gathered is not reported as no money', () => {
  // A null available amount means nobody looked, which is not the same as zero.
  assert.ok(!verdict(bank('errored'), null, null, NOW)[1]
    .includes('no payout has ever been attempted'));
  assert.ok(verdict(bank('errored'), null, 0, NOW)[1]
    .includes('no payout has ever been attempted'));
});

test('a frozen non default destination is flagged as cleanup', () => {
  const [, detail] = verdict(bank('verification_failed', false), null, null, NOW);
  assert.match(detail, /not the default destination for usd/);
});

test('no bank account at all is its own answer', () => {
  assert.equal(verdict(null, null, null, NOW)[0], 'no-destination');
});

test('an unrecognised status is not assumed healthy', () => {
  assert.equal(verdict(bank('some_new_status'), null, null, NOW)[0], 'unknown');
});