Skip to content

Payment Processing

BadgerCommerce provides a comprehensive payment processing system built on the PaymentV2 architecture — a pluggable, multi-method payment framework that supports split payments, two-phase authorisation, and extensible payment method processors.

Key Features

Payment Methods

  • Credit/Debit Cards: Process payments via Stripe (Payment Intents API)
  • Digital Wallets: Support for Apple Pay, Google Pay via Stripe
  • Gift Cards: Full checkout redemption with two-phase reserve/confirm flow (see Gift Cards)
  • Split Payments: Use multiple payment methods on a single order (e.g. gift card + Stripe)

Payment Processing

  • Two-Phase Flow: Authorise → Capture pattern for all payment methods
  • Secure Processing: PCI-compliant via Stripe's tokenisation
  • Real-time Authorization: Instant payment verification
  • Webhook Processing: Strategy-pattern event handlers for Stripe webhook events
  • Automatic Retries: Intelligent handling of failed payment attempts

Integration with Stripe

  • Stripe Connect: Multi-merchant capability for marketplace scenarios
  • Webhooks: 15+ dedicated event handlers auto-discovered via Spring component scanning
  • Payment Intents: Modern payment flow with SCA/3DS authentication support
  • Saved Payment Methods: Securely store card details for future use

Order Management

  • Capture & Settlement: Flexible timing for payment capture via pipeline processors
  • Refunds: Full and partial refund processing
  • Cancellations: Graceful handling with payment method rollback
  • Payment History: Complete audit trail via PaymentIntent and transaction records

Multi-currency Support

  • Global Currencies: Process payments in multiple currencies
  • Site Configuration: Currency configured per-site via siteCurrencyCode config key
  • Settlement Options: Flexible settlement currency configuration via Stripe Connect

PaymentV2 Architecture

Overview

PaymentV2 is a pluggable payment framework that decouples payment method logic from the checkout flow. Each payment method (Stripe, gift cards, etc.) has its own PaymentMethodProcessor that handles the full lifecycle.

Core Components

PaymentV2Adapter (commerce-core/.../payment/PaymentV2Adapter.java) - Implements the legacy PaymentService interface, bridging old and new payment systems - Routes payment operations to the appropriate PaymentMethodProcessor based on payment method type - Orchestrates split payment flows (e.g. gift card partial + Stripe remainder) - Manages PaymentIntent lifecycle on orders

PaymentMethodProcessor (common/.../payment/paymentV2/service/PaymentMethodProcessor.java) - Abstract base class for all payment method implementations - Generic type parameter <T extends PaymentMethod> for type-safe payment method handling - Required methods:

Method Purpose
createPaymentMethod() Initialise the payment method for an order
authorise() Authorise payment (reserve funds)
capture() Capture previously authorised payment
refund() Refund a captured payment

PaymentIntent (common/.../payment/paymentV2/beans/PaymentIntent.java) - Stored on the Order to track payment state - Contains the list of PaymentMethod instances used - Tracks authorisation, capture, and refund status

Payment Method Processors

Processor Payment Method Module
StripePaymentMethodProcessor StripePaymentMethod common
GiftCardPaymentMethodProcessor GiftCardPaymentMethod common

Split Payment Flow

When a customer uses a gift card + Stripe:

  1. Gift card applied: GiftCardPaymentMethodProcessor.authorise() reserves balance on the gift card
  2. Stripe payment created: Stripe Payment Intent created for the remaining amount
  3. Customer completes 3DS: Stripe confirms payment
  4. Order submitted: PaymentV2Adapter captures both methods:
  5. Gift card: confirmReservation() finalises the deduction
  6. Stripe: Payment Intent captured
  7. On failure: Gift card reservation released, Stripe intent cancelled

Checkout UI Integration

PaymentExtension (web-mvc/.../extensions/checkout/PaymentExtension.java) - Renders the payment form on the checkout page - Handles gift card application AJAX requests (validate card, show balance, apply to order) - Calculates remaining amount after gift card application - Integrates with Stripe Elements for card input

Stripe Webhook Handlers

Stripe events are processed via a strategy pattern:

StripeEventProcessor (worker/.../payment/stripe/StripeEventProcessor.java) - Auto-discovers all StripeEventHandler implementations via List<StripeEventHandler> injection - Maps handlers by event type at startup - Falls back to legacy handler for unmigrated events

Handler implementations (15+): - ChargeSucceededHandler, ChargeFailedHandler, ChargeRefundedHandler - PaymentIntentSucceededHandler, PaymentIntentPaymentFailedHandler - CustomerSubscriptionCreatedHandler, CustomerSubscriptionDeletedHandler - InvoicePaymentSucceededHandler, InvoicePaymentFailedHandler

Technical Implementation

Key Classes

Class Location Purpose
PaymentV2Adapter commerce-core Bridges legacy PaymentService → PaymentV2
PaymentMethodProcessor common Abstract base for payment method processors
StripePaymentMethodProcessor common Stripe payment processing
GiftCardPaymentMethodProcessor common Gift card checkout redemption
PaymentIntent common Payment state tracking on orders
PaymentMethod common Abstract payment method base
StripePaymentMethod common Stripe-specific payment data
GiftCardPaymentMethod common Gift card payment data
PaymentExtension web-mvc Checkout UI extension
SettlePaymentProcessor commerce-core Pipeline processor for payment capture
StripeEventProcessor worker Webhook event dispatcher
StripeEventHandler worker Webhook handler interface

Pipeline Processors

Payment-related processors in the order pipeline:

Processor Pipeline Purpose
SettlePaymentProcessor submitOrder Captures payment after order validation
ConditionalCaptureProcessor submitOrder Conditionally captures based on pipeline name
PaymentStateValidationProcessor various Validates payment state before processing
RefundOrderChargeProcessor refundOrder Processes refunds via payment service
SetPaymentToRefundPendingProcessor refundOrder Marks payment for refund

Integration Points

The payment system integrates with: - Order System: PaymentIntent stored on Order, captured via pipeline - Gift Card System: Two-phase balance reservation for checkout (see Gift Cards) - Subscription System: Stripe subscription billing (see Subscriptions) - Customer Accounts: Saved payment methods via Stripe Customer objects - Webhook System: Async event processing for payment status updates - Admin UI: Transaction monitoring, refund operations

Administration

Payment functionality can be managed through: - Payment method configuration per site - Transaction monitoring via order detail views - Refund and void operations from admin order management - Stripe webhook event logs - Gift card balance and transaction management

Configuration

Config Key Default Category Purpose
siteCurrencyCode GBP payment-config Site's base currency
giftCardService savvyGiftCardService payment-config Active gift card provider
payment-v2-enabled true payment-config Enable PaymentV2 adapter
stripe-js-on-every-page false payment-config Load Stripe.js on every storefront page (more Radar fraud signal) instead of only on pages that take a payment (~1 MB less JavaScript elsewhere)

Adding a New Payment Method

To add a new payment method to PaymentV2:

  1. Create a PaymentMethod subclass (e.g. MyPaymentMethod) in common/.../payment/
  2. Create a PaymentMethodProcessor<MyPaymentMethod> implementation
  3. Register it as a Spring @Service
  4. Wire it into PaymentV2Adapter alongside existing processors
  5. Add checkout UI support in PaymentExtension and payment templates
  6. Create webhook handlers if the provider sends async events