Stripe to Virtuous CRM

// On the donation form, when creating the PaymentIntent:
const paymentIntent = await stripe.paymentIntents.create({
  amount: 50000, // $500.00 in cents
  currency: 'usd',
  customer: stripeCustomerId,
  metadata: {
    virtuous_project_code: 'CLEAN-WATER',
    virtuous_segment_code: 'YE-2024',
    // ...any other Virtuous-side context to carry through
  },
});

import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

app.post(
  '/stripe/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // 1. Verify Stripe signature
    let event;
    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        req.headers['stripe-signature'],
        process.env.STRIPE_WEBHOOK_SECRET
      );
    } catch (err) {
      return res.status(401).send('Invalid Stripe signature');
    }

    // 2. Enqueue for processing — durable queue, not in-memory
    await db.virtuous_donation_queue.insert({
      platform_donation_id: event.id,  // The Stripe event ID is your stable idempotency anchor
      customer_id: deriveCustomerId(event),
      stripe_event_type: event.type,
      stripe_event_payload: event,
      status: 'pending',
    }, { onConflict: 'do_nothing' });  // Stripe retries also produce duplicate event IDs

    // 3. Acknowledge immediately
    res.status(200).send('OK');
  }
);

async function processPaymentIntentSucceeded(stripeEvent, customerId, token) {
  const intent = stripeEvent.data.object;
  const stripeCustomer = await stripe.customers.retrieve(intent.customer);

  // Determine the project designation from metadata
  const projectCode = intent.metadata.virtuous_project_code;
  if (!projectCode) {
    // No project specified — surface to customer for manual designation,
    // or fall back to a default project configured on your side.
    throw new Error('No virtuous_project_code in payment metadata');
  }

  const response = await fetch(
    'https://api.virtuoussoftware.com/api/v2/Gift/Transaction',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        transactionSource: 'Stripe',
        transactionId: intent.id,  // pi_xxx — stable across retries
        contact: {
          referenceId: stripeCustomer.id,  // cus_xxx
          type: 'Household',  // Adjust if your form distinguishes individuals from organizations
          firstname: extractFirstName(stripeCustomer),
          lastname: extractLastName(stripeCustomer),
          emailType: 'Home Email',
          email: stripeCustomer.email,
          phoneType: stripeCustomer.phone ? 'Mobile Phone' : undefined,
          phone: stripeCustomer.phone,
          address: stripeCustomer.address ? {
            address1: stripeCustomer.address.line1,
            address2: stripeCustomer.address.line2,
            city: stripeCustomer.address.city,
            state: stripeCustomer.address.state,
            postal: stripeCustomer.address.postal_code,
            country: stripeCustomer.address.country,
          } : undefined,
        },
        giftDate: new Date(intent.created * 1000).toISOString().slice(0, 10),
        giftType: 'Cash',
        amount: (intent.amount / 100).toFixed(2),
        currencyCode: intent.currency.toUpperCase(),
        batch: intent.metadata.virtuous_batch ?? 'Stripe',
        giftDesignations: [
          {
            projectCode,
            amountDesignated: (intent.amount / 100).toFixed(2),
          },
        ],
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Virtuous submission failed: ${response.status}`);
  }
}

async function processChargeRefunded(stripeEvent, customerId, token) {
  const charge = stripeEvent.data.object;

  // Find the original Gift in Virtuous by transaction reference
  const originalResponse = await fetch(
    `https://api.virtuoussoftware.com/api/Gift/Stripe/${encodeURIComponent(charge.payment_intent || charge.id)}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );

  if (!originalResponse.ok) {
    if (originalResponse.status === 404) {
      // The original Gift doesn't exist yet — Stripe's refund event arrived
      // before our giftCreate webhook from Virtuous. Defer and retry later.
      throw new Error('Original Gift not yet in Virtuous — will retry');
    }
    throw new Error(`Lookup failed: ${originalResponse.status}`);
  }

  const originalGift = await originalResponse.json();

  // Submit a reversing transaction
  await fetch(
    'https://api.virtuoussoftware.com/api/Gift/ReversingTransaction',
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        reversedGiftId: originalGift.id,
        giftDate: new Date().toISOString().slice(0, 10),
        notes: `Stripe refund processed ${new Date().toISOString()} — Refund ${charge.refunds.data[0]?.id}`,
      }),
    }
  );
}

