off-session charges die on authentication_required

"""Report customers whose saved cards cannot be charged off-session.

Read only. GET requests only, no writes: give this a RESTRICTED key with read
access to PaymentIntents, SetupIntents and PaymentMethods. The repair is printed,
never performed, because this script holds a credential to a live payments
account.
"""
import argparse
import collections
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_offsession_mandates")

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

# Both mean the issuer wanted the cardholder present. The second is what Stripe
# returns when the integration never handled the step-up at all.
STEP_UP = ("authentication_required", "authentication_not_handled")


def is_step_up_decline(intent):
    """True when this intent failed for want of authentication. Pure.

    The generic `code` on these is `card_declined`, identical to an ordinary
    decline, so the distinguishing value is one level down in `decline_code`.
    Anything grouping by `code` buries this failure inside the normal decline
    rate.
    """
    err = intent.get("last_payment_error") or {}
    return err.get("decline_code") in STEP_UP


def has_mandate(setup_intents):
    """True when some SetupIntent for this customer actually produced a mandate.

    Pure. A SetupIntent that was created and abandoned proves nothing: only one
    that reached `succeeded` and carries a non-null `mandate` records that the
    customer authenticated on-session and agreed to be charged later.
    """
    return any(si.get("status") == "succeeded" and si.get("mandate")
               for si in setup_intents)


def verdict(declines, saved_cards, setup_intents):
    """Classify one customer. Pure.

    Two states share a symptom and need different repairs: a decline with no
    mandate is a card-saving bug, and a decline despite a mandate is the issuer
    stepping up anyway. Retrying off-session is wrong for both.
    """
    mandated = has_mandate(setup_intents)
    if declines and not mandated:
        return ("unmandated",
                "%d off-session decline(s) and no succeeded SetupIntent carrying "
                "a mandate: the card was attached directly, so every retry "
                "declines identically" % declines)
    if declines:
        return ("stepped_up",
                "%d off-session decline(s) despite a mandate on file: the issuer "
                "asked for the cardholder anyway, so this charge has to be "
                "finished on-session" % declines)
    if saved_cards and not mandated:
        return ("at_risk",
                "%d saved card(s) with no mandate behind them: nothing has failed "
                "yet only because nothing has been charged off-session yet"
                % saved_cards)
    if saved_cards:
        return ("covered", "saved cards are backed by a mandate")
    return ("clear", "no saved cards to charge off-session")


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")
    if r.status_code == 403:
        raise SystemExit("403 from Stripe: the restricted key lacks read access to " + path)
    r.raise_for_status()
    return r.json()


