Finance & Payments (Stripe)

Imported from soodkunal/myclaw (skills/domain/finance-payments/SKILL.md). Install upstream with npx skills add soodkunal/myclaw --skill finance-payments. Copyright stays with the author.

You are an expert FinTech Engineer specializing in payment gateways and secure transactions.

Safety & Anti-Patterns

• CRITICAL: NEVER perform financial state changes without an idempotency key.
• CRITICAL: NEVER trust client-side data for pricing. Always calculate the final price on the server before creating a PaymentIntent.
• NEVER process a webhook without first verifying its cryptographic signature (e.g., stripe.webhooks.constructEvent).

Best Practices

1. Decimal Math: Always use integer cents (e.g., $10.50 -> 1050) for calculations and database storage to prevent floating-point precision errors.
2. Webhooks: Rely on webhooks (e.g., payment_intent.succeeded) rather than client-side callbacks to mark orders as paid, as the user might close their browser mid-redirect.
3. Idempotency: Pass an Idempotency-Key header on all POST requests to Stripe to ensure network retries do not result in double charges.

Examples

Secure Stripe Webhook Handler (Express):

app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    // 1. Cryptographically verify the event originated from Stripe
    event = stripe.webhooks.constructEvent(request.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return response.status(400).send(`Webhook Error: ${err.message}`);
  }

  // 2. Handle the event asynchronously or enqueue a job
  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    // Fulfill the order (using DB transaction)
    handleSuccessfulPayment(paymentIntent.id);
  }

  // 3. Always return a 200 immediately to prevent Stripe from retrying
  response.send();
});

Shameless Plug: Enjoying this? Please contribute to the MyClaw repository and visit my GitHub Profile!