async function processSubscriptionCreated(stripeEvent, customerId, token) {
  const subscription = stripeEvent.data.object;
  const stripeCustomer = await stripe.customers.retrieve(subscription.customer);

  // Determine the Virtuous Contact ID — either it exists, or it will after
  // the first invoice.paid event creates the donor. For now, store the
  // Stripe customer ID; the RecurringGift creation can defer until the
  // Contact is known.

  // For each recurring item, create a Virtuous RecurringGift
  for (const item of subscription.items.data) {
    const amount = item.price.unit_amount * item.quantity;

    await fetch(
      'https://api.virtuoussoftware.com/api/RecurringGift',
      {
        method: 'POST',
        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          transactionSource: 'Stripe',
          transactionId: subscription.id,  // sub_xxx
          contactId: await resolveContactIdFromStripeCustomer(stripeCustomer, token),
          startDate: new Date(subscription.start_date * 1000).toISOString().slice(0, 10),
          amount: (amount / 100).toFixed(2),
          frequency: mapStripeIntervalToVirtuous(item.price.recurring.interval),
          automatedPayments: true,
          trackPayments: true,
          designations: [
            {
              projectCode: subscription.metadata.virtuous_project_code,
              amountDesignated: (amount / 100).toFixed(2),
            },
          ],
        }),
      }
    );
  }
}

function mapStripeIntervalToVirtuous(stripeInterval) {
  // The Virtuous frequency enum is not fully documented — confirm valid values
  switch (stripeInterval) {
    case 'month':  return 'Monthly';
    case 'year':   return 'Annually';
    case 'week':   return 'Weekly';
    case 'day':    return 'Daily';
    default:       return 'Monthly';  // Safe default
  }
}

async function processInvoicePaid(stripeEvent, customerId, token) {
  const invoice = stripeEvent.data.object;

  // Submit a Gift Transaction linked to the RecurringGift
  await fetch(
    'https://api.virtuoussoftware.com/api/v2/Gift/Transaction',
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        transactionSource: 'Stripe',
        transactionId: invoice.payment_intent,  // The specific payment's PaymentIntent ID
        recurringGiftTransactionId: invoice.subscription,  // Links to the schedule
        contact: { referenceId: invoice.customer },
        giftDate: new Date(invoice.created * 1000).toISOString().slice(0, 10),
        giftType: 'Cash',
        amount: (invoice.amount_paid / 100).toFixed(2),
        currencyCode: invoice.currency.toUpperCase(),
        batch: 'Stripe-Recurring',
        giftDesignations: [
          {
            projectCode: invoice.subscription_details?.metadata?.virtuous_project_code,
            amountDesignated: (invoice.amount_paid / 100).toFixed(2),
          },
        ],
      }),
    }
  );
}

async function processSubscriptionDeleted(stripeEvent, customerId, token) {
  const subscription = stripeEvent.data.object;

  // Find the Virtuous RecurringGift by transaction reference
  // (There is no direct lookup-by-reference endpoint for RecurringGift in the spec;
  //  query for it by transactionSource/transactionId via POST /api/RecurringGift/Query
  //  or maintain the mapping in your own database from the create-time response.)
  const virtuousRecurringGiftId = await lookupRecurringGiftId(subscription.id);

  await fetch(
    `https://api.virtuoussoftware.com/api/RecurringGift/Cancel/${virtuousRecurringGiftId}`,
    {
      method: 'PUT',
      headers: { Authorization: `Bearer ${token}` },
    }
  );
}

async function reconcileStripePayouts(payoutDate, token) {
  // Fetch all charges in the payout from Stripe
  const charges = await stripe.charges.list({
    created: { gte: payoutDate.start, lte: payoutDate.end },
    limit: 100,
  });

  // Fetch all Gifts in the same date range from Virtuous
  const virtuousGifts = await queryVirtuousGiftsByDate(payoutDate, token);

  // For each Stripe charge, confirm a matching Gift exists in Virtuous
  for (const charge of charges.data) {
    const expectedTransactionId = charge.payment_intent || charge.id;
    const match = virtuousGifts.find(
      (g) => g.transactionSource === 'Stripe' && g.transactionId === expectedTransactionId
    );

    if (!match) {
      console.warn(`Stripe charge missing in Virtuous: ${expectedTransactionId}`);
      // Trigger resubmission or surface to customer
    }
  }
}