def declines_by_customer(session, since, cap):
    """Tally step-up declines per customer id over the window."""
    counts = collections.Counter()
    seen = 0
    params = {"limit": 100, "created[gte]": since}
    while True:
        page = get(session, "/payment_intents", **params)
        rows = page.get("data", [])
        for pi in rows:
            seen += 1
            if pi.get("customer") and is_step_up_decline(pi):
                counts[pi["customer"]] += 1
        if not rows or not page.get("has_more") or seen >= cap:
            break
        params["starting_after"] = rows[-1]["id"]
    return counts, seen


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=90,
                    help="how far back to look for declines")
    ap.add_argument("--max-intents", type=int, default=5000,
                    help="stop sampling 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})

    since = int(time.time()) - args.days * 86400
    declines, sampled = declines_by_customer(s, since, args.max_intents)
    if not declines:
        log.info("sampled %d intent(s), no authentication_required declines", sampled)
        return 0

    unmandated = stepped_up = 0
    for customer, n in declines.most_common():
        sis = get(s, "/setup_intents", customer=customer, limit=100).get("data", [])
        cards = get(s, "/payment_methods", customer=customer, type="card",
                    limit=100).get("data", [])
        state, detail = verdict(n, len(cards), sis)
        log.warning("%-11s %s  %s", state, customer, detail)
        if state == "unmandated":
            unmandated += 1
            log.warning("  repair: send a SetupIntent link so the customer "
                        "re-authenticates, then charge with off_session=true "
                        "and confirm=true")
        elif state == "stepped_up":
            stepped_up += 1
            log.warning("  repair: bring the customer back on-session for this "
                        "charge; do not schedule another off-session retry")

    log.warning("  repair: stop attaching cards directly. Save with a SetupIntent "
                "using usage=off_session, or setup_future_usage=off_session during "
                "a payment")
    log.info("%d customer(s) declining: %d unmandated, %d stepped up",
             len(declines), unmandated, stepped_up)
    return 1


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

/**
 * Report customers whose saved cards cannot be charged off-session.
 *
 * Read only. GET requests only, no writes: give this a RESTRICTED key with read
 * access to PaymentIntents, SetupIntents and PaymentMethods. The repair is
 * printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// Both mean the issuer wanted the cardholder present. The second is what Stripe
// returns when the integration never handled the step-up at all.
const STEP_UP = new Set(['authentication_required', 'authentication_not_handled']);

/**
 * True when this intent failed for want of authentication. Pure.
 *
 * The generic `code` is `card_declined` on all of these, so the distinguishing
 * value is one level down in `decline_code`.
 */
export function isStepUpDecline(intent) {
  const err = intent.last_payment_error ?? {};
  return STEP_UP.has(err.decline_code);
}

/**
 * True when some SetupIntent for this customer actually produced a mandate. Pure.
 *
 * An abandoned SetupIntent proves nothing: it has to have succeeded and to carry
 * a non-null mandate.
 */
export function hasMandate(setupIntents) {
  return setupIntents.some((si) => si.status === 'succeeded' && si.mandate);
}

/**
 * Classify one customer. Pure.
 */
export function verdict(declines, savedCards, setupIntents) {
  const mandated = hasMandate(setupIntents);
  if (declines && !mandated) {
    return ['unmandated',
      `${declines} off-session decline(s) and no succeeded SetupIntent carrying ` +
      'a mandate: the card was attached directly, so every retry declines identically'];
  }
  if (declines) {
    return ['stepped_up',
      `${declines} off-session decline(s) despite a mandate on file: the issuer ` +
      'asked for the cardholder anyway, so this charge has to be finished on-session'];
  }
  if (savedCards && !mandated) {
    return ['at_risk',
      `${savedCards} saved card(s) with no mandate behind them: nothing has ` +
      'failed yet only because nothing has been charged off-session yet'];
  }
  if (savedCards) return ['covered', 'saved cards are backed by a mandate'];
  return ['clear', 'no saved cards to charge off-session'];
}

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.status === 403) {
    throw new Error(`403 from Stripe: the restricted key lacks read access to ${path}`);
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

export async function declinesByCustomer(key, since, cap = 5000) {
  const counts = new Map();
  let seen = 0;
  const params = { limit: 100, 'created[gte]': since };
  for (;;) {
    const page = await get(key, '/payment_intents', params);
    const rows = page.data ?? [];
    for (const pi of rows) {
      seen += 1;
      if (pi.customer && isStepUpDecline(pi)) {
        counts.set(pi.customer, (counts.get(pi.customer) ?? 0) + 1);
      }
    }
    if (!rows.length || !page.has_more || seen >= cap) break;
    params.starting_after = rows[rows.length - 1].id;
  }
  return { counts, seen };
}

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 since = Math.floor(Date.now() / 1000) - 90 * 86400;
  const { counts, seen } = await declinesByCustomer(key, since);
  if (counts.size === 0) {
    console.log(`sampled ${seen} intent(s), no authentication_required declines`);
    return;
  }

  let unmandated = 0;
  let steppedUp = 0;
  for (const [customer, n] of [...counts].sort((a, b) => b[1] - a[1])) {
    const { data: sis = [] } = await get(key, '/setup_intents',
                                         { customer, limit: 100 });
    const { data: cards = [] } = await get(key, '/payment_methods',
                                           { customer, type: 'card', limit: 100 });
    const [state, detail] = verdict(n, cards.length, sis);
    console.warn(`${state.padEnd(11)} ${customer}  ${detail}`);
    if (state === 'unmandated') {
      unmandated += 1;
      console.warn('  repair: send a SetupIntent link so the customer ' +
        're-authenticates, then charge with off_session=true and confirm=true');
    } else if (state === 'stepped_up') {
      steppedUp += 1;
      console.warn('  repair: bring the customer back on-session for this charge; ' +
        'do not schedule another off-session retry');
    }
  }

  console.warn('  repair: stop attaching cards directly. Save with a SetupIntent ' +
    'using usage=off_session, or setup_future_usage=off_session during a payment');
  console.log(`${counts.size} customer(s) declining: ${unmandated} unmandated, ` +
              `${steppedUp} stepped up`);
  process.exitCode = 1;
}

