@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/webhooks/template-webhook-payment-gateway-integration.md

@@ -1,2478 +1,2478 @@
----
-template_id: tpl-webhook-payment-gateway-integration
-canonical_filename: template-webhook-payment-gateway-integration.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: integration
-source: webhook-json-payment
-destination: fluent-event-api
-entity: payment
-format: json
-logging: versori
-status: stable
-features:
-  - webhook-signature-validation
-  - batched-events
-  - attribute-transformation
-  - memory-management
-  - enhanced-logging
----
-
-# Template: Webhook - Payment Gateway Integration (Adyen)
-
-**Template Version:** 2.0.0
-**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
-
-**🆕 Version 2.0.0 Enhancements:**
-- ✅ **Webhook Signature Validation** - Secure webhook verification with HMAC-SHA256
-- ✅ **Batched Events** - Process events in optimized batches to reduce API calls
-- ✅ **Attribute Transformation** - Handle nested arrays and complex data structures
-- ✅ **Memory Management** - Clear large arrays after processing batches
-- ✅ **Enhanced Logging** - Track batch processing and event submission with emoji indicators
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Intercept Fluent Workflow webhooks for payment operations (Capture, Refund, Auth Cancel, ReAuth), process via payment gateway (Adyen), and send events back to Fluent Commerce
-
-**Complexity**: Medium-High
-
-**Runtime**: Versori Platform
-
-**Estimated Lines**: ~1600 lines (modular structure)
-
----
-
-## STEP 1: Understand This Template
-
-**What This Template Does:**
-
-- **4 Versori HTTP webhooks** for payment operations:
-  - **Capture** - Capture an authorized payment (triggered by ORDER/FULFILLMENT workflow)
-  - **Refund** - Refund a captured payment (triggered by Payment Entity orchestration)
-  - **Auth Cancel** - Cancel an authorization (triggered by Payment Entity orchestration)
-  - **ReAuth** - Re-authorize a payment (triggered by Payment Entity orchestration)
-
-- **Modular architecture** - Easy to swap payment providers (Adyen → Stripe, etc.)
-- **Shared services** - Webhook validation, event sending, idempotency
-- **Payment provider abstraction** - Switch providers by changing one service
-- **Event mapping** - Payment gateway responses → Fluent event format
-- **Idempotency handling** - Prevent duplicate operations
-- **Error handling** - Comprehensive error handling and retry logic
-- **Trigger source validation** - Ensures webhooks called from correct Fluent workflows
-- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
-
-**Key SDK Components:**
-
-- `createClient()` - Universal client factory (auto-detects Versori context)
-- `client.sendEvent()` - Send events to Fluent Commerce Event API
-- `VersoriKVAdapter` - Idempotency tracking (KV storage)
-- `WebhookValidationService` - Webhook signature validation
-- Native Versori `log` - Use `log` from context
-
-**Entity Type:**
-
-- **Payment** - Fluent entity for payment operations
-- **Event API** - Uses `sendEvent()` to send payment events back to Fluent
-
-**Critical Patterns:**
-
-- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes payment in background
-- **External JSON Config**: Payment provider configuration in separate JSON file (`config/payment-provider-config.json`)
-- **Modular Architecture**: Separate services, workflows, config, types folders
-- **Background Processing**: Long-running operations (payment gateway API calls, event sending) happen asynchronously
-- **Idempotency**: KV storage prevents duplicate payment operations
-- **Provider Abstraction**: Easy to swap payment providers (Adyen → Stripe)
-
-**When to Use This Template:**
-
-- ✅ Payment gateway integration (Adyen, Stripe, etc.)
-- ✅ Payment operations triggered by Fluent Rubix workflows
-- ✅ Need fast webhook response (don't wait for payment gateway API calls)
-- ✅ Idempotency required (prevent duplicate charges/refunds)
-- ✅ Multiple payment operations (Capture, Refund, Cancel, ReAuth)
-
-**When NOT to Use:**
-
-- ❌ Direct payment processing (use payment gateway SDK directly)
-- ❌ Bulk payment operations (use Batch API or scheduled workflows)
-- ❌ Need synchronous payment confirmation (wait for result before responding)
-
----
-
-## 🎯 Flow Mapping & Trigger Sources
-
-| Payment Operation | Trigger Source | When It Happens | Context |
-|-------------------|----------------|------------------|---------|
-| **Capture** | ORDER/FULFILLMENT Workflow | Order ready to ship | Initial flow - order moves to fulfillment |
-| **Refund** | Payment Entity Orchestration | Post-purchase refund | After RMA processing, order cancellation |
-| **Auth Cancel** | Payment Entity Orchestration | Pre-capture cancellation | Order cancelled before capture |
-| **ReAuth** | Payment Entity Orchestration | Authorization renewal | Authorization expires or needs extension |
-
-**Note**: All webhooks are called from Rubix workflows, which handle all business logic validation before calling endpoints.
-
----
-
-## 🔑 Key Principle: Rubix Workflow Validation
-
-**IMPORTANT**: All webhooks are called from **Rubix workflows** within Fluent Commerce.
-
-### What This Means
-
-✅ **Rubix workflows handle ALL business logic validation**:
-- Order status checks (is order ready to ship?)
-- Payment state checks (is payment authorized? captured?)
-- Entity existence checks (does order exist? does payment exist?)
-- Business rules (can we refund? can we cancel?)
-
-✅ **If Rubix workflow calls an endpoint, the entity is already in the correct state**:
-- If Capture endpoint is called → Order is ready to ship, payment is authorized
-- If Refund endpoint is called → Payment is captured, refund is approved
-- If Cancel endpoint is called → Authorization exists, order is cancelled
-- If ReAuth endpoint is called → Authorization exists, needs renewal
-
-### What We Validate (Technical Only)
-
-✅ **Payload structure** - Required fields present  
-✅ **Trigger source** - Correct Rubix workflow calling endpoint  
-✅ **Data format** - Amounts, currencies, references are valid  
-✅ **Idempotency** - Prevent duplicate operations  
-✅ **Signature** - Webhook authenticity (if configured)
-
-### What We DON'T Validate
-
-❌ **Entity status** - Rubix workflow ensures correct status  
-❌ **Payment state** - Rubix workflow ensures correct state  
-❌ **Business rules** - Rubix workflow enforces rules  
-❌ **Entity existence** - Rubix workflow verified before calling
-
-### Why This Matters
-
-- **Simpler code** - No complex business logic in webhook handlers
-- **Single source of truth** - Rubix workflows own business logic
-- **Reliability** - Rubix workflows ensure correct state before calling
-- **Performance** - No redundant GraphQL queries to check entity status
-
----
-
-## STEP 2: Implementation Prompt for Claude Code
-
-**Copy this prompt and send to Claude Code to generate the complete implementation:**
-
-```
-Create Versori webhook workflows for payment gateway integration (Adyen) to Fluent Commerce.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhooks)
-2. Source: Payment operations via HTTP POST webhooks (JSON, from Fluent Rubix workflows)
-3. Destination: Fluent Commerce Event API (sendEvent for payment events)
-4. Format: JSON payment payload
-5. Entity: Payment (Event API for event sending)
-
-KEY FEATURES:
-- Sync + fire-and-forget pattern (fast webhook response, background processing)
-- External JSON configuration (config/payment-provider-config.json)
-- Modular architecture (workflows/, services/, config/, types/)
-- 4 webhooks: Capture, Refund, Auth Cancel, ReAuth
-- Payment provider abstraction (easy to swap Adyen → Stripe)
-- Idempotency handling (prevent duplicate operations)
-- Webhook signature validation
-- Trigger source validation (Rubix workflow validation)
-
-CRITICAL REQUIREMENTS:
-1. Webhook Mode: response: { mode: 'sync' } (fast response)
-2. Background Processing: Fire-and-forget pattern (no await on long operations)
-3. Provider Config: External JSON file (config/payment-provider-config.json)
-4. Modular Structure: Separate services/, config/, types/ folders
-5. Native Logging: Use log from context (no LoggingService)
-6. Idempotency: VersoriKVAdapter for duplicate prevention
-
-SDK METHODS TO USE:
-- createClient({ ...ctx, log }) - Pass full Versori context
-- client.setRetailerId(retailerId) - REQUIRED for Event API
-- client.sendEvent(event) - Send payment events to Fluent
-- new VersoriKVAdapter(openKv(':project:')) - Idempotency tracking
-- new WebhookValidationService(log) - Webhook signature validation
-
-FORBIDDEN PATTERNS:
-- ❌ Inline config (use external JSON)
-- ❌ await on background processing (use fire-and-forget)
-- ❌ LoggingService (use native log from context)
-- ❌ All code in one file (use modular structure)
-- ❌ async mode webhook (use sync + fire-and-forget)
-```
-
----
-
-## STEP 3: Detailed Flow Documentation
-
-### Complete Processing Flow (Payment Capture Example)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. WEBHOOK RECEIVED (from Rubix Workflow)                  │
-│    POST https://{workspace}.versori.run/payment-capture     │
-│    Content-Type: application/json                           │
-│    Body: { paymentReference: "...", amount: 100, ... }      │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
-│    - Check fluent_commerce connection exists                 │
-│    - Validate payment payload present                        │
-│    - Validate webhook signature (if configured)             │
-│    - Validate trigger source (ORDER_FULFILLMENT)          │
-│    - Check idempotency (prevent duplicates)                 │
-│    - Return HTTP 200 OK immediately                         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3a. Initialize Fluent Client                        │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    │     - setRetailerId(retailerId)                     │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3b. Call Payment Gateway API                         │  │
-│    │     - Adyen Capture API call                         │  │
-│    │     - Handle payment gateway response                │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3c. Send Event to Fluent                            │  │
-│    │     - Map gateway response to Fluent event format   │  │
-│    │     - client.sendEvent(event)                        │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3d. Update Idempotency Record                       │  │
-│    │     - Store successful operation in KV               │  │
-│    └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Response Timing
-
-| Stage | Timing | Blocking |
-|-------|--------|----------|
-| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
-| **Background Processing** | ~1000-3000ms | ❌ No (fire-and-forget) |
-| **Total Response Time** | ~10-50ms | ✅ Fast response |
-
-**Key Benefit**: Rubix workflow receives immediate acknowledgment (~50ms) while payment processing happens in background (~1-3s).
-
----
-
-## STEP 4: Production Modular Structure
-
-> **✅ This section shows the COMPLETE production-ready modular structure.**
-> All files are shown with proper imports/exports and folder organization.
-
-### Complete Project Structure
-
-```
-payment-gateway-integration/
-├── package.json                              # Dependencies and Versori config
-├── index.ts                                  # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       ├── payment-capture.ts            # Webhook: Capture payment
-    │       ├── payment-refund.ts              # Webhook: Refund payment
-    │       ├── payment-auth-cancel.ts        # Webhook: Cancel authorization
-    │       └── payment-reauth.ts             # Webhook: Re-authorize payment
-    │
-    ├── services/
-    │   ├── payment-provider.service.ts       # Payment provider abstraction
-    │   ├── payment-event.service.ts          # Event sending to Fluent
-    │   ├── idempotency.service.ts            # Idempotency handling
-    │   └── webhook-validation.service.ts     # Webhook signature validation
-    │
-    ├── config/
-    │   └── payment-provider-config.json      # Provider configuration (external JSON)
-    │
-    └── types/
-        └── payment.types.ts                  # TypeScript interfaces
-```
-
-**Why This Structure?**
-
-- ✅ **Clear separation**: Webhook handlers vs business logic vs provider abstraction
-- ✅ **Reusable services**: Payment logic can be reused across webhooks
-- ✅ **External config**: Provider configuration changes don't require code changes
-- ✅ **Provider abstraction**: Easy to swap payment providers (Adyen → Stripe)
-- ✅ **Type safety**: TypeScript interfaces for better IDE support
-- ✅ **Scalable**: Easy to add new payment operations or providers
-
----
-
-## SDK Methods Used
-
-- `webhook(name, handler)` - HTTP webhook endpoint (from `@versori/run`)
-- `createClient(ctx)` - Auto-detects Versori context, creates FluentClient
-- `client.setRetailerId()` - REQUIRED for Event API (after createClient)
-- `client.sendEvent()` - Send events to Fluent Commerce Event API
-- `VersoriKVAdapter(ctx.openKv(':project:'))` - Idempotency tracking
-- Native Versori log from context (no console.log, no LoggingService)
-
----
-
-## Architecture Overview
-
-### Modular Design Pattern
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Webhook Layer (4 webhooks)                             │
-│  - adyen-capture                                        │
-│  - adyen-refund                                         │
-│  - adyen-auth-cancel                                    │
-│  - adyen-reauth                                         │
-└─────────────────────────────────────────────────────────┘
-                        ↓
-┌─────────────────────────────────────────────────────────┐
-│  Shared Services (Reusable)                             │
-│  - WebhookValidationService                             │
-│  - PaymentEventService                                  │
-│  - IdempotencyService                                   │
-└─────────────────────────────────────────────────────────┘
-                        ↓
-┌─────────────────────────────────────────────────────────┐
-│  Payment Provider Abstraction                           │
-│  - PaymentProviderService (Interface)                  │
-│  - AdyenPaymentProviderService (Implementation)        │
-│  - StripePaymentProviderService (Future)                │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Key Benefits
-
-✅ **Single Connector** - All 4 flows in one document/workflow  
-✅ **Provider Agnostic** - Easy to swap Adyen → Stripe (change one service)  
-✅ **DRY Principle** - Shared services used by all webhooks  
-✅ **Maintainable** - Clear separation of concerns  
-✅ **Testable** - Each layer can be tested independently  
-
----
-
-## Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`http()`** → External API calls (chained from webhook/schedule)
-- **`fn()`** → Internal processing (chained from webhook/schedule)
-
-### Recommended Project Structure
-
-```
-payment-gateway-integration/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       ├── payment-capture.ts        # Webhook: Capture payment
-    │       ├── payment-refund.ts         # Webhook: Refund payment
-    │       ├── payment-auth-cancel.ts    # Webhook: Cancel authorization
-    │       └── payment-reauth.ts         # Webhook: Re-authorize payment
-    │
-    ├── services/
-    │   ├── payment-provider.service.ts   # Payment provider abstraction (interface)
-    │   ├── adyen-provider.service.ts     # Adyen implementation
-    │   ├── payment-event.service.ts      # Fluent Event API service
-    │   ├── webhook-validation.service.ts # Webhook validation & security
-    │   └── idempotency.service.ts        # Idempotency tracking
-    │
-    └── config/
-        ├── adyen-config.json             # Adyen-specific configuration
-        └── event-mapping.json            # Fluent event mapping config
-```
-
----
-
-## Project Setup
-
-```bash
-mkdir versori-payment-gateway-integration && cd $_
-npm init -y
-npm install @fluentcommerce/fc-connect-sdk@latest @versori/run
-mkdir -p src/{workflows/webhook,services,config}
-```
-
-### Package Configuration (package.json)
-
-```json
-{
-  "name": "versori-payment-gateway-integration",
-  "version": "1.0.0",
-  "versori": {
-    "workflows": "./src/index.ts"
-  },
-  "type": "module",
-  "scripts": {
-    "deploy": "versori deploy",
-    "logs": "versori logs"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "@types/node": "^20.0.0"
-  }
-}
-```
-
----
-
-## Activation Variables
-
-Configure these in Versori Activation Variables:
-
-```bash
-# Fluent Commerce Configuration
-fluentRetailerId=your-retailer-id
-
-# Payment Provider Configuration
-paymentProvider=adyen                    # adyen | stripe | paypal (future)
-paymentProviderEnvironment=test         # test | live
-
-# Adyen-Specific Configuration
-adyenMerchantAccount=YourMerchantAccount
-
-# Stripe-Specific Configuration (if using Stripe)
-# stripeSecretKey=sk_test_...
-# stripePublishableKey=pk_test_...
-
-# Webhook Security
-webhookSecret=your-shared-secret-for-signature-validation
-
-# Trigger Source Validation (Optional but Recommended)
-validateTriggerSource=true
-allowedTriggerSources=ORDER_FULFILLMENT,PAYMENT_ENTITY
-
-# Optional: Retry Configuration
-enableRetry=true
-maxRetries=3
-retryDelayMs=1000
-
-# Optional: Feature Flags
-enableIdempotency=true
-enableEventLogging=true
-```
-
----
-
-## Versori Connections Setup
-
-### Connection 1: Fluent Commerce (OAuth2)
-
-**Name**: `fluent_commerce`
-
-**Type**: OAuth2
-
-**Configuration**:
-- `base_url`: Your Fluent Commerce API URL (e.g., `https://api.fluentcommerce.com`)
-- `client_id`: OAuth2 client ID
-- `client_secret`: OAuth2 client secret
-- `username`: Your Fluent Commerce username
-- `password`: Your Fluent Commerce password
-
-**Note**: SDK auto-detects and uses this connection via `createClient(ctx)`
-
-### Connection 2: Payment Gateway (API Key or OAuth2)
-
-**Name**: `payment_gateway` (or `adyen_payment_gateway`, `stripe_payment_gateway`)
-
-**Type**: API Key (for Adyen) or OAuth2 (for Stripe)
-
-**Configuration**:
-- **Adyen**: `api_key` - Your Adyen API key
-- **Stripe**: `secret_key` - Your Stripe secret key
-
-**Alternative**: Store API key in activation variable `paymentGatewayApiKey` if preferred
-
----
-
-## Complete Working Code
-
-### File: `src/index.ts`
-
-```typescript
-/**
- * ═══════════════════════════════════════════════════════════════
- * 🚀 VERSORI PAYMENT GATEWAY INTEGRATION - ENTRY POINT
- * ═══════════════════════════════════════════════════════════════
- *
- * Entry Point - Registers all payment webhooks with Versori platform
- *
- * Pattern: MemoryInterpreter
- * - Export all workflows
- * - Clean separation of concerns
- * - Easy to add new workflows
- */
-
-import { MemoryInterpreter } from '@versori/run';
-import { paymentCapture } from './workflows/webhook/payment-capture';
-import { paymentRefund } from './workflows/webhook/payment-refund';
-import { paymentAuthCancel } from './workflows/webhook/payment-auth-cancel';
-import { paymentReauth } from './workflows/webhook/payment-reauth';
-
-async function main(): Promise<void> {
-  const mi = await MemoryInterpreter.newInstance();
-  
-  // Register all payment webhook workflows
-  mi.register(paymentCapture);
-  mi.register(paymentRefund);
-  mi.register(paymentAuthCancel);
-  mi.register(paymentReauth);
-  
-  await mi.start();
-}
-
-main().then().catch((err) => console.error('Failed to run main()', err));
-```
-
----
-
-### File: `src/services/payment-provider.service.ts`
-
-```typescript
-/**
- * Payment Provider Service Interface
- *
- * Abstract interface for payment gateway operations
- * Allows easy swapping of payment providers (Adyen → Stripe → PayPal)
- */
-
-import type { Logger } from '@fluentcommerce/fc-connect-sdk';
-
-export interface PaymentAmount {
-  value: number;      // Amount in minor units (e.g., 1000 = $10.00)
-  currency: string;  // ISO 4217 currency code (e.g., "USD")
-}
-
-export interface PaymentContext {
-  orderRef: string;
-  paymentReference: string;
-  retailerId?: string;
-  merchantReference?: string;
-}
-
-export interface CaptureResult {
-  success: boolean;
-  paymentReference: string;
-  amount: PaymentAmount;
-  capturedAt: string;
-  resultCode?: string;
-  error?: string;
-}
-
-export interface RefundResult {
-  success: boolean;
-  refundReference: string;
-  originalPaymentReference: string;
-  amount: PaymentAmount;
-  refundedAt: string;
-  refundType?: 'FULL' | 'PARTIAL';
-  error?: string;
-}
-
-export interface CancelResult {
-  success: boolean;
-  cancellationReference: string;
-  originalPaymentReference: string;
-  cancelledAt: string;
-  error?: string;
-}
-
-export interface ReauthResult {
-  success: boolean;
-  reauthReference: string;
-  originalPaymentReference: string;
-  amount: PaymentAmount;
-  reauthorizedAt: string;
-  expiryDate?: string;
-  error?: string;
-}
-
-/**
- * Payment Provider Service Interface
- *
- * Implement this interface for each payment provider:
- * - AdyenPaymentProviderService
- * - StripePaymentProviderService
- * - PayPalPaymentProviderService
- */
-export interface PaymentProviderService {
-  /**
-   * Capture an authorized payment
-   */
-  capturePayment(
-    paymentReference: string,
-    amount: PaymentAmount,
-    context: PaymentContext
-  ): Promise<CaptureResult>;
-
-  /**
-   * Refund a captured payment
-   */
-  refundPayment(
-    paymentReference: string,
-    amount: PaymentAmount,
-    context: PaymentContext
-  ): Promise<RefundResult>;
-
-  /**
-   * Cancel an authorization
-   */
-  cancelAuthorization(
-    paymentReference: string,
-    context: PaymentContext
-  ): Promise<CancelResult>;
-
-  /**
-   * Re-authorize a payment
-   */
-  reauthorizePayment(
-    paymentReference: string,
-    amount: PaymentAmount,
-    context: PaymentContext
-  ): Promise<ReauthResult>;
-
-  /**
-   * Get provider name (for logging/debugging)
-   */
-  getProviderName(): string;
-}
-```
-
----
-
-### File: `src/services/adyen-provider.service.ts`
-
-```typescript
-/**
- * Adyen Payment Provider Service Implementation
- *
- * Implements PaymentProviderService for Adyen payment gateway
- */
-
-import type { Logger } from '@fluentcommerce/fc-connect-sdk';
-import type {
-  PaymentProviderService,
-  PaymentAmount,
-  PaymentContext,
-  CaptureResult,
-  RefundResult,
-  CancelResult,
-  ReauthResult,
-} from './payment-provider.service';
-
-export class AdyenPaymentProviderService implements PaymentProviderService {
-  constructor(
-    private apiKey: string,
-    private environment: 'test' | 'live',
-    private merchantAccount: string,
-    private log: Logger
-  ) {}
-
-  getProviderName(): string {
-    return 'Adyen';
-  }
-
-  /**
-   * Get Adyen API base URL based on environment
-   */
-  private getApiUrl(): string {
-    return this.environment === 'live'
-      ? 'https://pal-live.adyen.com/pal/servlet/Payment'
-      : 'https://pal-test.adyen.com/pal/servlet/Payment';
-  }
-
-  /**
-   * Capture an authorized payment
-   */
-  async capturePayment(
-    paymentReference: string,
-    amount: PaymentAmount,
-    context: PaymentContext
-  ): Promise<CaptureResult> {
-    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/capture`;
-
-    this.log.info('🔧 [Adyen] Calling capture API', {
-      paymentReference,
-      amount: amount.value,
-      currency: amount.currency,
-      merchantAccount: this.merchantAccount,
-    });
-
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': this.apiKey,
-        },
-        body: JSON.stringify({
-          amount: amount,
-          merchantAccount: this.merchantAccount,
-        }),
-      });
-
-      const responseData = await response.json();
-
-      if (!response.ok) {
-        const error = responseData.error || {
-          errorCode: 'UNKNOWN_ERROR',
-          errorType: 'API_ERROR',
-          message: `HTTP ${response.status}: ${response.statusText}`,
-        };
-
-        this.log.error('❌ [Adyen] Capture API error', {
-          paymentReference,
-          errorCode: error.errorCode,
-          message: error.message,
-        });
-
-        return {
-          success: false,
-          paymentReference: paymentReference,
-          amount: amount,
-          capturedAt: new Date().toISOString(),
-          error: `${error.errorCode}: ${error.message}`,
-        };
-      }
-
-      this.log.info('✅ [Adyen] Capture successful', {
-        pspReference: responseData.pspReference,
-        resultCode: responseData.resultCode,
-      });
-
-      return {
-        success: true,
-        paymentReference: responseData.pspReference,
-        amount: responseData.amount || amount,
-        capturedAt: responseData.eventDate || new Date().toISOString(),
-        resultCode: responseData.resultCode,
-      };
-    } catch (error: any) {
-      this.log.error('❌ [Adyen] Capture API call failed', {
-        paymentReference,
-        error: error.message,
-      });
-
-      return {
-        success: false,
-        paymentReference: paymentReference,
-        amount: amount,
-        capturedAt: new Date().toISOString(),
-        error: error.message,
-      };
-    }
-  }
-
-  /**
-   * Refund a captured payment
-   */
-  async refundPayment(
-    paymentReference: string,
-    amount: PaymentAmount,
-    context: PaymentContext
-  ): Promise<RefundResult> {
-    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/refunds`;
-
-    this.log.info('🔧 [Adyen] Calling refund API', {
-      paymentReference,
-      amount: amount.value,
-      currency: amount.currency,
-    });
-
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': this.apiKey,
-        },
-        body: JSON.stringify({
-          amount: amount,
-          merchantAccount: this.merchantAccount,
-          reference: context.merchantReference || context.orderRef,
-        }),
-      });
-
-      const responseData = await response.json();
-
-      if (!response.ok) {
-        const error = responseData.error || {
-          errorCode: 'UNKNOWN_ERROR',
-          message: `HTTP ${response.status}: ${response.statusText}`,
-        };
-
-        return {
-          success: false,
-          refundReference: '',
-          originalPaymentReference: paymentReference,
-          amount: amount,
-          refundedAt: new Date().toISOString(),
-          error: `${error.errorCode}: ${error.message}`,
-        };
-      }
-
-      // Determine refund type (full vs partial)
-      const refundType = responseData.refundType || 'FULL';
-
-      return {
-        success: true,
-        refundReference: responseData.pspReference,
-        originalPaymentReference: paymentReference,
-        amount: responseData.amount || amount,
-        refundedAt: responseData.eventDate || new Date().toISOString(),
-        refundType: refundType as 'FULL' | 'PARTIAL',
-      };
-    } catch (error: any) {
-      return {
-        success: false,
-        refundReference: '',
-        originalPaymentReference: paymentReference,
-        amount: amount,
-        refundedAt: new Date().toISOString(),
-        error: error.message,
-      };
-    }
-  }
-
-  /**
-   * Cancel an authorization
-   */
-  async cancelAuthorization(
-    paymentReference: string,
-    context: PaymentContext
-  ): Promise<CancelResult> {
-    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/cancels`;
-
-    this.log.info('🔧 [Adyen] Calling cancel API', {
-      paymentReference,
-    });
-
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': this.apiKey,
-        },
-        body: JSON.stringify({
-          merchantAccount: this.merchantAccount,
-          reference: context.merchantReference || context.orderRef,
-        }),
-      });
-
-      const responseData = await response.json();
-
-      if (!response.ok) {
-        const error = responseData.error || {
-          errorCode: 'UNKNOWN_ERROR',
-          message: `HTTP ${response.status}: ${response.statusText}`,
-        };
-
-        return {
-          success: false,
-          cancellationReference: '',
-          originalPaymentReference: paymentReference,
-          cancelledAt: new Date().toISOString(),
-          error: `${error.errorCode}: ${error.message}`,
-        };
-      }
-
-      return {
-        success: true,
-        cancellationReference: responseData.pspReference,
-        originalPaymentReference: paymentReference,
-        cancelledAt: responseData.eventDate || new Date().toISOString(),
-      };
-    } catch (error: any) {
-      return {
-        success: false,
-        cancellationReference: '',
-        originalPaymentReference: paymentReference,
-        cancelledAt: new Date().toISOString(),
-        error: error.message,
-      };
-    }
-  }
-
-  /**
-   * Re-authorize a payment
-   */
-  async reauthorizePayment(
-    paymentReference: string,
-    amount: PaymentAmount,
-    context: PaymentContext
-  ): Promise<ReauthResult> {
-    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/reauthorise`;
-
-    this.log.info('🔧 [Adyen] Calling reauthorize API', {
-      paymentReference,
-      amount: amount.value,
-      currency: amount.currency,
-    });
-
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': this.apiKey,
-        },
-        body: JSON.stringify({
-          amount: amount,
-          merchantAccount: this.merchantAccount,
-          reference: context.merchantReference || context.orderRef,
-        }),
-      });
-
-      const responseData = await response.json();
-
-      if (!response.ok) {
-        const error = responseData.error || {
-          errorCode: 'UNKNOWN_ERROR',
-          message: `HTTP ${response.status}: ${response.statusText}`,
-        };
-
-        return {
-          success: false,
-          reauthReference: '',
-          originalPaymentReference: paymentReference,
-          amount: amount,
-          reauthorizedAt: new Date().toISOString(),
-          error: `${error.errorCode}: ${error.message}`,
-        };
-      }
-
-      return {
-        success: true,
-        reauthReference: responseData.pspReference,
-        originalPaymentReference: paymentReference,
-        amount: responseData.amount || amount,
-        reauthorizedAt: responseData.eventDate || new Date().toISOString(),
-        expiryDate: responseData.expiryDate,
-      };
-    } catch (error: any) {
-      return {
-        success: false,
-        reauthReference: '',
-        originalPaymentReference: paymentReference,
-        amount: amount,
-        reauthorizedAt: new Date().toISOString(),
-        error: error.message,
-      };
-    }
-  }
-}
-```
-
----
-
-### File: `src/services/webhook-validation.service.ts`
-
-```typescript
-/**
- * Webhook Validation Service
- *
- * Validates incoming webhooks from Fluent Workflow
- * - Signature validation (HMAC-SHA256)
- * - Payload structure validation
- * - Required field checking
- */
-
-import { createHmac } from 'node:crypto';
-import type { Logger } from '@fluentcommerce/fc-connect-sdk';
-
-export interface WebhookPayload {
-  orderRef: string;
-  paymentReference: string;
-  amount: {
-    value: number;
-    currency: string;
-  };
-  retailerId?: string;
-  merchantReference?: string;
-  triggerSource?: string;  // ORDER_FULFILLMENT | PAYMENT_ENTITY
-  orderStatus?: string;    // For ORDER_FULFILLMENT triggers
-  refundReason?: string;   // For Payment Entity refunds
-  cancelReason?: string;  // For Payment Entity cancellations
-  reauthReason?: string;   // For Payment Entity reauthorizations
-}
-
-export interface ValidationResult {
-  valid: boolean;
-  error?: string;
-  payload?: WebhookPayload;
-}
-
-export class WebhookValidationService {
-  constructor(private log: Logger) {}
-
-  /**
-   * Validate webhook signature using HMAC-SHA256
-   */
-  validateSignature(
-    payload: string,
-    signature: string,
-    secret: string
-  ): boolean {
-    if (!signature || !secret) {
-      return false;
-    }
-
-    const hmac = createHmac('sha256', secret);
-    hmac.update(payload);
-    const expectedSignature = hmac.digest('hex');
-
-    // Constant-time comparison to prevent timing attacks
-    if (signature.length !== expectedSignature.length) {
-      return false;
-    }
-
-    let match = true;
-    for (let i = 0; i < signature.length; i++) {
-      if (signature[i] !== expectedSignature[i]) {
-        match = false;
-      }
-    }
-
-    return match;
-  }
-
-  /**
-   * Validate webhook payload structure
-   */
-  validatePayload(payload: any): ValidationResult {
-    const requiredFields = ['orderRef', 'paymentReference', 'amount'];
-    const missingFields = requiredFields.filter((field) => !payload[field]);
-
-    if (missingFields.length > 0) {
-      return {
-        valid: false,
-        error: `Missing required fields: ${missingFields.join(', ')}`,
-      };
-    }
-
-    if (!payload.amount || typeof payload.amount.value !== 'number') {
-      return {
-        valid: false,
-        error: 'Invalid amount structure: amount.value must be a number',
-      };
-    }
-
-    if (!payload.amount.currency || typeof payload.amount.currency !== 'string') {
-      return {
-        valid: false,
-        error: 'Invalid amount structure: amount.currency must be a string',
-      };
-    }
-
-    if (payload.amount.value <= 0) {
-      return {
-        valid: false,
-        error: 'Invalid amount: value must be positive',
-      };
-    }
-
-    if (typeof payload.paymentReference !== 'string' || payload.paymentReference.length === 0) {
-      return {
-        valid: false,
-        error: 'Invalid paymentReference: must be a non-empty string',
-      };
-    }
-
-    return {
-      valid: true,
-      payload: {
-        orderRef: payload.orderRef,
-        paymentReference: payload.paymentReference,
-        amount: {
-          value: payload.amount.value,
-          currency: payload.amount.currency,
-        },
-        retailerId: payload.retailerId,
-        merchantReference: payload.merchantReference,
-      },
-    };
-  }
-
-  /**
-   * Extract payment context from validated payload
-   */
-  extractPaymentContext(payload: WebhookPayload) {
-    return {
-      orderRef: payload.orderRef,
-      paymentReference: payload.paymentReference,
-      amount: payload.amount,
-      retailerId: payload.retailerId,
-      merchantReference: payload.merchantReference || payload.orderRef,
-      triggerSource: payload.triggerSource,
-      orderStatus: payload.orderStatus,
-      refundReason: payload.refundReason,
-      cancelReason: payload.cancelReason,
-      reauthReason: payload.reauthReason,
-    };
-  }
-
-  /**
-   * Validate trigger source (ensures webhook called from correct workflow)
-   */
-  validateTriggerSource(
-    payload: any,
-    allowedSources: string[],
-    requiredSource?: string
-  ): ValidationResult {
-    const source = payload.triggerSource;
-
-    if (!source) {
-      return {
-        valid: false,
-        error: 'Missing triggerSource in payload',
-      };
-    }
-
-    if (requiredSource && source !== requiredSource) {
-      return {
-        valid: false,
-        error: `Invalid trigger source: expected ${requiredSource}, got ${source}`,
-      };
-    }
-
-    if (!allowedSources.includes(source)) {
-      return {
-        valid: false,
-        error: `Trigger source not allowed: ${source}. Allowed: ${allowedSources.join(', ')}`,
-      };
-    }
-
-    return {
-      valid: true,
-    };
-  }
-}
-```
-
----
-
-### File: `src/services/idempotency.service.ts`
-
-```typescript
-/**
- * Idempotency Service
- *
- * Tracks processed payments to prevent duplicate operations
- */
-
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-import type { Logger } from '@fluentcommerce/fc-connect-sdk';
-
-export interface IdempotencyRecord {
-  operationType: 'capture' | 'refund' | 'cancel' | 'reauth';
-  paymentReference: string;
-  processedAt: string;
-  resultReference: string;
-  amount?: number;
-  currency?: string;
-}
-
-export class IdempotencyService {
-  constructor(
-    private kvAdapter: VersoriKVAdapter,
-    private log: Logger
-  ) {}
-
-  /**
-   * Generate idempotency key
-   */
-  private getIdempotencyKey(
-    operationType: string,
-    paymentReference: string
-  ): string[] {
-    return [`payment:${operationType}:${paymentReference}`];
-  }
-
-  /**
-   * Check if operation was already processed
-   */
-  async checkAndStore(
-    operationType: 'capture' | 'refund' | 'cancel' | 'reauth',
-    paymentReference: string,
-    resultReference: string,
-    amount?: { value: number; currency: string }
-  ): Promise<{ alreadyProcessed: boolean; existingRecord?: IdempotencyRecord }> {
-    const key = this.getIdempotencyKey(operationType, paymentReference);
-    const existing = await this.kvAdapter.get(key);
-
-    if (existing?.value) {
-      const record = typeof existing.value === 'string'
-        ? JSON.parse(existing.value)
-        : existing.value;
-
-      this.log.info('✅ [Idempotency] Operation already processed', {
-        operationType,
-        paymentReference,
-        processedAt: record.processedAt,
-      });
-
-      return {
-        alreadyProcessed: true,
-        existingRecord: record,
-      };
-    }
-
-    // Store new record
-    const record: IdempotencyRecord = {
-      operationType,
-      paymentReference,
-      processedAt: new Date().toISOString(),
-      resultReference,
-      amount: amount?.value,
-      currency: amount?.currency,
-    };
-
-    await this.kvAdapter.set(key, JSON.stringify(record));
-
-    this.log.info('✅ [Idempotency] Operation recorded', {
-      operationType,
-      paymentReference,
-      resultReference,
-    });
-
-    return {
-      alreadyProcessed: false,
-    };
-  }
-
-  /**
-   * Get existing record (without storing)
-   */
-  async getExisting(
-    operationType: 'capture' | 'refund' | 'cancel' | 'reauth',
-    paymentReference: string
-  ): Promise<IdempotencyRecord | null> {
-    const key = this.getIdempotencyKey(operationType, paymentReference);
-    const existing = await this.kvAdapter.get(key);
-
-    if (existing?.value) {
-      return typeof existing.value === 'string'
-        ? JSON.parse(existing.value)
-        : existing.value;
-    }
-
-    return null;
-  }
-}
-```
-
----
-
-### File: `src/services/payment-event.service.ts`
-
-```typescript
-/**
- * Payment Event Service
- *
- * Maps payment provider responses to Fluent event format and sends events
- */
-
-import type { FluentClient, Logger } from '@fluentcommerce/fc-connect-sdk';
-import type {
-  CaptureResult,
-  RefundResult,
-  CancelResult,
-  ReauthResult,
-  PaymentContext,
-} from './payment-provider.service';
-
-export class PaymentEventService {
-  constructor(
-    private client: FluentClient,
-    private log: Logger
-  ) {}
-
-  /**
-   * Send payment capture event to Fluent Commerce
-   */
-  async sendCaptureEvent(
-    result: CaptureResult,
-    context: PaymentContext
-  ): Promise<void> {
-    this.log.info('📤 [Event] Sending payment capture event', {
-      orderRef: context.orderRef,
-      paymentReference: result.paymentReference,
-    });
-
-    const eventPayload = {
-      name: 'PaymentCaptured',
-      entityType: 'ORDER',
-      entityRef: context.orderRef,
-      data: {
-        paymentReference: result.paymentReference,
-        originalPaymentReference: context.paymentReference,
-        amount: result.amount.value,
-        currency: result.amount.currency,
-        capturedAt: result.capturedAt,
-        resultCode: result.resultCode,
-        merchantReference: context.merchantReference,
-      },
-    };
-
-    await this.client.sendEvent(eventPayload);
-  }
-
-  /**
-   * Send payment refund event to Fluent Commerce
-   */
-  async sendRefundEvent(
-    result: RefundResult,
-    context: PaymentContext
-  ): Promise<void> {
-    this.log.info('📤 [Event] Sending payment refund event', {
-      orderRef: context.orderRef,
-      refundReference: result.refundReference,
-    });
-
-    const eventPayload = {
-      name: 'PaymentRefunded',
-      entityType: 'ORDER',
-      entityRef: context.orderRef,
-      data: {
-        refundReference: result.refundReference,
-        originalPaymentReference: result.originalPaymentReference,
-        amount: result.amount.value,
-        currency: result.amount.currency,
-        refundType: result.refundType || 'FULL',
-        refundedAt: result.refundedAt,
-        merchantReference: context.merchantReference,
-      },
-    };
-
-    await this.client.sendEvent(eventPayload);
-  }
-
-  /**
-   * Send payment cancellation event to Fluent Commerce
-   */
-  async sendCancelEvent(
-    result: CancelResult,
-    context: PaymentContext
-  ): Promise<void> {
-    this.log.info('📤 [Event] Sending payment cancellation event', {
-      orderRef: context.orderRef,
-      cancellationReference: result.cancellationReference,
-    });
-
-    const eventPayload = {
-      name: 'PaymentAuthorizationCancelled',
-      entityType: 'ORDER',
-      entityRef: context.orderRef,
-      data: {
-        cancellationReference: result.cancellationReference,
-        originalPaymentReference: result.originalPaymentReference,
-        cancelledAt: result.cancelledAt,
-        merchantReference: context.merchantReference,
-      },
-    };
-
-    await this.client.sendEvent(eventPayload);
-  }
-
-  /**
-   * Send payment reauthorization event to Fluent Commerce
-   */
-  async sendReauthEvent(
-    result: ReauthResult,
-    context: PaymentContext
-  ): Promise<void> {
-    this.log.info('📤 [Event] Sending payment reauthorization event', {
-      orderRef: context.orderRef,
-      reauthReference: result.reauthReference,
-    });
-
-    const eventPayload = {
-      name: 'PaymentReauthorized',
-      entityType: 'ORDER',
-      entityRef: context.orderRef,
-      data: {
-        reauthReference: result.reauthReference,
-        originalPaymentReference: result.originalPaymentReference,
-        amount: result.amount.value,
-        currency: result.amount.currency,
-        reauthorizedAt: result.reauthorizedAt,
-        expiryDate: result.expiryDate,
-        merchantReference: context.merchantReference,
-      },
-    };
-
-    await this.client.sendEvent(eventPayload);
-  }
-}
-```
-
----
-
-### File: `src/services/payment-provider-factory.service.ts`
-
-```typescript
-/**
- * Payment Provider Factory
- *
- * Creates payment provider service based on configuration
- * Easy to swap providers: Adyen → Stripe → PayPal
- */
-
-import type { Logger } from '@fluentcommerce/fc-connect-sdk';
-import type { PaymentProviderService } from './payment-provider.service';
-import { AdyenPaymentProviderService } from './adyen-provider.service';
-// Future: import { StripePaymentProviderService } from './stripe-provider.service';
-
-export class PaymentProviderFactory {
-  /**
-   * Create payment provider service
-   *
-   * @param provider - Provider name (adyen, stripe, paypal)
-   * @param config - Provider-specific configuration
-   * @param log - Logger instance
-   */
-  static createProvider(
-    provider: string,
-    config: any,
-    log: Logger
-  ): PaymentProviderService {
-    switch (provider.toLowerCase()) {
-      case 'adyen':
-        return new AdyenPaymentProviderService(
-          config.apiKey,
-          config.environment,
-          config.merchantAccount,
-          log
-        );
-
-      // Future: Stripe implementation
-      // case 'stripe':
-      //   return new StripePaymentProviderService(
-      //     config.secretKey,
-      //     config.environment,
-      //     log
-      //   );
-
-      // Future: PayPal implementation
-      // case 'paypal':
-      //   return new PayPalPaymentProviderService(
-      //     config.clientId,
-      //     config.clientSecret,
-      //     config.environment,
-      //     log
-      //   );
-
-      default:
-        throw new Error(`Unsupported payment provider: ${provider}`);
-    }
-  }
-}
-```
-
----
-
-### File: `src/workflows/webhook/payment-capture.ts`
-
-```typescript
-/**
- * ═══════════════════════════════════════════════════════════════
- * 🚀 PAYMENT CAPTURE WEBHOOK
- * ═══════════════════════════════════════════════════════════════
- *
- * Intercepts Fluent Workflow webhook for payment capture
- * 
- * TRIGGER SOURCE: ORDER/FULFILLMENT Workflow (Rubix)
- * - Triggered when order is ready to ship
- * - Validates triggerSource: ORDER_FULFILLMENT
- * - Note: Rubix workflow ensures order/payment is in correct state before calling
- * 
- * Flow:
- * - Validates webhook payload and signature
- * - Validates trigger source (must be ORDER_FULFILLMENT)
- * - Calls payment provider Capture API
- * - Sends event to Fluent Commerce Event API
- * - Handles idempotency
- * 
- * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
- */
-
-import { webhook } from '@versori/run';
-import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-import { WebhookValidationService } from '../../services/webhook-validation.service';
-import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
-import { PaymentEventService } from '../../services/payment-event.service';
-import { IdempotencyService } from '../../services/idempotency.service';
-import type { PaymentProviderService } from '../../services/payment-provider.service';
-
-/**
- * Background processing function for payment capture
- * Handles all long-running operations (payment gateway API, event sending)
- */
-async function processPaymentCapture(ctx: any, executionStartTime: number): Promise<void> {
-  const { log, activation, connections } = ctx;
-
-  try {
-    log.info('🔄 [BACKGROUND] Starting background payment capture processing', {
-      correlationId: activation.id,
-    });
-
-    // =================================================================
-    // STEP 1: CONFIGURATION VALIDATION
-    // =================================================================
-
-    if (!connections?.fluent_commerce) {
-      log.error('❌ [BACKGROUND] Missing fluent_commerce connection');
-      return;
-    }
-
-    const retailerId = activation.getVariable('fluentRetailerId');
-    const paymentProvider = activation.getVariable('paymentProvider') || 'adyen';
-    const paymentProviderEnv = (activation.getVariable('paymentProviderEnvironment') || 'test') as 'test' | 'live';
-    const enableIdempotency = activation.getVariable('enableIdempotency') !== 'false';
-
-    // Get payment provider API key
-    let apiKey: string | undefined;
-    if (connections.payment_gateway?.credentials?.api_key) {
-      apiKey = connections.payment_gateway.credentials.api_key;
-    } else if (connections.adyen_payment_gateway?.credentials?.api_key) {
-      apiKey = connections.adyen_payment_gateway.credentials.api_key;
-    } else {
-      apiKey = activation.getVariable('paymentGatewayApiKey') || activation.getVariable('adyenApiKey');
-    }
-
-    if (!apiKey) {
-      log.error('❌ [BACKGROUND] Missing payment gateway API key');
-      return;
-    }
-
-    const merchantAccount = activation.getVariable('adyenMerchantAccount');
-    if (!merchantAccount && paymentProvider === 'adyen') {
-      log.error('❌ [BACKGROUND] Missing adyenMerchantAccount');
-      return;
-    }
-
-    // =================================================================
-    // STEP 2: PAYLOAD VALIDATION
-    // =================================================================
-
-    const rawPayload = activation.body || ctx.data;
-    const payload = typeof rawPayload === 'string' ? JSON.parse(rawPayload) : rawPayload;
-    const validator = new WebhookValidationService(log);
-    const validation = validator.validatePayload(payload);
-
-    if (!validation.valid) {
-      log.error('❌ [BACKGROUND] Invalid payload', { error: validation.error });
-      return;
-    }
-
-    const paymentContext = validator.extractPaymentContext(validation.payload!);
-    const finalRetailerId = paymentContext.retailerId || retailerId;
-
-    if (!finalRetailerId) {
-      log.error('❌ [BACKGROUND] Missing retailerId');
-      return;
-    }
-
-    // =================================================================
-    // STEP 2.5: VALIDATE TRIGGER SOURCE (Capture must come from ORDER/FULFILLMENT)
-    // =================================================================
-
-    const validateTriggerSource = activation.getVariable('validateTriggerSource') !== 'false';
-    const allowedSources = (activation.getVariable('allowedTriggerSources') || 'ORDER_FULFILLMENT,PAYMENT_ENTITY')
-      .split(',').map(s => s.trim());
-
-    if (validateTriggerSource) {
-      const triggerValidation = validator.validateTriggerSource(
-        payload,
-        allowedSources,
-        'ORDER_FULFILLMENT'  // Capture MUST come from ORDER_FULFILLMENT
-      );
-
-      if (!triggerValidation.valid) {
-        log.error('❌ [BACKGROUND] Invalid trigger source', {
-          triggerSource: payload.triggerSource,
-          expected: 'ORDER_FULFILLMENT',
-          error: triggerValidation.error,
-        });
-        return;
-      }
-
-      log.info('✅ [BACKGROUND] Trigger source validated', {
-        triggerSource: payload.triggerSource,
-      });
-    }
-
-    // =================================================================
-    // STEP 3: INITIALIZE SERVICES
-    // =================================================================
-
-    const fluentClient = await createClient(ctx, { validateConnection: true });
-    await fluentClient.setRetailerId(finalRetailerId);
-
-    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
-    const idempotencyService = new IdempotencyService(kvAdapter, log);
-
-    // Create payment provider service (easily swappable)
-    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
-      paymentProvider,
-      {
-        apiKey,
-        environment: paymentProviderEnv,
-        merchantAccount,
-      },
-      log
-    );
-
-    const eventService = new PaymentEventService(fluentClient, log);
-
-    // =================================================================
-    // STEP 4: IDEMPOTENCY CHECK
-    // =================================================================
-
-    if (enableIdempotency) {
-      const idempotencyCheck = await idempotencyService.checkAndStore(
-        'capture',
-        paymentContext.paymentReference,
-        '', // Will be updated after successful capture
-        paymentContext.amount
-      );
-
-      if (idempotencyCheck.alreadyProcessed && idempotencyCheck.existingRecord) {
-        log.info('✅ [BACKGROUND] Payment already processed (idempotency)', {
-          paymentReference: paymentContext.paymentReference,
-          resultReference: idempotencyCheck.existingRecord.resultReference,
-        });
-        return; // Already processed, exit early
-      }
-    }
-
-    // =================================================================
-    // STEP 5: CALL PAYMENT PROVIDER
-    // =================================================================
-
-    log.info('💳 [BACKGROUND] Calling payment provider', {
-      provider: paymentProviderService.getProviderName(),
-      paymentReference: paymentContext.paymentReference,
-    });
-
-    const captureResult = await paymentProviderService.capturePayment(
-      paymentContext.paymentReference,
-      paymentContext.amount,
-      {
-        ...paymentContext,
-        retailerId: finalRetailerId,
-      }
-    );
-
-    if (!captureResult.success) {
-      log.error('❌ [BACKGROUND] Payment capture failed', {
-        providerError: captureResult.error,
-        paymentReference: paymentContext.paymentReference,
-      });
-      return; // Failed, exit
-    }
-
-    // =================================================================
-    // STEP 6: UPDATE IDEMPOTENCY KEY
-    // =================================================================
-
-    if (enableIdempotency) {
-      await idempotencyService.checkAndStore(
-        'capture',
-        paymentContext.paymentReference,
-        captureResult.paymentReference,
-        captureResult.amount
-      );
-    }
-
-    // =================================================================
-    // STEP 7: SEND EVENT TO FLUENT
-    // =================================================================
-
-    try {
-      await eventService.sendCaptureEvent(captureResult, {
-        ...paymentContext,
-        retailerId: finalRetailerId,
-      });
-      log.info('✅ [BACKGROUND] Payment event sent to Fluent', {
-        paymentReference: captureResult.paymentReference,
-      });
-    } catch (error: any) {
-      log.error('❌ [BACKGROUND] Event send failed (non-blocking)', {
-        error: error.message,
-        paymentReference: captureResult.paymentReference,
-        note: 'Payment capture succeeded, but event failed - will be retried',
-      });
-      // Continue - event failure doesn't block success
-    }
-
-    // =================================================================
-    // STEP 8: LOG SUCCESS
-    // =================================================================
-
-    const duration = Date.now() - executionStartTime;
-    log.info('✅ [BACKGROUND] Payment capture completed successfully', {
-      paymentReference: paymentContext.paymentReference,
-      resultReference: captureResult.paymentReference,
-      provider: paymentProviderService.getProviderName(),
-      duration: `${duration}ms`,
-    });
-  } catch (error: any) {
-    log.error('❌ [BACKGROUND] Payment capture failed', {
-      error: error.message,
-      stack: error.stack,
-      errorType: error instanceof Error ? error.constructor.name : typeof error,
-    });
-  }
-}
-
-/**
- * Payment Capture Webhook Handler
- * Uses sync + fire-and-forget pattern for fast response
- */
-export const paymentCapture = webhook('payment-capture', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-}, async (ctx) => {
-  const { log, activation, connections } = ctx;
-  const executionStartTime = Date.now();
-
-  log.info('🚀 [WEBHOOK] Received payment capture webhook', {
-    correlationId: activation.id,
-    timestamp: new Date().toISOString(),
-  });
-
-  // =================================================================
-  // QUICK VALIDATION (Synchronous, ~10-50ms)
-  // =================================================================
-
-  if (!connections?.fluent_commerce) {
-    log.error('❌ [WEBHOOK] Missing fluent_commerce connection');
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Missing fluent_commerce connection',
-        recommendation: 'Configure fluent_commerce connection in Connections section',
-      },
-    };
-  }
-
-  const retailerId = activation.getVariable('fluentRetailerId');
-  const paymentProvider = activation.getVariable('paymentProvider') || 'adyen';
-  const webhookSecret = activation.getVariable('webhookSecret');
-
-  // Quick payload validation
-  const rawPayload = activation.body || ctx.data;
-  const payload = typeof rawPayload === 'string' ? JSON.parse(rawPayload) : rawPayload;
-
-  if (!payload.paymentReference || !payload.amount) {
-    log.error('❌ [WEBHOOK] Invalid payload', {
-      hasPaymentReference: !!payload.paymentReference,
-      hasAmount: !!payload.amount,
-    });
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'Invalid payload: missing paymentReference or amount',
-      },
-    };
-  }
-
-  // Quick webhook signature validation (if configured)
-  if (webhookSecret) {
-    const payloadString = typeof rawPayload === 'string' ? rawPayload : JSON.stringify(rawPayload);
-    const signature = activation.headers?.['x-webhook-signature'] ||
-                     activation.headers?.['webhook-signature'] ||
-                     activation.headers?.['signature'];
-
-    if (signature) {
-      const validator = new WebhookValidationService(log);
-      const isValid = validator.validateSignature(payloadString, signature, webhookSecret);
-
-      if (!isValid) {
-        log.error('❌ [WEBHOOK] Invalid webhook signature');
-        return {
-          status: 401,
-          body: {
-            success: false,
-            error: 'Invalid webhook signature',
-          },
-        };
-      }
-    }
-  }
-
-  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
-    paymentReference: payload.paymentReference,
-  });
-
-  // ✅ Fire-and-forget: Start background processing WITHOUT await
-  // The promise continues execution after we return the response
-  processPaymentCapture(ctx, executionStartTime)
-    .then(() => {
-      log.info('✅ [BACKGROUND] Payment capture processing completed successfully', {
-        correlationId: activation.id,
-      });
-    })
-    .catch((error: unknown) => {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      log.error('❌ [BACKGROUND] Payment capture processing failed', {
-        correlationId: activation.id,
-        error: errorMessage,
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : typeof error,
-      });
-    });
-
-  // Return immediately (response sent with this return value)
-  return {
-    status: 200,
-    body: {
-      success: true,
-      message: 'Payment capture started in background',
-      paymentReference: payload.paymentReference,
-      timestamp: new Date().toISOString(),
-    },
-  };
-});
-```
-
----
-
-### File: `src/workflows/webhook/payment-refund.ts`
-
-```typescript
-/**
- * ═══════════════════════════════════════════════════════════════
- * 🚀 PAYMENT REFUND WEBHOOK
- * ═══════════════════════════════════════════════════════════════
- *
- * Intercepts Fluent Workflow webhook for payment refund
- * 
- * TRIGGER SOURCE: Payment Entity Orchestration (Rubix)
- * - Triggered when refund is approved (after RMA processing, order cancellation)
- * - Validates triggerSource: PAYMENT_ENTITY
- * - Note: Rubix workflow ensures payment is in correct state before calling
- * 
- * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
- */
-
-import { webhook } from '@versori/run';
-import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-import { WebhookValidationService } from '../../services/webhook-validation.service';
-import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
-import { PaymentEventService } from '../../services/payment-event.service';
-import { IdempotencyService } from '../../services/idempotency.service';
-import type { PaymentProviderService } from '../../services/payment-provider.service';
-
-export const paymentRefund = webhook('payment-refund', async (ctx) => {
-  const { log, activation, connections } = ctx;
-  const executionStartTime = Date.now();
-
-  try {
-    log.info('🚀 [PaymentRefund] Processing payment refund webhook', {
-      correlationId: activation.id,
-    });
-
-    // Similar structure to payment-capture.ts, but calls refundPayment()
-    // ... (same configuration validation, webhook validation, etc.)
-
-    const fluentClient = await createClient(ctx, { validateConnection: true });
-    await fluentClient.setRetailerId(finalRetailerId);
-
-    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
-    const idempotencyService = new IdempotencyService(kvAdapter, log);
-
-    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
-      paymentProvider,
-      { apiKey, environment: paymentProviderEnv, merchantAccount },
-      log
-    );
-
-    const eventService = new PaymentEventService(fluentClient, log);
-
-    // Idempotency check
-    if (enableIdempotency) {
-      const idempotencyCheck = await idempotencyService.checkAndStore(
-        'refund',
-        paymentContext.paymentReference,
-        '',
-        paymentContext.amount
-      );
-
-      if (idempotencyCheck.alreadyProcessed) {
-        return {
-          status: 200,
-          body: {
-            success: true,
-            alreadyProcessed: true,
-            refundReference: idempotencyCheck.existingRecord!.resultReference,
-          },
-        };
-      }
-    }
-
-    // Call payment provider
-    const refundResult = await paymentProviderService.refundPayment(
-      paymentContext.paymentReference,
-      paymentContext.amount,
-      { ...paymentContext, retailerId: finalRetailerId }
-    );
-
-    if (!refundResult.success) {
-      return {
-        status: 502,
-        body: {
-          success: false,
-          error: 'Payment refund failed',
-          providerError: refundResult.error,
-        },
-      };
-    }
-
-    // Update idempotency
-    if (enableIdempotency) {
-      await idempotencyService.checkAndStore(
-        'refund',
-        paymentContext.paymentReference,
-        refundResult.refundReference,
-        refundResult.amount
-      );
-    }
-
-    // Send event
-    await eventService.sendRefundEvent(refundResult, {
-      ...paymentContext,
-      retailerId: finalRetailerId,
-    });
-
-    const duration = Date.now() - executionStartTime;
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        refundReference: refundResult.refundReference,
-        originalPaymentReference: refundResult.originalPaymentReference,
-        amount: refundResult.amount.value,
-        currency: refundResult.amount.currency,
-        refundType: refundResult.refundType,
-        refundedAt: refundResult.refundedAt,
-        provider: paymentProviderService.getProviderName(),
-        duration: `${duration}ms`,
-      },
-    };
-  } catch (error: any) {
-    log.error('❌ [PaymentRefund] Unexpected error', { error: error.message });
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Internal server error',
-        message: error.message,
-      },
-    };
-  }
-});
-```
-
----
-
-### File: `src/workflows/webhook/payment-auth-cancel.ts`
-
-```typescript
-/**
- * ═══════════════════════════════════════════════════════════════
- * 🚀 PAYMENT AUTH CANCEL WEBHOOK
- * ═══════════════════════════════════════════════════════════════
- *
- * Intercepts Fluent Workflow webhook for authorization cancellation
- * 
- * TRIGGER SOURCE: Payment Entity Orchestration (Rubix)
- * - Triggered when order is cancelled before capture
- * - Validates triggerSource: PAYMENT_ENTITY
- * - Note: Rubix workflow ensures payment is in correct state before calling
- * 
- * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
- */
-
-import { webhook } from '@versori/run';
-import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-import { WebhookValidationService } from '../../services/webhook-validation.service';
-import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
-import { PaymentEventService } from '../../services/payment-event.service';
-import { IdempotencyService } from '../../services/idempotency.service';
-import type { PaymentProviderService } from '../../services/payment-provider.service';
-
-export const paymentAuthCancel = webhook('payment-auth-cancel', async (ctx) => {
-  const { log, activation, connections } = ctx;
-  const executionStartTime = Date.now();
-
-  try {
-    log.info('🚀 [PaymentAuthCancel] Processing authorization cancellation webhook', {
-      correlationId: activation.id,
-    });
-
-    // Similar structure, but:
-    // - No amount validation (cancellation doesn't need amount)
-    // - Calls cancelAuthorization()
-    // - Sends PaymentAuthorizationCancelled event
-
-    // ... (configuration validation, webhook validation similar to capture)
-
-    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
-      paymentProvider,
-      { apiKey, environment: paymentProviderEnv, merchantAccount },
-      log
-    );
-
-    const cancelResult = await paymentProviderService.cancelAuthorization(
-      paymentContext.paymentReference,
-      { ...paymentContext, retailerId: finalRetailerId }
-    );
-
-    if (!cancelResult.success) {
-      return {
-        status: 502,
-        body: {
-          success: false,
-          error: 'Authorization cancellation failed',
-          providerError: cancelResult.error,
-        },
-      };
-    }
-
-    await eventService.sendCancelEvent(cancelResult, {
-      ...paymentContext,
-      retailerId: finalRetailerId,
-    });
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        cancellationReference: cancelResult.cancellationReference,
-        originalPaymentReference: cancelResult.originalPaymentReference,
-        cancelledAt: cancelResult.cancelledAt,
-        provider: paymentProviderService.getProviderName(),
-      },
-    };
-  } catch (error: any) {
-    log.error('❌ [PaymentAuthCancel] Unexpected error', { error: error.message });
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Internal server error',
-        message: error.message,
-      },
-    };
-  }
-});
-```
-
----
-
-### File: `src/workflows/webhook/payment-reauth.ts`
-
-```typescript
-/**
- * ═══════════════════════════════════════════════════════════════
- * 🚀 PAYMENT REAUTH WEBHOOK
- * ═══════════════════════════════════════════════════════════════
- *
- * Intercepts Fluent Workflow webhook for payment reauthorization
- * 
- * TRIGGER SOURCE: Payment Entity Orchestration (Rubix)
- * - Triggered when authorization expires or needs extension
- * - Validates triggerSource: PAYMENT_ENTITY
- * - Note: Rubix workflow ensures authorization is in correct state before calling
- * 
- * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
- */
-
-import { webhook } from '@versori/run';
-import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-import { WebhookValidationService } from '../../services/webhook-validation.service';
-import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
-import { PaymentEventService } from '../../services/payment-event.service';
-import { IdempotencyService } from '../../services/idempotency.service';
-import type { PaymentProviderService } from '../../services/payment-provider.service';
-
-export const paymentReauth = webhook('payment-reauth', async (ctx) => {
-  const { log, activation, connections } = ctx;
-  const executionStartTime = Date.now();
-
-  try {
-    log.info('🚀 [PaymentReauth] Processing payment reauthorization webhook', {
-      correlationId: activation.id,
-    });
-
-    // Similar structure to capture, but:
-    // - Calls reauthorizePayment()
-    // - Sends PaymentReauthorized event
-
-    // ... (configuration validation, webhook validation similar to capture)
-
-    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
-      paymentProvider,
-      { apiKey, environment: paymentProviderEnv, merchantAccount },
-      log
-    );
-
-    const reauthResult = await paymentProviderService.reauthorizePayment(
-      paymentContext.paymentReference,
-      paymentContext.amount,
-      { ...paymentContext, retailerId: finalRetailerId }
-    );
-
-    if (!reauthResult.success) {
-      return {
-        status: 502,
-        body: {
-          success: false,
-          error: 'Payment reauthorization failed',
-          providerError: reauthResult.error,
-        },
-      };
-    }
-
-    await eventService.sendReauthEvent(reauthResult, {
-      ...paymentContext,
-      retailerId: finalRetailerId,
-    });
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        reauthReference: reauthResult.reauthReference,
-        originalPaymentReference: reauthResult.originalPaymentReference,
-        amount: reauthResult.amount.value,
-        currency: reauthResult.amount.currency,
-        reauthorizedAt: reauthResult.reauthorizedAt,
-        expiryDate: reauthResult.expiryDate,
-        provider: paymentProviderService.getProviderName(),
-      },
-    };
-  } catch (error: any) {
-    log.error('❌ [PaymentReauth] Unexpected error', { error: error.message });
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Internal server error',
-        message: error.message,
-      },
-    };
-  }
-});
-```
-
----
-
-## How to Swap Payment Providers
-
-### Current: Adyen → Stripe
-
-**Step 1**: Create `src/services/stripe-provider.service.ts`
-
-```typescript
-import type { PaymentProviderService } from './payment-provider.service';
-// Implement StripePaymentProviderService with same interface
-```
-
-**Step 2**: Update `PaymentProviderFactory`
-
-```typescript
-case 'stripe':
-  return new StripePaymentProviderService(
-    config.secretKey,
-    config.environment,
-    log
-  );
-```
-
-**Step 3**: Update Activation Variables
-
-```bash
-paymentProvider=stripe                    # Change from adyen to stripe
-stripeSecretKey=sk_test_...              # Add Stripe config
-```
-
-**That's it!** All 4 webhooks automatically use Stripe. No changes needed to webhook code.
-
----
-
-## Expected Webhook Payloads
-
-### Capture Payload (from ORDER/FULFILLMENT Workflow)
-
-```json
-{
-  "orderRef": "ORDER-12345",
-  "paymentReference": "8826162495174985",
-  "amount": {
-    "value": 10000,
-    "currency": "USD"
-  },
-  "retailerId": "2",
-  "merchantReference": "ORDER-12345",
-  "triggerSource": "ORDER_FULFILLMENT",
-  "orderStatus": "READY_TO_SHIP"
-}
-```
-
-### Refund Payload (from Payment Entity Orchestration)
-
-```json
-{
-  "orderRef": "ORDER-12345",
-  "paymentReference": "8826162495174985",
-  "amount": {
-    "value": 10000,
-    "currency": "USD"
-  },
-  "retailerId": "2",
-  "merchantReference": "ORDER-12345",
-  "triggerSource": "PAYMENT_ENTITY",
-  "refundReason": "RETURN_APPROVED",
-  "rmaRef": "RMA-67890",
-  "refundType": "FULL"
-}
-```
-
-### Auth Cancel Payload (from Payment Entity Orchestration)
-
-```json
-{
-  "orderRef": "ORDER-12345",
-  "paymentReference": "8826162495174985",
-  "retailerId": "2",
-  "merchantReference": "ORDER-12345",
-  "triggerSource": "PAYMENT_ENTITY",
-  "cancelReason": "ORDER_CANCELLED",
-  "orderStatus": "CANCELLED"
-}
-```
-
-### ReAuth Payload (from Payment Entity Orchestration)
-
-```json
-{
-  "orderRef": "ORDER-12345",
-  "paymentReference": "8826162495174985",
-  "amount": {
-    "value": 10000,
-    "currency": "USD"
-  },
-  "retailerId": "2",
-  "merchantReference": "ORDER-12345",
-  "triggerSource": "PAYMENT_ENTITY",
-  "reauthReason": "AUTHORIZATION_EXPIRING"
-}
-```
-
----
-
-## Expected Events Sent to Fluent Commerce
-
-### PaymentCaptured
-
-```json
-{
-  "name": "PaymentCaptured",
-  "entityType": "ORDER",
-  "entityRef": "ORDER-12345",
-  "data": {
-    "paymentReference": "8826162495174985",
-    "originalPaymentReference": "8826162495174985",
-    "amount": 10000,
-    "currency": "USD",
-    "capturedAt": "2025-01-22T12:34:56.789Z",
-    "resultCode": "Received",
-    "merchantReference": "ORDER-12345"
-  }
-}
-```
-
-### PaymentRefunded
-
-```json
-{
-  "name": "PaymentRefunded",
-  "entityType": "ORDER",
-  "entityRef": "ORDER-12345",
-  "data": {
-    "refundReference": "8826162495174986",
-    "originalPaymentReference": "8826162495174985",
-    "amount": 10000,
-    "currency": "USD",
-    "refundType": "FULL",
-    "refundedAt": "2025-01-22T12:34:56.789Z",
-    "merchantReference": "ORDER-12345"
-  }
-}
-```
-
-### PaymentAuthorizationCancelled
-
-```json
-{
-  "name": "PaymentAuthorizationCancelled",
-  "entityType": "ORDER",
-  "entityRef": "ORDER-12345",
-  "data": {
-    "cancellationReference": "8826162495174987",
-    "originalPaymentReference": "8826162495174985",
-    "cancelledAt": "2025-01-22T12:34:56.789Z",
-    "merchantReference": "ORDER-12345"
-  }
-}
-```
-
-### PaymentReauthorized
-
-```json
-{
-  "name": "PaymentReauthorized",
-  "entityType": "ORDER",
-  "entityRef": "ORDER-12345",
-  "data": {
-    "reauthReference": "8826162495174988",
-    "originalPaymentReference": "8826162495174985",
-    "amount": 10000,
-    "currency": "USD",
-    "reauthorizedAt": "2025-01-22T12:34:56.789Z",
-    "expiryDate": "2025-02-22T12:34:56.789Z",
-    "merchantReference": "ORDER-12345"
-  }
-}
-```
-
----
-
-## Testing Checklist
-
-### 1. Configuration Testing
-- [ ] Fluent Commerce connection configured
-- [ ] Payment gateway connection configured (Adyen)
-- [ ] All activation variables set
-- [ ] Provider can be swapped (test Stripe if implemented)
-
-### 2. Webhook Testing (All 4)
-- [ ] Capture webhook works
-- [ ] Refund webhook works
-- [ ] Auth Cancel webhook works
-- [ ] ReAuth webhook works
-
-### 3. Idempotency Testing
-- [ ] Duplicate capture calls return same result
-- [ ] Duplicate refund calls return same result
-- [ ] Duplicate cancel calls return same result
-- [ ] Duplicate reauth calls return same result
-
-### 4. Event Testing
-- [ ] Capture event sent to Fluent
-- [ ] Refund event sent to Fluent
-- [ ] Cancel event sent to Fluent
-- [ ] ReAuth event sent to Fluent
-
-### 5. Provider Swap Testing (Future)
-- [ ] Switch to Stripe provider
-- [ ] Verify all 4 flows work with Stripe
-- [ ] Verify events still sent correctly
-
----
-
-## Deployment Steps
-
-1. **Set up Connections**:
-   - Configure `fluent_commerce` connection (OAuth2)
-   - Configure `payment_gateway` or `adyen_payment_gateway` connection (API key)
-
-2. **Set Activation Variables**:
-   - `fluentRetailerId`
-   - `paymentProvider` (default: `adyen`)
-   - `paymentProviderEnvironment` (test/live)
-   - `adyenMerchantAccount` (if using Adyen)
-   - `webhookSecret` (optional)
-
-3. **Deploy Workflow**:
-   ```bash
-   cd versori-payment-gateway-integration
-   npm install
-   versori deploy
-   ```
-
-4. **Configure Fluent Workflows**:
-   - Point webhook URLs to Versori endpoints:
-     - `/payment-capture`
-     - `/payment-refund`
-     - `/payment-auth-cancel`
-     - `/payment-reauth`
-
-5. **Test End-to-End**:
-   - Test each webhook from Fluent Workflow
-   - Verify payment provider API calls
-   - Verify events sent to Fluent Commerce
-   - Check Versori logs for errors
-
----
-
-## Key Benefits of This Architecture
-
-✅ **Single Connector** - All 4 flows in one document/workflow  
-✅ **Provider Agnostic** - Easy to swap Adyen → Stripe (change one service)  
-✅ **DRY Principle** - Shared services used by all webhooks  
-✅ **Maintainable** - Clear separation of concerns  
-✅ **Testable** - Each layer can be tested independently  
-✅ **Scalable** - Easy to add new payment providers or operations  
-
----
-
-## Future Enhancements
-
-### Adding Stripe Support
-
-1. Create `StripePaymentProviderService` implementing `PaymentProviderService`
-2. Add case to `PaymentProviderFactory`
-3. Update activation variables
-4. **Done!** All 4 webhooks automatically use Stripe
-
-### Adding PayPal Support
-
-Same pattern - implement interface, add to factory, configure variables.
-
-### Adding New Operations
-
-1. Add method to `PaymentProviderService` interface
-2. Implement in all provider services
-3. Add webhook workflow
-4. Add event service method
-5. **Done!**
-
----
-
-This template provides a complete, modular, provider-agnostic payment gateway integration that's easy to maintain and extend!
-
+---
+template_id: tpl-webhook-payment-gateway-integration
+canonical_filename: template-webhook-payment-gateway-integration.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: integration
+source: webhook-json-payment
+destination: fluent-event-api
+entity: payment
+format: json
+logging: versori
+status: stable
+features:
+  - webhook-signature-validation
+  - batched-events
+  - attribute-transformation
+  - memory-management
+  - enhanced-logging
+---
+
+# Template: Webhook - Payment Gateway Integration (Adyen)
+
+**Template Version:** 2.0.0
+**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+
+**🆕 Version 2.0.0 Enhancements:**
+- ✅ **Webhook Signature Validation** - Secure webhook verification with HMAC-SHA256
+- ✅ **Batched Events** - Process events in optimized batches to reduce API calls
+- ✅ **Attribute Transformation** - Handle nested arrays and complex data structures
+- ✅ **Memory Management** - Clear large arrays after processing batches
+- ✅ **Enhanced Logging** - Track batch processing and event submission with emoji indicators
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Intercept Fluent Workflow webhooks for payment operations (Capture, Refund, Auth Cancel, ReAuth), process via payment gateway (Adyen), and send events back to Fluent Commerce
+
+**Complexity**: Medium-High
+
+**Runtime**: Versori Platform
+
+**Estimated Lines**: ~1600 lines (modular structure)
+
+---
+
+## STEP 1: Understand This Template
+
+**What This Template Does:**
+
+- **4 Versori HTTP webhooks** for payment operations:
+  - **Capture** - Capture an authorized payment (triggered by ORDER/FULFILLMENT workflow)
+  - **Refund** - Refund a captured payment (triggered by Payment Entity orchestration)
+  - **Auth Cancel** - Cancel an authorization (triggered by Payment Entity orchestration)
+  - **ReAuth** - Re-authorize a payment (triggered by Payment Entity orchestration)
+
+- **Modular architecture** - Easy to swap payment providers (Adyen → Stripe, etc.)
+- **Shared services** - Webhook validation, event sending, idempotency
+- **Payment provider abstraction** - Switch providers by changing one service
+- **Event mapping** - Payment gateway responses → Fluent event format
+- **Idempotency handling** - Prevent duplicate operations
+- **Error handling** - Comprehensive error handling and retry logic
+- **Trigger source validation** - Ensures webhooks called from correct Fluent workflows
+- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
+
+**Key SDK Components:**
+
+- `createClient()` - Universal client factory (auto-detects Versori context)
+- `client.sendEvent()` - Send events to Fluent Commerce Event API
+- `VersoriKVAdapter` - Idempotency tracking (KV storage)
+- `WebhookValidationService` - Webhook signature validation
+- Native Versori `log` - Use `log` from context
+
+**Entity Type:**
+
+- **Payment** - Fluent entity for payment operations
+- **Event API** - Uses `sendEvent()` to send payment events back to Fluent
+
+**Critical Patterns:**
+
+- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes payment in background
+- **External JSON Config**: Payment provider configuration in separate JSON file (`config/payment-provider-config.json`)
+- **Modular Architecture**: Separate services, workflows, config, types folders
+- **Background Processing**: Long-running operations (payment gateway API calls, event sending) happen asynchronously
+- **Idempotency**: KV storage prevents duplicate payment operations
+- **Provider Abstraction**: Easy to swap payment providers (Adyen → Stripe)
+
+**When to Use This Template:**
+
+- ✅ Payment gateway integration (Adyen, Stripe, etc.)
+- ✅ Payment operations triggered by Fluent Rubix workflows
+- ✅ Need fast webhook response (don't wait for payment gateway API calls)
+- ✅ Idempotency required (prevent duplicate charges/refunds)
+- ✅ Multiple payment operations (Capture, Refund, Cancel, ReAuth)
+
+**When NOT to Use:**
+
+- ❌ Direct payment processing (use payment gateway SDK directly)
+- ❌ Bulk payment operations (use Batch API or scheduled workflows)
+- ❌ Need synchronous payment confirmation (wait for result before responding)
+
+---
+
+## 🎯 Flow Mapping & Trigger Sources
+
+| Payment Operation | Trigger Source | When It Happens | Context |
+|-------------------|----------------|------------------|---------|
+| **Capture** | ORDER/FULFILLMENT Workflow | Order ready to ship | Initial flow - order moves to fulfillment |
+| **Refund** | Payment Entity Orchestration | Post-purchase refund | After RMA processing, order cancellation |
+| **Auth Cancel** | Payment Entity Orchestration | Pre-capture cancellation | Order cancelled before capture |
+| **ReAuth** | Payment Entity Orchestration | Authorization renewal | Authorization expires or needs extension |
+
+**Note**: All webhooks are called from Rubix workflows, which handle all business logic validation before calling endpoints.
+
+---
+
+## 🔑 Key Principle: Rubix Workflow Validation
+
+**IMPORTANT**: All webhooks are called from **Rubix workflows** within Fluent Commerce.
+
+### What This Means
+
+✅ **Rubix workflows handle ALL business logic validation**:
+- Order status checks (is order ready to ship?)
+- Payment state checks (is payment authorized? captured?)
+- Entity existence checks (does order exist? does payment exist?)
+- Business rules (can we refund? can we cancel?)
+
+✅ **If Rubix workflow calls an endpoint, the entity is already in the correct state**:
+- If Capture endpoint is called → Order is ready to ship, payment is authorized
+- If Refund endpoint is called → Payment is captured, refund is approved
+- If Cancel endpoint is called → Authorization exists, order is cancelled
+- If ReAuth endpoint is called → Authorization exists, needs renewal
+
+### What We Validate (Technical Only)
+
+✅ **Payload structure** - Required fields present  
+✅ **Trigger source** - Correct Rubix workflow calling endpoint  
+✅ **Data format** - Amounts, currencies, references are valid  
+✅ **Idempotency** - Prevent duplicate operations  
+✅ **Signature** - Webhook authenticity (if configured)
+
+### What We DON'T Validate
+
+❌ **Entity status** - Rubix workflow ensures correct status  
+❌ **Payment state** - Rubix workflow ensures correct state  
+❌ **Business rules** - Rubix workflow enforces rules  
+❌ **Entity existence** - Rubix workflow verified before calling
+
+### Why This Matters
+
+- **Simpler code** - No complex business logic in webhook handlers
+- **Single source of truth** - Rubix workflows own business logic
+- **Reliability** - Rubix workflows ensure correct state before calling
+- **Performance** - No redundant GraphQL queries to check entity status
+
+---
+
+## STEP 2: Implementation Prompt for Claude Code
+
+**Copy this prompt and send to Claude Code to generate the complete implementation:**
+
+```
+Create Versori webhook workflows for payment gateway integration (Adyen) to Fluent Commerce.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhooks)
+2. Source: Payment operations via HTTP POST webhooks (JSON, from Fluent Rubix workflows)
+3. Destination: Fluent Commerce Event API (sendEvent for payment events)
+4. Format: JSON payment payload
+5. Entity: Payment (Event API for event sending)
+
+KEY FEATURES:
+- Sync + fire-and-forget pattern (fast webhook response, background processing)
+- External JSON configuration (config/payment-provider-config.json)
+- Modular architecture (workflows/, services/, config/, types/)
+- 4 webhooks: Capture, Refund, Auth Cancel, ReAuth
+- Payment provider abstraction (easy to swap Adyen → Stripe)
+- Idempotency handling (prevent duplicate operations)
+- Webhook signature validation
+- Trigger source validation (Rubix workflow validation)
+
+CRITICAL REQUIREMENTS:
+1. Webhook Mode: response: { mode: 'sync' } (fast response)
+2. Background Processing: Fire-and-forget pattern (no await on long operations)
+3. Provider Config: External JSON file (config/payment-provider-config.json)
+4. Modular Structure: Separate services/, config/, types/ folders
+5. Native Logging: Use log from context (no LoggingService)
+6. Idempotency: VersoriKVAdapter for duplicate prevention
+
+SDK METHODS TO USE:
+- createClient({ ...ctx, log }) - Pass full Versori context
+- client.setRetailerId(retailerId) - REQUIRED for Event API
+- client.sendEvent(event) - Send payment events to Fluent
+- new VersoriKVAdapter(openKv(':project:')) - Idempotency tracking
+- new WebhookValidationService(log) - Webhook signature validation
+
+FORBIDDEN PATTERNS:
+- ❌ Inline config (use external JSON)
+- ❌ await on background processing (use fire-and-forget)
+- ❌ LoggingService (use native log from context)
+- ❌ All code in one file (use modular structure)
+- ❌ async mode webhook (use sync + fire-and-forget)
+```
+
+---
+
+## STEP 3: Detailed Flow Documentation
+
+### Complete Processing Flow (Payment Capture Example)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. WEBHOOK RECEIVED (from Rubix Workflow)                  │
+│    POST https://{workspace}.versori.run/payment-capture     │
+│    Content-Type: application/json                           │
+│    Body: { paymentReference: "...", amount: 100, ... }      │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
+│    - Check fluent_commerce connection exists                 │
+│    - Validate payment payload present                        │
+│    - Validate webhook signature (if configured)             │
+│    - Validate trigger source (ORDER_FULFILLMENT)          │
+│    - Check idempotency (prevent duplicates)                 │
+│    - Return HTTP 200 OK immediately                         │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3a. Initialize Fluent Client                        │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    │     - setRetailerId(retailerId)                     │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3b. Call Payment Gateway API                         │  │
+│    │     - Adyen Capture API call                         │  │
+│    │     - Handle payment gateway response                │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3c. Send Event to Fluent                            │  │
+│    │     - Map gateway response to Fluent event format   │  │
+│    │     - client.sendEvent(event)                        │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3d. Update Idempotency Record                       │  │
+│    │     - Store successful operation in KV               │  │
+│    └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Response Timing
+
+| Stage | Timing | Blocking |
+|-------|--------|----------|
+| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
+| **Background Processing** | ~1000-3000ms | ❌ No (fire-and-forget) |
+| **Total Response Time** | ~10-50ms | ✅ Fast response |
+
+**Key Benefit**: Rubix workflow receives immediate acknowledgment (~50ms) while payment processing happens in background (~1-3s).
+
+---
+
+## STEP 4: Production Modular Structure
+
+> **✅ This section shows the COMPLETE production-ready modular structure.**
+> All files are shown with proper imports/exports and folder organization.
+
+### Complete Project Structure
+
+```
+payment-gateway-integration/
+├── package.json                              # Dependencies and Versori config
+├── index.ts                                  # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       ├── payment-capture.ts            # Webhook: Capture payment
+    │       ├── payment-refund.ts              # Webhook: Refund payment
+    │       ├── payment-auth-cancel.ts        # Webhook: Cancel authorization
+    │       └── payment-reauth.ts             # Webhook: Re-authorize payment
+    │
+    ├── services/
+    │   ├── payment-provider.service.ts       # Payment provider abstraction
+    │   ├── payment-event.service.ts          # Event sending to Fluent
+    │   ├── idempotency.service.ts            # Idempotency handling
+    │   └── webhook-validation.service.ts     # Webhook signature validation
+    │
+    ├── config/
+    │   └── payment-provider-config.json      # Provider configuration (external JSON)
+    │
+    └── types/
+        └── payment.types.ts                  # TypeScript interfaces
+```
+
+**Why This Structure?**
+
+- ✅ **Clear separation**: Webhook handlers vs business logic vs provider abstraction
+- ✅ **Reusable services**: Payment logic can be reused across webhooks
+- ✅ **External config**: Provider configuration changes don't require code changes
+- ✅ **Provider abstraction**: Easy to swap payment providers (Adyen → Stripe)
+- ✅ **Type safety**: TypeScript interfaces for better IDE support
+- ✅ **Scalable**: Easy to add new payment operations or providers
+
+---
+
+## SDK Methods Used
+
+- `webhook(name, handler)` - HTTP webhook endpoint (from `@versori/run`)
+- `createClient(ctx)` - Auto-detects Versori context, creates FluentClient
+- `client.setRetailerId()` - REQUIRED for Event API (after createClient)
+- `client.sendEvent()` - Send events to Fluent Commerce Event API
+- `VersoriKVAdapter(ctx.openKv(':project:'))` - Idempotency tracking
+- Native Versori log from context (no console.log, no LoggingService)
+
+---
+
+## Architecture Overview
+
+### Modular Design Pattern
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Webhook Layer (4 webhooks)                             │
+│  - adyen-capture                                        │
+│  - adyen-refund                                         │
+│  - adyen-auth-cancel                                    │
+│  - adyen-reauth                                         │
+└─────────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────┐
+│  Shared Services (Reusable)                             │
+│  - WebhookValidationService                             │
+│  - PaymentEventService                                  │
+│  - IdempotencyService                                   │
+└─────────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────┐
+│  Payment Provider Abstraction                           │
+│  - PaymentProviderService (Interface)                  │
+│  - AdyenPaymentProviderService (Implementation)        │
+│  - StripePaymentProviderService (Future)                │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Key Benefits
+
+✅ **Single Connector** - All 4 flows in one document/workflow  
+✅ **Provider Agnostic** - Easy to swap Adyen → Stripe (change one service)  
+✅ **DRY Principle** - Shared services used by all webhooks  
+✅ **Maintainable** - Clear separation of concerns  
+✅ **Testable** - Each layer can be tested independently  
+
+---
+
+## Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`http()`** → External API calls (chained from webhook/schedule)
+- **`fn()`** → Internal processing (chained from webhook/schedule)
+
+### Recommended Project Structure
+
+```
+payment-gateway-integration/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       ├── payment-capture.ts        # Webhook: Capture payment
+    │       ├── payment-refund.ts         # Webhook: Refund payment
+    │       ├── payment-auth-cancel.ts    # Webhook: Cancel authorization
+    │       └── payment-reauth.ts         # Webhook: Re-authorize payment
+    │
+    ├── services/
+    │   ├── payment-provider.service.ts   # Payment provider abstraction (interface)
+    │   ├── adyen-provider.service.ts     # Adyen implementation
+    │   ├── payment-event.service.ts      # Fluent Event API service
+    │   ├── webhook-validation.service.ts # Webhook validation & security
+    │   └── idempotency.service.ts        # Idempotency tracking
+    │
+    └── config/
+        ├── adyen-config.json             # Adyen-specific configuration
+        └── event-mapping.json            # Fluent event mapping config
+```
+
+---
+
+## Project Setup
+
+```bash
+mkdir versori-payment-gateway-integration && cd $_
+npm init -y
+npm install @fluentcommerce/fc-connect-sdk@latest @versori/run
+mkdir -p src/{workflows/webhook,services,config}
+```
+
+### Package Configuration (package.json)
+
+```json
+{
+  "name": "versori-payment-gateway-integration",
+  "version": "1.0.0",
+  "versori": {
+    "workflows": "./src/index.ts"
+  },
+  "type": "module",
+  "scripts": {
+    "deploy": "versori deploy",
+    "logs": "versori logs"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}
+```
+
+---
+
+## Activation Variables
+
+Configure these in Versori Activation Variables:
+
+```bash
+# Fluent Commerce Configuration
+fluentRetailerId=your-retailer-id
+
+# Payment Provider Configuration
+paymentProvider=adyen                    # adyen | stripe | paypal (future)
+paymentProviderEnvironment=test         # test | live
+
+# Adyen-Specific Configuration
+adyenMerchantAccount=YourMerchantAccount
+
+# Stripe-Specific Configuration (if using Stripe)
+# stripeSecretKey=sk_test_...
+# stripePublishableKey=pk_test_...
+
+# Webhook Security
+webhookSecret=your-shared-secret-for-signature-validation
+
+# Trigger Source Validation (Optional but Recommended)
+validateTriggerSource=true
+allowedTriggerSources=ORDER_FULFILLMENT,PAYMENT_ENTITY
+
+# Optional: Retry Configuration
+enableRetry=true
+maxRetries=3
+retryDelayMs=1000
+
+# Optional: Feature Flags
+enableIdempotency=true
+enableEventLogging=true
+```
+
+---
+
+## Versori Connections Setup
+
+### Connection 1: Fluent Commerce (OAuth2)
+
+**Name**: `fluent_commerce`
+
+**Type**: OAuth2
+
+**Configuration**:
+- `base_url`: Your Fluent Commerce API URL (e.g., `https://api.fluentcommerce.com`)
+- `client_id`: OAuth2 client ID
+- `client_secret`: OAuth2 client secret
+- `username`: Your Fluent Commerce username
+- `password`: Your Fluent Commerce password
+
+**Note**: SDK auto-detects and uses this connection via `createClient(ctx)`
+
+### Connection 2: Payment Gateway (API Key or OAuth2)
+
+**Name**: `payment_gateway` (or `adyen_payment_gateway`, `stripe_payment_gateway`)
+
+**Type**: API Key (for Adyen) or OAuth2 (for Stripe)
+
+**Configuration**:
+- **Adyen**: `api_key` - Your Adyen API key
+- **Stripe**: `secret_key` - Your Stripe secret key
+
+**Alternative**: Store API key in activation variable `paymentGatewayApiKey` if preferred
+
+---
+
+## Complete Working Code
+
+### File: `src/index.ts`
+
+```typescript
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * 🚀 VERSORI PAYMENT GATEWAY INTEGRATION - ENTRY POINT
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * Entry Point - Registers all payment webhooks with Versori platform
+ *
+ * Pattern: MemoryInterpreter
+ * - Export all workflows
+ * - Clean separation of concerns
+ * - Easy to add new workflows
+ */
+
+import { MemoryInterpreter } from '@versori/run';
+import { paymentCapture } from './workflows/webhook/payment-capture';
+import { paymentRefund } from './workflows/webhook/payment-refund';
+import { paymentAuthCancel } from './workflows/webhook/payment-auth-cancel';
+import { paymentReauth } from './workflows/webhook/payment-reauth';
+
+async function main(): Promise<void> {
+  const mi = await MemoryInterpreter.newInstance();
+  
+  // Register all payment webhook workflows
+  mi.register(paymentCapture);
+  mi.register(paymentRefund);
+  mi.register(paymentAuthCancel);
+  mi.register(paymentReauth);
+  
+  await mi.start();
+}
+
+main().then().catch((err) => console.error('Failed to run main()', err));
+```
+
+---
+
+### File: `src/services/payment-provider.service.ts`
+
+```typescript
+/**
+ * Payment Provider Service Interface
+ *
+ * Abstract interface for payment gateway operations
+ * Allows easy swapping of payment providers (Adyen → Stripe → PayPal)
+ */
+
+import type { Logger } from '@fluentcommerce/fc-connect-sdk';
+
+export interface PaymentAmount {
+  value: number;      // Amount in minor units (e.g., 1000 = $10.00)
+  currency: string;  // ISO 4217 currency code (e.g., "USD")
+}
+
+export interface PaymentContext {
+  orderRef: string;
+  paymentReference: string;
+  retailerId?: string;
+  merchantReference?: string;
+}
+
+export interface CaptureResult {
+  success: boolean;
+  paymentReference: string;
+  amount: PaymentAmount;
+  capturedAt: string;
+  resultCode?: string;
+  error?: string;
+}
+
+export interface RefundResult {
+  success: boolean;
+  refundReference: string;
+  originalPaymentReference: string;
+  amount: PaymentAmount;
+  refundedAt: string;
+  refundType?: 'FULL' | 'PARTIAL';
+  error?: string;
+}
+
+export interface CancelResult {
+  success: boolean;
+  cancellationReference: string;
+  originalPaymentReference: string;
+  cancelledAt: string;
+  error?: string;
+}
+
+export interface ReauthResult {
+  success: boolean;
+  reauthReference: string;
+  originalPaymentReference: string;
+  amount: PaymentAmount;
+  reauthorizedAt: string;
+  expiryDate?: string;
+  error?: string;
+}
+
+/**
+ * Payment Provider Service Interface
+ *
+ * Implement this interface for each payment provider:
+ * - AdyenPaymentProviderService
+ * - StripePaymentProviderService
+ * - PayPalPaymentProviderService
+ */
+export interface PaymentProviderService {
+  /**
+   * Capture an authorized payment
+   */
+  capturePayment(
+    paymentReference: string,
+    amount: PaymentAmount,
+    context: PaymentContext
+  ): Promise<CaptureResult>;
+
+  /**
+   * Refund a captured payment
+   */
+  refundPayment(
+    paymentReference: string,
+    amount: PaymentAmount,
+    context: PaymentContext
+  ): Promise<RefundResult>;
+
+  /**
+   * Cancel an authorization
+   */
+  cancelAuthorization(
+    paymentReference: string,
+    context: PaymentContext
+  ): Promise<CancelResult>;
+
+  /**
+   * Re-authorize a payment
+   */
+  reauthorizePayment(
+    paymentReference: string,
+    amount: PaymentAmount,
+    context: PaymentContext
+  ): Promise<ReauthResult>;
+
+  /**
+   * Get provider name (for logging/debugging)
+   */
+  getProviderName(): string;
+}
+```
+
+---
+
+### File: `src/services/adyen-provider.service.ts`
+
+```typescript
+/**
+ * Adyen Payment Provider Service Implementation
+ *
+ * Implements PaymentProviderService for Adyen payment gateway
+ */
+
+import type { Logger } from '@fluentcommerce/fc-connect-sdk';
+import type {
+  PaymentProviderService,
+  PaymentAmount,
+  PaymentContext,
+  CaptureResult,
+  RefundResult,
+  CancelResult,
+  ReauthResult,
+} from './payment-provider.service';
+
+export class AdyenPaymentProviderService implements PaymentProviderService {
+  constructor(
+    private apiKey: string,
+    private environment: 'test' | 'live',
+    private merchantAccount: string,
+    private log: Logger
+  ) {}
+
+  getProviderName(): string {
+    return 'Adyen';
+  }
+
+  /**
+   * Get Adyen API base URL based on environment
+   */
+  private getApiUrl(): string {
+    return this.environment === 'live'
+      ? 'https://pal-live.adyen.com/pal/servlet/Payment'
+      : 'https://pal-test.adyen.com/pal/servlet/Payment';
+  }
+
+  /**
+   * Capture an authorized payment
+   */
+  async capturePayment(
+    paymentReference: string,
+    amount: PaymentAmount,
+    context: PaymentContext
+  ): Promise<CaptureResult> {
+    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/capture`;
+
+    this.log.info('🔧 [Adyen] Calling capture API', {
+      paymentReference,
+      amount: amount.value,
+      currency: amount.currency,
+      merchantAccount: this.merchantAccount,
+    });
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.apiKey,
+        },
+        body: JSON.stringify({
+          amount: amount,
+          merchantAccount: this.merchantAccount,
+        }),
+      });
+
+      const responseData = await response.json();
+
+      if (!response.ok) {
+        const error = responseData.error || {
+          errorCode: 'UNKNOWN_ERROR',
+          errorType: 'API_ERROR',
+          message: `HTTP ${response.status}: ${response.statusText}`,
+        };
+
+        this.log.error('❌ [Adyen] Capture API error', {
+          paymentReference,
+          errorCode: error.errorCode,
+          message: error.message,
+        });
+
+        return {
+          success: false,
+          paymentReference: paymentReference,
+          amount: amount,
+          capturedAt: new Date().toISOString(),
+          error: `${error.errorCode}: ${error.message}`,
+        };
+      }
+
+      this.log.info('✅ [Adyen] Capture successful', {
+        pspReference: responseData.pspReference,
+        resultCode: responseData.resultCode,
+      });
+
+      return {
+        success: true,
+        paymentReference: responseData.pspReference,
+        amount: responseData.amount || amount,
+        capturedAt: responseData.eventDate || new Date().toISOString(),
+        resultCode: responseData.resultCode,
+      };
+    } catch (error: any) {
+      this.log.error('❌ [Adyen] Capture API call failed', {
+        paymentReference,
+        error: error.message,
+      });
+
+      return {
+        success: false,
+        paymentReference: paymentReference,
+        amount: amount,
+        capturedAt: new Date().toISOString(),
+        error: error.message,
+      };
+    }
+  }
+
+  /**
+   * Refund a captured payment
+   */
+  async refundPayment(
+    paymentReference: string,
+    amount: PaymentAmount,
+    context: PaymentContext
+  ): Promise<RefundResult> {
+    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/refunds`;
+
+    this.log.info('🔧 [Adyen] Calling refund API', {
+      paymentReference,
+      amount: amount.value,
+      currency: amount.currency,
+    });
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.apiKey,
+        },
+        body: JSON.stringify({
+          amount: amount,
+          merchantAccount: this.merchantAccount,
+          reference: context.merchantReference || context.orderRef,
+        }),
+      });
+
+      const responseData = await response.json();
+
+      if (!response.ok) {
+        const error = responseData.error || {
+          errorCode: 'UNKNOWN_ERROR',
+          message: `HTTP ${response.status}: ${response.statusText}`,
+        };
+
+        return {
+          success: false,
+          refundReference: '',
+          originalPaymentReference: paymentReference,
+          amount: amount,
+          refundedAt: new Date().toISOString(),
+          error: `${error.errorCode}: ${error.message}`,
+        };
+      }
+
+      // Determine refund type (full vs partial)
+      const refundType = responseData.refundType || 'FULL';
+
+      return {
+        success: true,
+        refundReference: responseData.pspReference,
+        originalPaymentReference: paymentReference,
+        amount: responseData.amount || amount,
+        refundedAt: responseData.eventDate || new Date().toISOString(),
+        refundType: refundType as 'FULL' | 'PARTIAL',
+      };
+    } catch (error: any) {
+      return {
+        success: false,
+        refundReference: '',
+        originalPaymentReference: paymentReference,
+        amount: amount,
+        refundedAt: new Date().toISOString(),
+        error: error.message,
+      };
+    }
+  }
+
+  /**
+   * Cancel an authorization
+   */
+  async cancelAuthorization(
+    paymentReference: string,
+    context: PaymentContext
+  ): Promise<CancelResult> {
+    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/cancels`;
+
+    this.log.info('🔧 [Adyen] Calling cancel API', {
+      paymentReference,
+    });
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.apiKey,
+        },
+        body: JSON.stringify({
+          merchantAccount: this.merchantAccount,
+          reference: context.merchantReference || context.orderRef,
+        }),
+      });
+
+      const responseData = await response.json();
+
+      if (!response.ok) {
+        const error = responseData.error || {
+          errorCode: 'UNKNOWN_ERROR',
+          message: `HTTP ${response.status}: ${response.statusText}`,
+        };
+
+        return {
+          success: false,
+          cancellationReference: '',
+          originalPaymentReference: paymentReference,
+          cancelledAt: new Date().toISOString(),
+          error: `${error.errorCode}: ${error.message}`,
+        };
+      }
+
+      return {
+        success: true,
+        cancellationReference: responseData.pspReference,
+        originalPaymentReference: paymentReference,
+        cancelledAt: responseData.eventDate || new Date().toISOString(),
+      };
+    } catch (error: any) {
+      return {
+        success: false,
+        cancellationReference: '',
+        originalPaymentReference: paymentReference,
+        cancelledAt: new Date().toISOString(),
+        error: error.message,
+      };
+    }
+  }
+
+  /**
+   * Re-authorize a payment
+   */
+  async reauthorizePayment(
+    paymentReference: string,
+    amount: PaymentAmount,
+    context: PaymentContext
+  ): Promise<ReauthResult> {
+    const url = `${this.getApiUrl()}/v68/payments/${paymentReference}/reauthorise`;
+
+    this.log.info('🔧 [Adyen] Calling reauthorize API', {
+      paymentReference,
+      amount: amount.value,
+      currency: amount.currency,
+    });
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this.apiKey,
+        },
+        body: JSON.stringify({
+          amount: amount,
+          merchantAccount: this.merchantAccount,
+          reference: context.merchantReference || context.orderRef,
+        }),
+      });
+
+      const responseData = await response.json();
+
+      if (!response.ok) {
+        const error = responseData.error || {
+          errorCode: 'UNKNOWN_ERROR',
+          message: `HTTP ${response.status}: ${response.statusText}`,
+        };
+
+        return {
+          success: false,
+          reauthReference: '',
+          originalPaymentReference: paymentReference,
+          amount: amount,
+          reauthorizedAt: new Date().toISOString(),
+          error: `${error.errorCode}: ${error.message}`,
+        };
+      }
+
+      return {
+        success: true,
+        reauthReference: responseData.pspReference,
+        originalPaymentReference: paymentReference,
+        amount: responseData.amount || amount,
+        reauthorizedAt: responseData.eventDate || new Date().toISOString(),
+        expiryDate: responseData.expiryDate,
+      };
+    } catch (error: any) {
+      return {
+        success: false,
+        reauthReference: '',
+        originalPaymentReference: paymentReference,
+        amount: amount,
+        reauthorizedAt: new Date().toISOString(),
+        error: error.message,
+      };
+    }
+  }
+}
+```
+
+---
+
+### File: `src/services/webhook-validation.service.ts`
+
+```typescript
+/**
+ * Webhook Validation Service
+ *
+ * Validates incoming webhooks from Fluent Workflow
+ * - Signature validation (HMAC-SHA256)
+ * - Payload structure validation
+ * - Required field checking
+ */
+
+import { createHmac } from 'node:crypto';
+import type { Logger } from '@fluentcommerce/fc-connect-sdk';
+
+export interface WebhookPayload {
+  orderRef: string;
+  paymentReference: string;
+  amount: {
+    value: number;
+    currency: string;
+  };
+  retailerId?: string;
+  merchantReference?: string;
+  triggerSource?: string;  // ORDER_FULFILLMENT | PAYMENT_ENTITY
+  orderStatus?: string;    // For ORDER_FULFILLMENT triggers
+  refundReason?: string;   // For Payment Entity refunds
+  cancelReason?: string;  // For Payment Entity cancellations
+  reauthReason?: string;   // For Payment Entity reauthorizations
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  payload?: WebhookPayload;
+}
+
+export class WebhookValidationService {
+  constructor(private log: Logger) {}
+
+  /**
+   * Validate webhook signature using HMAC-SHA256
+   */
+  validateSignature(
+    payload: string,
+    signature: string,
+    secret: string
+  ): boolean {
+    if (!signature || !secret) {
+      return false;
+    }
+
+    const hmac = createHmac('sha256', secret);
+    hmac.update(payload);
+    const expectedSignature = hmac.digest('hex');
+
+    // Constant-time comparison to prevent timing attacks
+    if (signature.length !== expectedSignature.length) {
+      return false;
+    }
+
+    let match = true;
+    for (let i = 0; i < signature.length; i++) {
+      if (signature[i] !== expectedSignature[i]) {
+        match = false;
+      }
+    }
+
+    return match;
+  }
+
+  /**
+   * Validate webhook payload structure
+   */
+  validatePayload(payload: any): ValidationResult {
+    const requiredFields = ['orderRef', 'paymentReference', 'amount'];
+    const missingFields = requiredFields.filter((field) => !payload[field]);
+
+    if (missingFields.length > 0) {
+      return {
+        valid: false,
+        error: `Missing required fields: ${missingFields.join(', ')}`,
+      };
+    }
+
+    if (!payload.amount || typeof payload.amount.value !== 'number') {
+      return {
+        valid: false,
+        error: 'Invalid amount structure: amount.value must be a number',
+      };
+    }
+
+    if (!payload.amount.currency || typeof payload.amount.currency !== 'string') {
+      return {
+        valid: false,
+        error: 'Invalid amount structure: amount.currency must be a string',
+      };
+    }
+
+    if (payload.amount.value <= 0) {
+      return {
+        valid: false,
+        error: 'Invalid amount: value must be positive',
+      };
+    }
+
+    if (typeof payload.paymentReference !== 'string' || payload.paymentReference.length === 0) {
+      return {
+        valid: false,
+        error: 'Invalid paymentReference: must be a non-empty string',
+      };
+    }
+
+    return {
+      valid: true,
+      payload: {
+        orderRef: payload.orderRef,
+        paymentReference: payload.paymentReference,
+        amount: {
+          value: payload.amount.value,
+          currency: payload.amount.currency,
+        },
+        retailerId: payload.retailerId,
+        merchantReference: payload.merchantReference,
+      },
+    };
+  }
+
+  /**
+   * Extract payment context from validated payload
+   */
+  extractPaymentContext(payload: WebhookPayload) {
+    return {
+      orderRef: payload.orderRef,
+      paymentReference: payload.paymentReference,
+      amount: payload.amount,
+      retailerId: payload.retailerId,
+      merchantReference: payload.merchantReference || payload.orderRef,
+      triggerSource: payload.triggerSource,
+      orderStatus: payload.orderStatus,
+      refundReason: payload.refundReason,
+      cancelReason: payload.cancelReason,
+      reauthReason: payload.reauthReason,
+    };
+  }
+
+  /**
+   * Validate trigger source (ensures webhook called from correct workflow)
+   */
+  validateTriggerSource(
+    payload: any,
+    allowedSources: string[],
+    requiredSource?: string
+  ): ValidationResult {
+    const source = payload.triggerSource;
+
+    if (!source) {
+      return {
+        valid: false,
+        error: 'Missing triggerSource in payload',
+      };
+    }
+
+    if (requiredSource && source !== requiredSource) {
+      return {
+        valid: false,
+        error: `Invalid trigger source: expected ${requiredSource}, got ${source}`,
+      };
+    }
+
+    if (!allowedSources.includes(source)) {
+      return {
+        valid: false,
+        error: `Trigger source not allowed: ${source}. Allowed: ${allowedSources.join(', ')}`,
+      };
+    }
+
+    return {
+      valid: true,
+    };
+  }
+}
+```
+
+---
+
+### File: `src/services/idempotency.service.ts`
+
+```typescript
+/**
+ * Idempotency Service
+ *
+ * Tracks processed payments to prevent duplicate operations
+ */
+
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+import type { Logger } from '@fluentcommerce/fc-connect-sdk';
+
+export interface IdempotencyRecord {
+  operationType: 'capture' | 'refund' | 'cancel' | 'reauth';
+  paymentReference: string;
+  processedAt: string;
+  resultReference: string;
+  amount?: number;
+  currency?: string;
+}
+
+export class IdempotencyService {
+  constructor(
+    private kvAdapter: VersoriKVAdapter,
+    private log: Logger
+  ) {}
+
+  /**
+   * Generate idempotency key
+   */
+  private getIdempotencyKey(
+    operationType: string,
+    paymentReference: string
+  ): string[] {
+    return [`payment:${operationType}:${paymentReference}`];
+  }
+
+  /**
+   * Check if operation was already processed
+   */
+  async checkAndStore(
+    operationType: 'capture' | 'refund' | 'cancel' | 'reauth',
+    paymentReference: string,
+    resultReference: string,
+    amount?: { value: number; currency: string }
+  ): Promise<{ alreadyProcessed: boolean; existingRecord?: IdempotencyRecord }> {
+    const key = this.getIdempotencyKey(operationType, paymentReference);
+    const existing = await this.kvAdapter.get(key);
+
+    if (existing?.value) {
+      const record = typeof existing.value === 'string'
+        ? JSON.parse(existing.value)
+        : existing.value;
+
+      this.log.info('✅ [Idempotency] Operation already processed', {
+        operationType,
+        paymentReference,
+        processedAt: record.processedAt,
+      });
+
+      return {
+        alreadyProcessed: true,
+        existingRecord: record,
+      };
+    }
+
+    // Store new record
+    const record: IdempotencyRecord = {
+      operationType,
+      paymentReference,
+      processedAt: new Date().toISOString(),
+      resultReference,
+      amount: amount?.value,
+      currency: amount?.currency,
+    };
+
+    await this.kvAdapter.set(key, JSON.stringify(record));
+
+    this.log.info('✅ [Idempotency] Operation recorded', {
+      operationType,
+      paymentReference,
+      resultReference,
+    });
+
+    return {
+      alreadyProcessed: false,
+    };
+  }
+
+  /**
+   * Get existing record (without storing)
+   */
+  async getExisting(
+    operationType: 'capture' | 'refund' | 'cancel' | 'reauth',
+    paymentReference: string
+  ): Promise<IdempotencyRecord | null> {
+    const key = this.getIdempotencyKey(operationType, paymentReference);
+    const existing = await this.kvAdapter.get(key);
+
+    if (existing?.value) {
+      return typeof existing.value === 'string'
+        ? JSON.parse(existing.value)
+        : existing.value;
+    }
+
+    return null;
+  }
+}
+```
+
+---
+
+### File: `src/services/payment-event.service.ts`
+
+```typescript
+/**
+ * Payment Event Service
+ *
+ * Maps payment provider responses to Fluent event format and sends events
+ */
+
+import type { FluentClient, Logger } from '@fluentcommerce/fc-connect-sdk';
+import type {
+  CaptureResult,
+  RefundResult,
+  CancelResult,
+  ReauthResult,
+  PaymentContext,
+} from './payment-provider.service';
+
+export class PaymentEventService {
+  constructor(
+    private client: FluentClient,
+    private log: Logger
+  ) {}
+
+  /**
+   * Send payment capture event to Fluent Commerce
+   */
+  async sendCaptureEvent(
+    result: CaptureResult,
+    context: PaymentContext
+  ): Promise<void> {
+    this.log.info('📤 [Event] Sending payment capture event', {
+      orderRef: context.orderRef,
+      paymentReference: result.paymentReference,
+    });
+
+    const eventPayload = {
+      name: 'PaymentCaptured',
+      entityType: 'ORDER',
+      entityRef: context.orderRef,
+      data: {
+        paymentReference: result.paymentReference,
+        originalPaymentReference: context.paymentReference,
+        amount: result.amount.value,
+        currency: result.amount.currency,
+        capturedAt: result.capturedAt,
+        resultCode: result.resultCode,
+        merchantReference: context.merchantReference,
+      },
+    };
+
+    await this.client.sendEvent(eventPayload);
+  }
+
+  /**
+   * Send payment refund event to Fluent Commerce
+   */
+  async sendRefundEvent(
+    result: RefundResult,
+    context: PaymentContext
+  ): Promise<void> {
+    this.log.info('📤 [Event] Sending payment refund event', {
+      orderRef: context.orderRef,
+      refundReference: result.refundReference,
+    });
+
+    const eventPayload = {
+      name: 'PaymentRefunded',
+      entityType: 'ORDER',
+      entityRef: context.orderRef,
+      data: {
+        refundReference: result.refundReference,
+        originalPaymentReference: result.originalPaymentReference,
+        amount: result.amount.value,
+        currency: result.amount.currency,
+        refundType: result.refundType || 'FULL',
+        refundedAt: result.refundedAt,
+        merchantReference: context.merchantReference,
+      },
+    };
+
+    await this.client.sendEvent(eventPayload);
+  }
+
+  /**
+   * Send payment cancellation event to Fluent Commerce
+   */
+  async sendCancelEvent(
+    result: CancelResult,
+    context: PaymentContext
+  ): Promise<void> {
+    this.log.info('📤 [Event] Sending payment cancellation event', {
+      orderRef: context.orderRef,
+      cancellationReference: result.cancellationReference,
+    });
+
+    const eventPayload = {
+      name: 'PaymentAuthorizationCancelled',
+      entityType: 'ORDER',
+      entityRef: context.orderRef,
+      data: {
+        cancellationReference: result.cancellationReference,
+        originalPaymentReference: result.originalPaymentReference,
+        cancelledAt: result.cancelledAt,
+        merchantReference: context.merchantReference,
+      },
+    };
+
+    await this.client.sendEvent(eventPayload);
+  }
+
+  /**
+   * Send payment reauthorization event to Fluent Commerce
+   */
+  async sendReauthEvent(
+    result: ReauthResult,
+    context: PaymentContext
+  ): Promise<void> {
+    this.log.info('📤 [Event] Sending payment reauthorization event', {
+      orderRef: context.orderRef,
+      reauthReference: result.reauthReference,
+    });
+
+    const eventPayload = {
+      name: 'PaymentReauthorized',
+      entityType: 'ORDER',
+      entityRef: context.orderRef,
+      data: {
+        reauthReference: result.reauthReference,
+        originalPaymentReference: result.originalPaymentReference,
+        amount: result.amount.value,
+        currency: result.amount.currency,
+        reauthorizedAt: result.reauthorizedAt,
+        expiryDate: result.expiryDate,
+        merchantReference: context.merchantReference,
+      },
+    };
+
+    await this.client.sendEvent(eventPayload);
+  }
+}
+```
+
+---
+
+### File: `src/services/payment-provider-factory.service.ts`
+
+```typescript
+/**
+ * Payment Provider Factory
+ *
+ * Creates payment provider service based on configuration
+ * Easy to swap providers: Adyen → Stripe → PayPal
+ */
+
+import type { Logger } from '@fluentcommerce/fc-connect-sdk';
+import type { PaymentProviderService } from './payment-provider.service';
+import { AdyenPaymentProviderService } from './adyen-provider.service';
+// Future: import { StripePaymentProviderService } from './stripe-provider.service';
+
+export class PaymentProviderFactory {
+  /**
+   * Create payment provider service
+   *
+   * @param provider - Provider name (adyen, stripe, paypal)
+   * @param config - Provider-specific configuration
+   * @param log - Logger instance
+   */
+  static createProvider(
+    provider: string,
+    config: any,
+    log: Logger
+  ): PaymentProviderService {
+    switch (provider.toLowerCase()) {
+      case 'adyen':
+        return new AdyenPaymentProviderService(
+          config.apiKey,
+          config.environment,
+          config.merchantAccount,
+          log
+        );
+
+      // Future: Stripe implementation
+      // case 'stripe':
+      //   return new StripePaymentProviderService(
+      //     config.secretKey,
+      //     config.environment,
+      //     log
+      //   );
+
+      // Future: PayPal implementation
+      // case 'paypal':
+      //   return new PayPalPaymentProviderService(
+      //     config.clientId,
+      //     config.clientSecret,
+      //     config.environment,
+      //     log
+      //   );
+
+      default:
+        throw new Error(`Unsupported payment provider: ${provider}`);
+    }
+  }
+}
+```
+
+---
+
+### File: `src/workflows/webhook/payment-capture.ts`
+
+```typescript
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * 🚀 PAYMENT CAPTURE WEBHOOK
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * Intercepts Fluent Workflow webhook for payment capture
+ * 
+ * TRIGGER SOURCE: ORDER/FULFILLMENT Workflow (Rubix)
+ * - Triggered when order is ready to ship
+ * - Validates triggerSource: ORDER_FULFILLMENT
+ * - Note: Rubix workflow ensures order/payment is in correct state before calling
+ * 
+ * Flow:
+ * - Validates webhook payload and signature
+ * - Validates trigger source (must be ORDER_FULFILLMENT)
+ * - Calls payment provider Capture API
+ * - Sends event to Fluent Commerce Event API
+ * - Handles idempotency
+ * 
+ * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
+ */
+
+import { webhook } from '@versori/run';
+import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+import { WebhookValidationService } from '../../services/webhook-validation.service';
+import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
+import { PaymentEventService } from '../../services/payment-event.service';
+import { IdempotencyService } from '../../services/idempotency.service';
+import type { PaymentProviderService } from '../../services/payment-provider.service';
+
+/**
+ * Background processing function for payment capture
+ * Handles all long-running operations (payment gateway API, event sending)
+ */
+async function processPaymentCapture(ctx: any, executionStartTime: number): Promise<void> {
+  const { log, activation, connections } = ctx;
+
+  try {
+    log.info('🔄 [BACKGROUND] Starting background payment capture processing', {
+      correlationId: activation.id,
+    });
+
+    // =================================================================
+    // STEP 1: CONFIGURATION VALIDATION
+    // =================================================================
+
+    if (!connections?.fluent_commerce) {
+      log.error('❌ [BACKGROUND] Missing fluent_commerce connection');
+      return;
+    }
+
+    const retailerId = activation.getVariable('fluentRetailerId');
+    const paymentProvider = activation.getVariable('paymentProvider') || 'adyen';
+    const paymentProviderEnv = (activation.getVariable('paymentProviderEnvironment') || 'test') as 'test' | 'live';
+    const enableIdempotency = activation.getVariable('enableIdempotency') !== 'false';
+
+    // Get payment provider API key
+    let apiKey: string | undefined;
+    if (connections.payment_gateway?.credentials?.api_key) {
+      apiKey = connections.payment_gateway.credentials.api_key;
+    } else if (connections.adyen_payment_gateway?.credentials?.api_key) {
+      apiKey = connections.adyen_payment_gateway.credentials.api_key;
+    } else {
+      apiKey = activation.getVariable('paymentGatewayApiKey') || activation.getVariable('adyenApiKey');
+    }
+
+    if (!apiKey) {
+      log.error('❌ [BACKGROUND] Missing payment gateway API key');
+      return;
+    }
+
+    const merchantAccount = activation.getVariable('adyenMerchantAccount');
+    if (!merchantAccount && paymentProvider === 'adyen') {
+      log.error('❌ [BACKGROUND] Missing adyenMerchantAccount');
+      return;
+    }
+
+    // =================================================================
+    // STEP 2: PAYLOAD VALIDATION
+    // =================================================================
+
+    const rawPayload = activation.body || ctx.data;
+    const payload = typeof rawPayload === 'string' ? JSON.parse(rawPayload) : rawPayload;
+    const validator = new WebhookValidationService(log);
+    const validation = validator.validatePayload(payload);
+
+    if (!validation.valid) {
+      log.error('❌ [BACKGROUND] Invalid payload', { error: validation.error });
+      return;
+    }
+
+    const paymentContext = validator.extractPaymentContext(validation.payload!);
+    const finalRetailerId = paymentContext.retailerId || retailerId;
+
+    if (!finalRetailerId) {
+      log.error('❌ [BACKGROUND] Missing retailerId');
+      return;
+    }
+
+    // =================================================================
+    // STEP 2.5: VALIDATE TRIGGER SOURCE (Capture must come from ORDER/FULFILLMENT)
+    // =================================================================
+
+    const validateTriggerSource = activation.getVariable('validateTriggerSource') !== 'false';
+    const allowedSources = (activation.getVariable('allowedTriggerSources') || 'ORDER_FULFILLMENT,PAYMENT_ENTITY')
+      .split(',').map(s => s.trim());
+
+    if (validateTriggerSource) {
+      const triggerValidation = validator.validateTriggerSource(
+        payload,
+        allowedSources,
+        'ORDER_FULFILLMENT'  // Capture MUST come from ORDER_FULFILLMENT
+      );
+
+      if (!triggerValidation.valid) {
+        log.error('❌ [BACKGROUND] Invalid trigger source', {
+          triggerSource: payload.triggerSource,
+          expected: 'ORDER_FULFILLMENT',
+          error: triggerValidation.error,
+        });
+        return;
+      }
+
+      log.info('✅ [BACKGROUND] Trigger source validated', {
+        triggerSource: payload.triggerSource,
+      });
+    }
+
+    // =================================================================
+    // STEP 3: INITIALIZE SERVICES
+    // =================================================================
+
+    const fluentClient = await createClient(ctx, { validateConnection: true });
+    await fluentClient.setRetailerId(finalRetailerId);
+
+    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
+    const idempotencyService = new IdempotencyService(kvAdapter, log);
+
+    // Create payment provider service (easily swappable)
+    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
+      paymentProvider,
+      {
+        apiKey,
+        environment: paymentProviderEnv,
+        merchantAccount,
+      },
+      log
+    );
+
+    const eventService = new PaymentEventService(fluentClient, log);
+
+    // =================================================================
+    // STEP 4: IDEMPOTENCY CHECK
+    // =================================================================
+
+    if (enableIdempotency) {
+      const idempotencyCheck = await idempotencyService.checkAndStore(
+        'capture',
+        paymentContext.paymentReference,
+        '', // Will be updated after successful capture
+        paymentContext.amount
+      );
+
+      if (idempotencyCheck.alreadyProcessed && idempotencyCheck.existingRecord) {
+        log.info('✅ [BACKGROUND] Payment already processed (idempotency)', {
+          paymentReference: paymentContext.paymentReference,
+          resultReference: idempotencyCheck.existingRecord.resultReference,
+        });
+        return; // Already processed, exit early
+      }
+    }
+
+    // =================================================================
+    // STEP 5: CALL PAYMENT PROVIDER
+    // =================================================================
+
+    log.info('💳 [BACKGROUND] Calling payment provider', {
+      provider: paymentProviderService.getProviderName(),
+      paymentReference: paymentContext.paymentReference,
+    });
+
+    const captureResult = await paymentProviderService.capturePayment(
+      paymentContext.paymentReference,
+      paymentContext.amount,
+      {
+        ...paymentContext,
+        retailerId: finalRetailerId,
+      }
+    );
+
+    if (!captureResult.success) {
+      log.error('❌ [BACKGROUND] Payment capture failed', {
+        providerError: captureResult.error,
+        paymentReference: paymentContext.paymentReference,
+      });
+      return; // Failed, exit
+    }
+
+    // =================================================================
+    // STEP 6: UPDATE IDEMPOTENCY KEY
+    // =================================================================
+
+    if (enableIdempotency) {
+      await idempotencyService.checkAndStore(
+        'capture',
+        paymentContext.paymentReference,
+        captureResult.paymentReference,
+        captureResult.amount
+      );
+    }
+
+    // =================================================================
+    // STEP 7: SEND EVENT TO FLUENT
+    // =================================================================
+
+    try {
+      await eventService.sendCaptureEvent(captureResult, {
+        ...paymentContext,
+        retailerId: finalRetailerId,
+      });
+      log.info('✅ [BACKGROUND] Payment event sent to Fluent', {
+        paymentReference: captureResult.paymentReference,
+      });
+    } catch (error: any) {
+      log.error('❌ [BACKGROUND] Event send failed (non-blocking)', {
+        error: error.message,
+        paymentReference: captureResult.paymentReference,
+        note: 'Payment capture succeeded, but event failed - will be retried',
+      });
+      // Continue - event failure doesn't block success
+    }
+
+    // =================================================================
+    // STEP 8: LOG SUCCESS
+    // =================================================================
+
+    const duration = Date.now() - executionStartTime;
+    log.info('✅ [BACKGROUND] Payment capture completed successfully', {
+      paymentReference: paymentContext.paymentReference,
+      resultReference: captureResult.paymentReference,
+      provider: paymentProviderService.getProviderName(),
+      duration: `${duration}ms`,
+    });
+  } catch (error: any) {
+    log.error('❌ [BACKGROUND] Payment capture failed', {
+      error: error.message,
+      stack: error.stack,
+      errorType: error instanceof Error ? error.constructor.name : typeof error,
+    });
+  }
+}
+
+/**
+ * Payment Capture Webhook Handler
+ * Uses sync + fire-and-forget pattern for fast response
+ */
+export const paymentCapture = webhook('payment-capture', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+}, async (ctx) => {
+  const { log, activation, connections } = ctx;
+  const executionStartTime = Date.now();
+
+  log.info('🚀 [WEBHOOK] Received payment capture webhook', {
+    correlationId: activation.id,
+    timestamp: new Date().toISOString(),
+  });
+
+  // =================================================================
+  // QUICK VALIDATION (Synchronous, ~10-50ms)
+  // =================================================================
+
+  if (!connections?.fluent_commerce) {
+    log.error('❌ [WEBHOOK] Missing fluent_commerce connection');
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Missing fluent_commerce connection',
+        recommendation: 'Configure fluent_commerce connection in Connections section',
+      },
+    };
+  }
+
+  const retailerId = activation.getVariable('fluentRetailerId');
+  const paymentProvider = activation.getVariable('paymentProvider') || 'adyen';
+  const webhookSecret = activation.getVariable('webhookSecret');
+
+  // Quick payload validation
+  const rawPayload = activation.body || ctx.data;
+  const payload = typeof rawPayload === 'string' ? JSON.parse(rawPayload) : rawPayload;
+
+  if (!payload.paymentReference || !payload.amount) {
+    log.error('❌ [WEBHOOK] Invalid payload', {
+      hasPaymentReference: !!payload.paymentReference,
+      hasAmount: !!payload.amount,
+    });
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'Invalid payload: missing paymentReference or amount',
+      },
+    };
+  }
+
+  // Quick webhook signature validation (if configured)
+  if (webhookSecret) {
+    const payloadString = typeof rawPayload === 'string' ? rawPayload : JSON.stringify(rawPayload);
+    const signature = activation.headers?.['x-webhook-signature'] ||
+                     activation.headers?.['webhook-signature'] ||
+                     activation.headers?.['signature'];
+
+    if (signature) {
+      const validator = new WebhookValidationService(log);
+      const isValid = validator.validateSignature(payloadString, signature, webhookSecret);
+
+      if (!isValid) {
+        log.error('❌ [WEBHOOK] Invalid webhook signature');
+        return {
+          status: 401,
+          body: {
+            success: false,
+            error: 'Invalid webhook signature',
+          },
+        };
+      }
+    }
+  }
+
+  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
+    paymentReference: payload.paymentReference,
+  });
+
+  // ✅ Fire-and-forget: Start background processing WITHOUT await
+  // The promise continues execution after we return the response
+  processPaymentCapture(ctx, executionStartTime)
+    .then(() => {
+      log.info('✅ [BACKGROUND] Payment capture processing completed successfully', {
+        correlationId: activation.id,
+      });
+    })
+    .catch((error: unknown) => {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      log.error('❌ [BACKGROUND] Payment capture processing failed', {
+        correlationId: activation.id,
+        error: errorMessage,
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : typeof error,
+      });
+    });
+
+  // Return immediately (response sent with this return value)
+  return {
+    status: 200,
+    body: {
+      success: true,
+      message: 'Payment capture started in background',
+      paymentReference: payload.paymentReference,
+      timestamp: new Date().toISOString(),
+    },
+  };
+});
+```
+
+---
+
+### File: `src/workflows/webhook/payment-refund.ts`
+
+```typescript
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * 🚀 PAYMENT REFUND WEBHOOK
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * Intercepts Fluent Workflow webhook for payment refund
+ * 
+ * TRIGGER SOURCE: Payment Entity Orchestration (Rubix)
+ * - Triggered when refund is approved (after RMA processing, order cancellation)
+ * - Validates triggerSource: PAYMENT_ENTITY
+ * - Note: Rubix workflow ensures payment is in correct state before calling
+ * 
+ * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
+ */
+
+import { webhook } from '@versori/run';
+import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+import { WebhookValidationService } from '../../services/webhook-validation.service';
+import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
+import { PaymentEventService } from '../../services/payment-event.service';
+import { IdempotencyService } from '../../services/idempotency.service';
+import type { PaymentProviderService } from '../../services/payment-provider.service';
+
+export const paymentRefund = webhook('payment-refund', async (ctx) => {
+  const { log, activation, connections } = ctx;
+  const executionStartTime = Date.now();
+
+  try {
+    log.info('🚀 [PaymentRefund] Processing payment refund webhook', {
+      correlationId: activation.id,
+    });
+
+    // Similar structure to payment-capture.ts, but calls refundPayment()
+    // ... (same configuration validation, webhook validation, etc.)
+
+    const fluentClient = await createClient(ctx, { validateConnection: true });
+    await fluentClient.setRetailerId(finalRetailerId);
+
+    const kvAdapter = new VersoriKVAdapter(ctx.openKv(':project:'));
+    const idempotencyService = new IdempotencyService(kvAdapter, log);
+
+    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
+      paymentProvider,
+      { apiKey, environment: paymentProviderEnv, merchantAccount },
+      log
+    );
+
+    const eventService = new PaymentEventService(fluentClient, log);
+
+    // Idempotency check
+    if (enableIdempotency) {
+      const idempotencyCheck = await idempotencyService.checkAndStore(
+        'refund',
+        paymentContext.paymentReference,
+        '',
+        paymentContext.amount
+      );
+
+      if (idempotencyCheck.alreadyProcessed) {
+        return {
+          status: 200,
+          body: {
+            success: true,
+            alreadyProcessed: true,
+            refundReference: idempotencyCheck.existingRecord!.resultReference,
+          },
+        };
+      }
+    }
+
+    // Call payment provider
+    const refundResult = await paymentProviderService.refundPayment(
+      paymentContext.paymentReference,
+      paymentContext.amount,
+      { ...paymentContext, retailerId: finalRetailerId }
+    );
+
+    if (!refundResult.success) {
+      return {
+        status: 502,
+        body: {
+          success: false,
+          error: 'Payment refund failed',
+          providerError: refundResult.error,
+        },
+      };
+    }
+
+    // Update idempotency
+    if (enableIdempotency) {
+      await idempotencyService.checkAndStore(
+        'refund',
+        paymentContext.paymentReference,
+        refundResult.refundReference,
+        refundResult.amount
+      );
+    }
+
+    // Send event
+    await eventService.sendRefundEvent(refundResult, {
+      ...paymentContext,
+      retailerId: finalRetailerId,
+    });
+
+    const duration = Date.now() - executionStartTime;
+
+    return {
+      status: 200,
+      body: {
+        success: true,
+        refundReference: refundResult.refundReference,
+        originalPaymentReference: refundResult.originalPaymentReference,
+        amount: refundResult.amount.value,
+        currency: refundResult.amount.currency,
+        refundType: refundResult.refundType,
+        refundedAt: refundResult.refundedAt,
+        provider: paymentProviderService.getProviderName(),
+        duration: `${duration}ms`,
+      },
+    };
+  } catch (error: any) {
+    log.error('❌ [PaymentRefund] Unexpected error', { error: error.message });
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Internal server error',
+        message: error.message,
+      },
+    };
+  }
+});
+```
+
+---
+
+### File: `src/workflows/webhook/payment-auth-cancel.ts`
+
+```typescript
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * 🚀 PAYMENT AUTH CANCEL WEBHOOK
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * Intercepts Fluent Workflow webhook for authorization cancellation
+ * 
+ * TRIGGER SOURCE: Payment Entity Orchestration (Rubix)
+ * - Triggered when order is cancelled before capture
+ * - Validates triggerSource: PAYMENT_ENTITY
+ * - Note: Rubix workflow ensures payment is in correct state before calling
+ * 
+ * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
+ */
+
+import { webhook } from '@versori/run';
+import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+import { WebhookValidationService } from '../../services/webhook-validation.service';
+import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
+import { PaymentEventService } from '../../services/payment-event.service';
+import { IdempotencyService } from '../../services/idempotency.service';
+import type { PaymentProviderService } from '../../services/payment-provider.service';
+
+export const paymentAuthCancel = webhook('payment-auth-cancel', async (ctx) => {
+  const { log, activation, connections } = ctx;
+  const executionStartTime = Date.now();
+
+  try {
+    log.info('🚀 [PaymentAuthCancel] Processing authorization cancellation webhook', {
+      correlationId: activation.id,
+    });
+
+    // Similar structure, but:
+    // - No amount validation (cancellation doesn't need amount)
+    // - Calls cancelAuthorization()
+    // - Sends PaymentAuthorizationCancelled event
+
+    // ... (configuration validation, webhook validation similar to capture)
+
+    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
+      paymentProvider,
+      { apiKey, environment: paymentProviderEnv, merchantAccount },
+      log
+    );
+
+    const cancelResult = await paymentProviderService.cancelAuthorization(
+      paymentContext.paymentReference,
+      { ...paymentContext, retailerId: finalRetailerId }
+    );
+
+    if (!cancelResult.success) {
+      return {
+        status: 502,
+        body: {
+          success: false,
+          error: 'Authorization cancellation failed',
+          providerError: cancelResult.error,
+        },
+      };
+    }
+
+    await eventService.sendCancelEvent(cancelResult, {
+      ...paymentContext,
+      retailerId: finalRetailerId,
+    });
+
+    return {
+      status: 200,
+      body: {
+        success: true,
+        cancellationReference: cancelResult.cancellationReference,
+        originalPaymentReference: cancelResult.originalPaymentReference,
+        cancelledAt: cancelResult.cancelledAt,
+        provider: paymentProviderService.getProviderName(),
+      },
+    };
+  } catch (error: any) {
+    log.error('❌ [PaymentAuthCancel] Unexpected error', { error: error.message });
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Internal server error',
+        message: error.message,
+      },
+    };
+  }
+});
+```
+
+---
+
+### File: `src/workflows/webhook/payment-reauth.ts`
+
+```typescript
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * 🚀 PAYMENT REAUTH WEBHOOK
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * Intercepts Fluent Workflow webhook for payment reauthorization
+ * 
+ * TRIGGER SOURCE: Payment Entity Orchestration (Rubix)
+ * - Triggered when authorization expires or needs extension
+ * - Validates triggerSource: PAYMENT_ENTITY
+ * - Note: Rubix workflow ensures authorization is in correct state before calling
+ * 
+ * IMPORTANT: No entity status validation needed - Rubix workflow handles business logic
+ */
+
+import { webhook } from '@versori/run';
+import { createClient, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+import { WebhookValidationService } from '../../services/webhook-validation.service';
+import { PaymentProviderFactory } from '../../services/payment-provider-factory.service';
+import { PaymentEventService } from '../../services/payment-event.service';
+import { IdempotencyService } from '../../services/idempotency.service';
+import type { PaymentProviderService } from '../../services/payment-provider.service';
+
+export const paymentReauth = webhook('payment-reauth', async (ctx) => {
+  const { log, activation, connections } = ctx;
+  const executionStartTime = Date.now();
+
+  try {
+    log.info('🚀 [PaymentReauth] Processing payment reauthorization webhook', {
+      correlationId: activation.id,
+    });
+
+    // Similar structure to capture, but:
+    // - Calls reauthorizePayment()
+    // - Sends PaymentReauthorized event
+
+    // ... (configuration validation, webhook validation similar to capture)
+
+    const paymentProviderService: PaymentProviderService = PaymentProviderFactory.createProvider(
+      paymentProvider,
+      { apiKey, environment: paymentProviderEnv, merchantAccount },
+      log
+    );
+
+    const reauthResult = await paymentProviderService.reauthorizePayment(
+      paymentContext.paymentReference,
+      paymentContext.amount,
+      { ...paymentContext, retailerId: finalRetailerId }
+    );
+
+    if (!reauthResult.success) {
+      return {
+        status: 502,
+        body: {
+          success: false,
+          error: 'Payment reauthorization failed',
+          providerError: reauthResult.error,
+        },
+      };
+    }
+
+    await eventService.sendReauthEvent(reauthResult, {
+      ...paymentContext,
+      retailerId: finalRetailerId,
+    });
+
+    return {
+      status: 200,
+      body: {
+        success: true,
+        reauthReference: reauthResult.reauthReference,
+        originalPaymentReference: reauthResult.originalPaymentReference,
+        amount: reauthResult.amount.value,
+        currency: reauthResult.amount.currency,
+        reauthorizedAt: reauthResult.reauthorizedAt,
+        expiryDate: reauthResult.expiryDate,
+        provider: paymentProviderService.getProviderName(),
+      },
+    };
+  } catch (error: any) {
+    log.error('❌ [PaymentReauth] Unexpected error', { error: error.message });
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Internal server error',
+        message: error.message,
+      },
+    };
+  }
+});
+```
+
+---
+
+## How to Swap Payment Providers
+
+### Current: Adyen → Stripe
+
+**Step 1**: Create `src/services/stripe-provider.service.ts`
+
+```typescript
+import type { PaymentProviderService } from './payment-provider.service';
+// Implement StripePaymentProviderService with same interface
+```
+
+**Step 2**: Update `PaymentProviderFactory`
+
+```typescript
+case 'stripe':
+  return new StripePaymentProviderService(
+    config.secretKey,
+    config.environment,
+    log
+  );
+```
+
+**Step 3**: Update Activation Variables
+
+```bash
+paymentProvider=stripe                    # Change from adyen to stripe
+stripeSecretKey=sk_test_...              # Add Stripe config
+```
+
+**That's it!** All 4 webhooks automatically use Stripe. No changes needed to webhook code.
+
+---
+
+## Expected Webhook Payloads
+
+### Capture Payload (from ORDER/FULFILLMENT Workflow)
+
+```json
+{
+  "orderRef": "ORDER-12345",
+  "paymentReference": "8826162495174985",
+  "amount": {
+    "value": 10000,
+    "currency": "USD"
+  },
+  "retailerId": "2",
+  "merchantReference": "ORDER-12345",
+  "triggerSource": "ORDER_FULFILLMENT",
+  "orderStatus": "READY_TO_SHIP"
+}
+```
+
+### Refund Payload (from Payment Entity Orchestration)
+
+```json
+{
+  "orderRef": "ORDER-12345",
+  "paymentReference": "8826162495174985",
+  "amount": {
+    "value": 10000,
+    "currency": "USD"
+  },
+  "retailerId": "2",
+  "merchantReference": "ORDER-12345",
+  "triggerSource": "PAYMENT_ENTITY",
+  "refundReason": "RETURN_APPROVED",
+  "rmaRef": "RMA-67890",
+  "refundType": "FULL"
+}
+```
+
+### Auth Cancel Payload (from Payment Entity Orchestration)
+
+```json
+{
+  "orderRef": "ORDER-12345",
+  "paymentReference": "8826162495174985",
+  "retailerId": "2",
+  "merchantReference": "ORDER-12345",
+  "triggerSource": "PAYMENT_ENTITY",
+  "cancelReason": "ORDER_CANCELLED",
+  "orderStatus": "CANCELLED"
+}
+```
+
+### ReAuth Payload (from Payment Entity Orchestration)
+
+```json
+{
+  "orderRef": "ORDER-12345",
+  "paymentReference": "8826162495174985",
+  "amount": {
+    "value": 10000,
+    "currency": "USD"
+  },
+  "retailerId": "2",
+  "merchantReference": "ORDER-12345",
+  "triggerSource": "PAYMENT_ENTITY",
+  "reauthReason": "AUTHORIZATION_EXPIRING"
+}
+```
+
+---
+
+## Expected Events Sent to Fluent Commerce
+
+### PaymentCaptured
+
+```json
+{
+  "name": "PaymentCaptured",
+  "entityType": "ORDER",
+  "entityRef": "ORDER-12345",
+  "data": {
+    "paymentReference": "8826162495174985",
+    "originalPaymentReference": "8826162495174985",
+    "amount": 10000,
+    "currency": "USD",
+    "capturedAt": "2025-01-22T12:34:56.789Z",
+    "resultCode": "Received",
+    "merchantReference": "ORDER-12345"
+  }
+}
+```
+
+### PaymentRefunded
+
+```json
+{
+  "name": "PaymentRefunded",
+  "entityType": "ORDER",
+  "entityRef": "ORDER-12345",
+  "data": {
+    "refundReference": "8826162495174986",
+    "originalPaymentReference": "8826162495174985",
+    "amount": 10000,
+    "currency": "USD",
+    "refundType": "FULL",
+    "refundedAt": "2025-01-22T12:34:56.789Z",
+    "merchantReference": "ORDER-12345"
+  }
+}
+```
+
+### PaymentAuthorizationCancelled
+
+```json
+{
+  "name": "PaymentAuthorizationCancelled",
+  "entityType": "ORDER",
+  "entityRef": "ORDER-12345",
+  "data": {
+    "cancellationReference": "8826162495174987",
+    "originalPaymentReference": "8826162495174985",
+    "cancelledAt": "2025-01-22T12:34:56.789Z",
+    "merchantReference": "ORDER-12345"
+  }
+}
+```
+
+### PaymentReauthorized
+
+```json
+{
+  "name": "PaymentReauthorized",
+  "entityType": "ORDER",
+  "entityRef": "ORDER-12345",
+  "data": {
+    "reauthReference": "8826162495174988",
+    "originalPaymentReference": "8826162495174985",
+    "amount": 10000,
+    "currency": "USD",
+    "reauthorizedAt": "2025-01-22T12:34:56.789Z",
+    "expiryDate": "2025-02-22T12:34:56.789Z",
+    "merchantReference": "ORDER-12345"
+  }
+}
+```
+
+---
+
+## Testing Checklist
+
+### 1. Configuration Testing
+- [ ] Fluent Commerce connection configured
+- [ ] Payment gateway connection configured (Adyen)
+- [ ] All activation variables set
+- [ ] Provider can be swapped (test Stripe if implemented)
+
+### 2. Webhook Testing (All 4)
+- [ ] Capture webhook works
+- [ ] Refund webhook works
+- [ ] Auth Cancel webhook works
+- [ ] ReAuth webhook works
+
+### 3. Idempotency Testing
+- [ ] Duplicate capture calls return same result
+- [ ] Duplicate refund calls return same result
+- [ ] Duplicate cancel calls return same result
+- [ ] Duplicate reauth calls return same result
+
+### 4. Event Testing
+- [ ] Capture event sent to Fluent
+- [ ] Refund event sent to Fluent
+- [ ] Cancel event sent to Fluent
+- [ ] ReAuth event sent to Fluent
+
+### 5. Provider Swap Testing (Future)
+- [ ] Switch to Stripe provider
+- [ ] Verify all 4 flows work with Stripe
+- [ ] Verify events still sent correctly
+
+---
+
+## Deployment Steps
+
+1. **Set up Connections**:
+   - Configure `fluent_commerce` connection (OAuth2)
+   - Configure `payment_gateway` or `adyen_payment_gateway` connection (API key)
+
+2. **Set Activation Variables**:
+   - `fluentRetailerId`
+   - `paymentProvider` (default: `adyen`)
+   - `paymentProviderEnvironment` (test/live)
+   - `adyenMerchantAccount` (if using Adyen)
+   - `webhookSecret` (optional)
+
+3. **Deploy Workflow**:
+   ```bash
+   cd versori-payment-gateway-integration
+   npm install
+   versori deploy
+   ```
+
+4. **Configure Fluent Workflows**:
+   - Point webhook URLs to Versori endpoints:
+     - `/payment-capture`
+     - `/payment-refund`
+     - `/payment-auth-cancel`
+     - `/payment-reauth`
+
+5. **Test End-to-End**:
+   - Test each webhook from Fluent Workflow
+   - Verify payment provider API calls
+   - Verify events sent to Fluent Commerce
+   - Check Versori logs for errors
+
+---
+
+## Key Benefits of This Architecture
+
+✅ **Single Connector** - All 4 flows in one document/workflow  
+✅ **Provider Agnostic** - Easy to swap Adyen → Stripe (change one service)  
+✅ **DRY Principle** - Shared services used by all webhooks  
+✅ **Maintainable** - Clear separation of concerns  
+✅ **Testable** - Each layer can be tested independently  
+✅ **Scalable** - Easy to add new payment providers or operations  
+
+---
+
+## Future Enhancements
+
+### Adding Stripe Support
+
+1. Create `StripePaymentProviderService` implementing `PaymentProviderService`
+2. Add case to `PaymentProviderFactory`
+3. Update activation variables
+4. **Done!** All 4 webhooks automatically use Stripe
+
+### Adding PayPal Support
+
+Same pattern - implement interface, add to factory, configure variables.
+
+### Adding New Operations
+
+1. Add method to `PaymentProviderService` interface
+2. Implement in all provider services
+3. Add webhook workflow
+4. Add event service method
+5. **Done!**
+
+---
+
+This template provides a complete, modular, provider-agnostic payment gateway integration that's easy to maintain and extend!
+