payouts fail with account_closed and nobody is watching

"""Group failed Stripe payouts by failure_code and say what each one needs.

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

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

# The destination is wrong or gone. Nothing but new bank details fixes these.
NEW_DETAILS = (
    "account_closed", "no_account", "invalid_account_number",
    "invalid_account_number_length", "incorrect_account_holder_name",
    "incorrect_account_holder_address", "incorrect_account_holder_tax_id",
    "unsupported_card",
)
# The account exists but its holder has to authorise something with their bank.
BANK_AUTHORISATION = (
    "debit_not_authorized", "incorrect_account_type", "declined",
    "bank_account_restricted", "account_frozen",
)
# Your balance, not their bank.
FUNDING = ("insufficient_funds",)
# Transient. Worth one retry before anyone is contacted.
TRANSIENT = ("could_not_process", "bank_ownership_changed")
# A configuration mismatch on the destination rather than a bad number.
CONFIGURATION = ("invalid_currency", "unsupported_currency")


def classify(payout):
    """Sort one payout by what its failure needs. Pure, so the table is testable.

    Takes a /v1/payouts object. Returns (state, detail). The states name the
    person who can act, which is the only grouping that changes what you do next.
    """
    status = payout.get("status")
    if status in ("paid", "in_transit", "pending"):
        return ("open", "status %s: not a failure, and not final either" % status)
    if status == "canceled":
        return ("canceled", "cancelled before it left, nothing was rejected")
    if status != "failed":
        return ("unknown", "unrecognised status %r" % (status,))

    code = payout.get("failure_code") or "unknown"
    message = payout.get("failure_message") or "no failure_message"
    returned = payout.get("failure_balance_transaction") is not None
    tail = "" if returned else " (no failure_balance_transaction: check the balance)"

    if code in NEW_DETAILS:
        return ("new-details",
                "%s: the destination is gone or wrong. Attach a fresh external "
                "account; re-entering the same number fails identically.%s"
                % (code, tail))
    if code in BANK_AUTHORISATION:
        return ("bank-authorisation",
                "%s: the account exists, its holder has to settle this with their "
                "bank. New details will not help.%s" % (code, tail))
    if code in FUNDING:
        return ("funding",
                "%s: your balance could not cover it. This is your side, not "
                "theirs.%s" % (code, tail))
    if code in TRANSIENT:
        return ("transient",
                "%s: worth one retry before anyone is contacted.%s" % (code, tail))
    if code in CONFIGURATION:
        return ("configuration",
                "%s: the destination cannot receive this currency.%s" % (code, tail))
    return ("unclassified",
            "failure_code %s: %s%s" % (code, message, tail))


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 failed_payouts(session, since, cap, account=None):
    """Yield failed payouts created since `since`, paginating to the cap."""
    seen = 0
    params = {"limit": 100, "status": "failed", "created[gte]": since}
    while True:
        page = get(session, "/payouts", account=account, **params)
        data = page.get("data", [])
        for po in data:
            yield po
            seen += 1
            if seen >= cap:
                return
        if not data or not page.get("has_more"):
            return
        params["starting_after"] = data[-1]["id"]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=90,
                    help="how far back to look (default 90)")
    ap.add_argument("--account", action="append", default=[],
                    help="also scan this connected account; repeatable")
    ap.add_argument("--max-payouts", type=int, default=2000,
                    help="stop paginating after this many failed payouts")
    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
    counts = {}
    by_code = {}
    returned_minor = 0
    total = 0

    for account in [None] + list(args.account):
        for po in failed_payouts(s, since, args.max_payouts, account):
            total += 1
            state, detail = classify(po)
            counts[state] = counts.get(state, 0) + 1
            code = po.get("failure_code") or "unknown"
            by_code[code] = by_code.get(code, 0) + 1
            returned_minor += int(po.get("amount") or 0)
            log.warning("%s  %-18s dest=%s  %s", po.get("id", "po_?"), state,
                        po.get("destination") or "?", detail)

    log.info("%d failed payout(s) in the last %d days", total, args.days)
    for code, n in sorted(by_code.items(), key=lambda kv: -kv[1]):
        log.warning("  %-34s %d", code, n)

    if total:
        log.warning("  %d in minor units came back to the balance: reconcile against "
                    "failure_balance_transaction or it is counted twice", returned_minor)
    if counts.get("new-details"):
        log.warning("  repair: attach a new external account and make it the default "
                    "for the currency. Editing the existing one rarely clears it.")
    if counts.get("bank-authorisation"):
        log.warning("  repair: the account holder authorises credits and debits with "
                    "their own bank. No API call substitutes for that.")
    if counts.get("funding"):
        log.warning("  repair: fund the balance before the next payout cycle")
    if total:
        log.warning("  check: the destination status is probably errored, which stops "
                    "scheduled payouts and is why the failures are not accumulating:")
        log.warning("  GET %s/accounts/{id}/external_accounts", API)
        log.warning("  check: payout.failed in enabled_events, or this stays a "
                    "five day old surprise:")
        log.warning("  GET %s/webhook_endpoints", API)
    return 1 if total else 0


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

/**
 * Group failed Stripe payouts by failure_code and say what each one needs.
 *
 * Read only. One paginated GET per account and no writes: give this a RESTRICTED
 * key with read access to Payouts. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// The destination is wrong or gone. Nothing but new bank details fixes these.
const NEW_DETAILS = [
  'account_closed', 'no_account', 'invalid_account_number',
  'invalid_account_number_length', 'incorrect_account_holder_name',
  'incorrect_account_holder_address', 'incorrect_account_holder_tax_id',
  'unsupported_card',
];
// The account exists but its holder has to authorise something with their bank.
const BANK_AUTHORISATION = [
  'debit_not_authorized', 'incorrect_account_type', 'declined',
  'bank_account_restricted', 'account_frozen',
];
// Your balance, not their bank.
const FUNDING = ['insufficient_funds'];
// Transient. Worth one retry before anyone is contacted.
const TRANSIENT = ['could_not_process', 'bank_ownership_changed'];
// A configuration mismatch on the destination rather than a bad number.
const CONFIGURATION = ['invalid_currency', 'unsupported_currency'];

/**
 * Sort one payout by what its failure needs. Pure, so the table is testable.
 * The states name the person who can act, which is the only grouping that
 * changes what you do next. Returns [state, detail].
 */
export function classify(payout) {
  const status = payout.status;
  if (['paid', 'in_transit', 'pending'].includes(status)) {
    return ['open', `status ${status}: not a failure, and not final either`];
  }
  if (status === 'canceled') {
    return ['canceled', 'cancelled before it left, nothing was rejected'];
  }
  if (status !== 'failed') {
    return ['unknown', `unrecognised status ${JSON.stringify(status)}`];
  }

  const code = payout.failure_code ?? 'unknown';
  const message = payout.failure_message ?? 'no failure_message';
  const returned = payout.failure_balance_transaction != null;
  const tail = returned ? '' : ' (no failure_balance_transaction: check the balance)';

  if (NEW_DETAILS.includes(code)) {
    return ['new-details',
      `${code}: the destination is gone or wrong. Attach a fresh external ` +
      `account; re-entering the same number fails identically.${tail}`];
  }
  if (BANK_AUTHORISATION.includes(code)) {
    return ['bank-authorisation',
      `${code}: the account exists, its holder has to settle this with their ` +
      `bank. New details will not help.${tail}`];
  }
  if (FUNDING.includes(code)) {
    return ['funding',
      `${code}: your balance could not cover it. This is your side, not theirs.${tail}`];
  }
  if (TRANSIENT.includes(code)) {
    return ['transient', `${code}: worth one retry before anyone is contacted.${tail}`];
  }
  if (CONFIGURATION.includes(code)) {
    return ['configuration',
      `${code}: the destination cannot receive this currency.${tail}`];
  }
  return ['unclassified', `failure_code ${code}: ${message}${tail}`];
}

async function get(key, path, { account = null, ...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* failedPayouts(key, since, cap = 2000, account = null) {
  let seen = 0;
  const params = { account, limit: 100, status: 'failed', 'created[gte]': since };
  for (;;) {
    const page = await get(key, '/payouts', params);
    const data = page.data ?? [];
    for (const po of data) {
      yield po;
      seen += 1;
      if (seen >= cap) return;
    }
    if (data.length === 0 || !page.has_more) 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 ?? 90);
  const extra = (process.env.ACCOUNTS ?? '').split(',').filter(Boolean);
  const since = Math.floor(Date.now() / 1000) - days * 86400;

  const counts = new Map();
  const byCode = new Map();
  let returnedMinor = 0;
  let total = 0;

  for (const account of [null, ...extra]) {
    for await (const po of failedPayouts(key, since, 2000, account)) {
      total += 1;
      const [state, detail] = classify(po);
      counts.set(state, (counts.get(state) ?? 0) + 1);
      const code = po.failure_code ?? 'unknown';
      byCode.set(code, (byCode.get(code) ?? 0) + 1);
      returnedMinor += po.amount ?? 0;
      console.warn(`${po.id ?? 'po_?'}  ${state.padEnd(18)} ` +
                   `dest=${po.destination ?? '?'}  ${detail}`);
    }
  }

  console.log(`${total} failed payout(s) in the last ${days} days`);
  for (const [code, n] of [...byCode].sort((a, b) => b[1] - a[1])) {
    console.warn(`  ${code.padEnd(34)} ${n}`);
  }

  if (total) {
    console.warn(`  ${returnedMinor} in minor units came back to the balance: ` +
                 'reconcile against failure_balance_transaction or it is counted twice');
  }
  if (counts.get('new-details')) {
    console.warn('  repair: attach a new external account and make it the default ' +
                 'for the currency. Editing the existing one rarely clears it.');
  }
  if (counts.get('bank-authorisation')) {
    console.warn('  repair: the account holder authorises credits and debits with ' +
                 'their own bank. No API call substitutes for that.');
  }
  if (counts.get('funding')) {
    console.warn('  repair: fund the balance before the next payout cycle');
  }
  if (total) {
    console.warn('  check: the destination status is probably errored, which stops ' +
                 'scheduled payouts and is why the failures are not accumulating:');
    console.warn(`  GET ${API}/accounts/{id}/external_accounts`);
    console.warn('  check: payout.failed in enabled_events, or this stays a five ' +
                 'day old surprise:');
    console.warn(`  GET ${API}/webhook_endpoints`);
    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_failed_payouts import classify


def test_paid_is_not_treated_as_final():
    # The paid to failed transition happens up to five business days later. A
    # classifier that calls paid "done" is the bug this guide is about.
    state, detail = classify({"status": "paid"})
    assert state == "open"
    assert "not final" in detail


def test_closed_account_needs_new_details():
    state, detail = classify({
        "status": "failed", "failure_code": "account_closed",
        "failure_balance_transaction": "txn_1",
    })
    assert state == "new-details"
    assert "fails identically" in detail


def test_debit_not_authorized_is_not_a_bank_details_problem():
    # The number is right. Attaching a new external account changes nothing, and
    # asking the seller for it wastes a round trip while they stay unpaid.
    state, detail = classify({
        "status": "failed", "failure_code": "debit_not_authorized",
        "failure_balance_transaction": "txn_2",
    })
    assert state == "bank-authorisation"
    assert "New details will not help" in detail


def test_insufficient_funds_is_your_side():
    state, detail = classify({
        "status": "failed", "failure_code": "insufficient_funds",
        "failure_balance_transaction": "txn_3",
    })
    assert state == "funding"
    assert "your side" in detail


def test_missing_reversal_is_called_out():
    _, detail = classify({"status": "failed", "failure_code": "account_closed"})
    assert "no failure_balance_transaction" in detail


def test_unknown_code_is_reported_rather_than_swallowed():
    state, detail = classify({
        "status": "failed", "failure_code": "brand_new_code",
        "failure_message": "Something Stripe added later",
    })
    assert state == "unclassified"
    assert "brand_new_code" in detail
    assert classify({"status": "in_flight"})[0] == "unknown"

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

test('paid is not treated as final', () => {
  // The paid to failed transition happens up to five business days later. A
  // classifier that calls paid "done" is the bug this guide is about.
  const [state, detail] = classify({ status: 'paid' });
  assert.equal(state, 'open');
  assert.match(detail, /not final/);
});

test('closed account needs new details', () => {
  const [state, detail] = classify({
    status: 'failed',
    failure_code: 'account_closed',
    failure_balance_transaction: 'txn_1',
  });
  assert.equal(state, 'new-details');
  assert.match(detail, /fails identically/);
});

test('debit not authorized is not a bank details problem', () => {
  // The number is right. Attaching a new external account changes nothing.
  const [state, detail] = classify({
    status: 'failed',
    failure_code: 'debit_not_authorized',
    failure_balance_transaction: 'txn_2',
  });
  assert.equal(state, 'bank-authorisation');
  assert.match(detail, /New details will not help/);
});

test('insufficient funds is your side', () => {
  const [state, detail] = classify({
    status: 'failed',
    failure_code: 'insufficient_funds',
    failure_balance_transaction: 'txn_3',
  });
  assert.equal(state, 'funding');
  assert.match(detail, /your side/);
});

test('missing reversal is called out', () => {
  const [, detail] = classify({ status: 'failed', failure_code: 'account_closed' });
  assert.match(detail, /no failure_balance_transaction/);
});

test('unknown code is reported rather than swallowed', () => {
  const [state, detail] = classify({
    status: 'failed',
    failure_code: 'brand_new_code',
    failure_message: 'Something Stripe added later',
  });
  assert.equal(state, 'unclassified');
  assert.match(detail, /brand_new_code/);
  assert.equal(classify({ status: 'in_flight' })[0], 'unknown');
});