Stripe Integration

Stripe is the primary payment provider, handling card payments, Apple Pay, Google Pay, ACH transfers, and tax calculation. It is always registered (no conditional env check).

Architecture

StripeAdapter

The StripeAdapter class (lib/payments/providers/stripe.ts) implements PaymentProviderAdapter using the Stripe Node.js SDK.

Payment Methods Handled

createPayment

Creates a Stripe PaymentIntent with:

• Amount in cents and USD currency
• Shipping address attached to the intent
• Customer ID for saved payment methods
• setup_future_usage when customer opts to save card
• Metadata: orderId, orderNumber, customerEmail

Returns a clientSecret for client-side confirmation via Stripe.js.

Status Mapping

function mapStripeStatus(status: string): PaymentResult['status'] {
  switch (status) {
    case 'requires_payment_method':
    case 'requires_confirmation':
      return 'REQUIRES_CONFIRMATION'
    case 'requires_action':
      return 'REQUIRES_ACTION'
    case 'processing':
      return 'PROCESSING'
    case 'succeeded':
      return 'SUCCEEDED'
    default:
      return 'FAILED'
  }
}

Stripe Tax

Tax calculation uses the Stripe Tax API via lib/tax-calculator.ts. See the Taxes page for details.

Client-Side Integration

The checkout page loads Stripe.js and wraps the payment form in <Elements>:

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY)

<Elements stripe={stripePromise}>
  <CardElement options={CardElementOptions} />
  <ExpressCheckoutElement />
  <LinkAuthenticationElement />
</Elements>

Webhooks

Stripe webhooks are handled at /api/webhooks/stripe/route.ts. The adapter's verifyWebhookSignature() method validates the stripe-signature header against STRIPE_WEBHOOK_SECRET.

Environment Variables