// Only run when invoked directly, so importing this module from the test file
// does not execute main() and fail the suite on the missing key.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from stripe_offsession_mandates import is_step_up_decline, has_mandate, verdict

GOOD_SI = {"status": "succeeded", "mandate": "mandate_123"}


def test_authentication_required_is_a_step_up_decline():
    assert is_step_up_decline({"last_payment_error":
                               {"code": "card_declined",
                                "decline_code": "authentication_required"}})


def test_authentication_not_handled_counts_too():
    assert is_step_up_decline({"last_payment_error":
                               {"decline_code": "authentication_not_handled"}})


def test_an_ordinary_decline_is_not_one():
    assert not is_step_up_decline({"last_payment_error":
                                   {"code": "card_declined",
                                    "decline_code": "insufficient_funds"}})


def test_a_succeeded_setup_intent_without_a_mandate_is_not_proof():
    # Green in the Dashboard, still not chargeable off-session.
    assert not has_mandate([{"status": "succeeded", "mandate": None}])


def test_an_abandoned_setup_intent_is_not_proof():
    assert not has_mandate([{"status": "requires_confirmation", "mandate": None}])


def test_declines_without_a_mandate_are_a_card_saving_bug():
    state, detail = verdict(4, 1, [{"status": "succeeded", "mandate": None}])
    assert state == "unmandated"
    assert "4" in detail


def test_declines_with_a_mandate_are_the_issuer_stepping_up():
    state, detail = verdict(2, 1, [GOOD_SI])
    assert state == "stepped_up"
    assert "on-session" in detail


def test_saved_cards_with_no_mandate_and_no_declines_yet_are_at_risk():
    state, _ = verdict(0, 3, [])
    assert state == "at_risk"


def test_saved_cards_behind_a_mandate_are_covered():
    assert verdict(0, 2, [GOOD_SI])[0] == "covered"


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

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { isStepUpDecline, hasMandate, verdict } from './stripe-offsession-mandates.mjs';

const GOOD_SI = { status: 'succeeded', mandate: 'mandate_123' };

test('authentication_required is a step up decline', () => {
  assert.equal(isStepUpDecline({
    last_payment_error: { code: 'card_declined',
                          decline_code: 'authentication_required' },
  }), true);
});

test('authentication_not_handled counts too', () => {
  assert.equal(isStepUpDecline({
    last_payment_error: { decline_code: 'authentication_not_handled' },
  }), true);
});

test('an ordinary decline is not one', () => {
  assert.equal(isStepUpDecline({
    last_payment_error: { code: 'card_declined', decline_code: 'insufficient_funds' },
  }), false);
});

test('a succeeded setup intent without a mandate is not proof', () => {
  assert.equal(hasMandate([{ status: 'succeeded', mandate: null }]), false);
});

test('an abandoned setup intent is not proof', () => {
  assert.equal(hasMandate([{ status: 'requires_confirmation', mandate: null }]), false);
});

test('declines without a mandate are a card saving bug', () => {
  const [state, detail] = verdict(4, 1, [{ status: 'succeeded', mandate: null }]);
  assert.equal(state, 'unmandated');
  assert.match(detail, /4/);
});

test('declines with a mandate are the issuer stepping up', () => {
  const [state, detail] = verdict(2, 1, [GOOD_SI]);
  assert.equal(state, 'stepped_up');
  assert.match(detail, /on-session/);
});

test('saved cards with no mandate and no declines yet are at risk', () => {
  assert.equal(verdict(0, 3, [])[0], 'at_risk');
});

test('saved cards behind a mandate are covered', () => {
  assert.equal(verdict(0, 2, [GOOD_SI])[0], 'covered');
});

test('a customer with no saved cards is clear', () => {
  assert.equal(verdict(0, 0, [])[0], 'clear');
});