Handle Failed Payments

async function processDonation(donationRequest) {
  const response = await fetch(
    'https://prod-api.raisedonors.com/api/Raise/give',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.RAISE_API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(donationRequest),
    }
  );

  if (response.ok) {
    return { success: true, gift: await response.json() };
  }

  const problem = await response.json();

  // Classify the failure
  const classification = classifyPaymentFailure(response.status, problem);

  return {
    success: false,
    classification,
    detail: problem.detail,
    fieldErrors: problem.errors,
  };
}

function classifyPaymentFailure(status, problem) {
  if (status === 401) return 'auth_error';
  if (status === 429) return 'rate_limited';
  if (status >= 500) return 'gateway_error';

  // 400 — could be validation or payment failure
  if (problem.errors) return 'validation_error';

  // Payment-failure 400: surface to donor
  return 'payment_declined';
}

async function findFailedSchedules() {
  const allFailedSchedules = [];
  let skip = 0;
  const take = 1000;

  while (true) {
    const response = await fetch(
      'https://prod-api.raisedonors.com/api/RecurringGift/query',
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.RAISE_API_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          skip,
          take,
          sortBy: 'id',
          groups: [
            {
              conditions: [
                {
                  parameter: 'hasPaymentFailed',
                  operator: 0 /* equals — discover via QueryOptions */,
                  value: 'true',
                },
              ],
            },
          ],
        }),
      }
    );
    const page = await response.json();
    allFailedSchedules.push(...page.items);

    if (page.items.length < take) break;
    skip += take;
  }

  return allFailedSchedules;
}

curl https://prod-api.raisedonors.com/api/RecurringGift/9876/activities \
  -H "Authorization: Bearer YOUR_API_TOKEN"

async function findSchedulesExpiringWithinMonths(monthsAhead) {
  const allActive = await listAllActiveRecurringGifts();
  const now = new Date();
  const cutoff = new Date(now.getFullYear(), now.getMonth() + monthsAhead, 1);

  return allActive.filter((schedule) => {
    if (!schedule.expMonthAndYear) return false;
    const [month, year] = schedule.expMonthAndYear.split('/').map(Number);
    const expDate = new Date(year, month - 1, 1);
    return expDate < cutoff && expDate > now;
  });
}

class FailedPaymentMonitor {
  constructor({ token, emailService, outreachTracker }) {
    this.token = token;
    this.emailService = emailService;
    this.outreachTracker = outreachTracker;
  }

  async runDaily() {
    const failedSchedules = await this.findFailedSchedules();
    const expiringSchedules = await this.findSchedulesExpiringWithinMonths(2);

    const newFailures = [];
    const newExpiringSoon = [];

    for (const schedule of failedSchedules) {
      if (!await this.outreachTracker.hasContacted(schedule.id, 'failed', 14)) {
        newFailures.push(schedule);
      }
    }

    for (const schedule of expiringSchedules) {
      if (!await this.outreachTracker.hasContacted(schedule.id, 'expiring', 30)) {
        newExpiringSoon.push(schedule);
      }
    }

    for (const schedule of newFailures) {
      await this.notifyFailure(schedule);
    }
    for (const schedule of newExpiringSoon) {
      await this.notifyExpiringSoon(schedule);
    }

    return {
      failedCount: newFailures.length,
      expiringCount: newExpiringSoon.length,
    };
  }

  async notifyFailure(schedule) {
    const pageUrl = await this.generateDonorPage(schedule.donor.id);
    await this.emailService.send({
      to: schedule.donor.email,
      template: 'payment-failed',
      data: { donor: schedule.donor, pageUrl, amount: schedule.formattedAmount },
    });
    await this.outreachTracker.recordContact(schedule.id, 'failed');
  }

  async notifyExpiringSoon(schedule) {
    const pageUrl = await this.generateDonorPage(schedule.donor.id);
    await this.emailService.send({
      to: schedule.donor.email,
      template: 'card-expiring',
      data: { donor: schedule.donor, pageUrl, expDate: schedule.expMonthAndYear },
    });
    await this.outreachTracker.recordContact(schedule.id, 'expiring');
  }

  // findFailedSchedules, findSchedulesExpiringWithinMonths, generateDonorPage
  // omitted for brevity — see the snippets earlier on this page.
}