--- name: payment-gateways-stripe-adyen-integration description: Architect and implement secure, PCI-DSS compliant payment processing integrations with Stripe and Adyen, featuring idempotent webhook handling, tokenization, multi-currency processing, automatic retries, and ledger-based reconciliation. --- # Payment Gateways Integration Architecture (Stripe & Adyen) This skill package provides enterprise-grade patterns, architectural principles, PCI-DSS v4.0 compliance guidelines, and production code implementations for orchestrating payment processing across **Stripe** and **Adyen**. --- ## 1. Core Architectural & Compliance Standards ### PCI-DSS v4.0 Compliance & Tokenization - **Out-of-Scope Architecture (SAQ A / SAQ A-EP)**: Never ingest, process, or store Raw Primary Account Numbers (PAN), Card Verification Values (CVV/CVC), or PINs on your infrastructure. Use client-side SDKs (Stripe Elements / Adyen Web Drop-in) to tokenization endpoints directly owned by payment service providers (PSPs). - **Network & Transport Layer Security**: All API endpoints and client SDK communications must enforce TLS 1.3 with strong cipher suites (e.g., `TLS_AES_256_GCM_SHA384`). - **Data Sanitization & Zero Logging**: Redact all sensitive fields from application logs, trace contexts, and error payloads. Never log header signatures, API tokens, raw webhook payloads with PII, or tokens susceptible to account takeover. ### Webhook Idempotency & Replay Protection - **Idempotency Keying**: Webhook events must be processed exactly once using distributed locking (e.g., Redis `SET key value NX PX`) keyed by the unique Event ID (`event.id` for Stripe, `eventCode` + `pspReference` for Adyen). - **Time-Window & Signature Verification**: Reject webhooks missing cryptographic HMAC signatures or with timestamps older than 300 seconds to prevent replay attacks. - **Asynchronous Execution**: Webhook HTTP handlers must validate signatures, enqueue the event into an isolated message queue (e.g., Kafka / RabbitMQ), and return an immediate HTTP `200 OK` within 500ms to avoid PSP retry loops. ### Reconciliation & Ledger Architecture - **Double-Entry Bookkeeping**: Model payments as state transitions across double-entry ledger accounts (Asset: PSP Clearing, Revenue, Expense: Gateway Fees, Liability: Customer Balance). - **State Machine Integrity**: Enforce strict status transitions (`AUTHORIZED` -> `CAPTURED` -> `SETTLED` / `REFUNDED` / `DISPUTED`). --- ## 2. PSP Capabilities Comparison Matrix | Capability | Stripe Integration | Adyen Integration | | :--- | :--- | :--- | | **Client Tokenization** | Stripe Elements / PaymentIntents API | Adyen Drop-in / Components API | | **Webhook Verification** | HMAC-SHA256 (`Stripe-Signature` header) | HMAC-SHA256 Base64 encoded payload validation | | **Capture Model** | Immediate or Manual (`capture_method: 'manual'`) | Automatic, Manual, or Delayed Capture rules | | **Payout & Settlement** | Balance Transactions & Payouts API | Financial Reports (Settlement Detail Report) | | **Global Payment Methods** | iDEAL, SEPA, Klarna, Alipay via PaymentIntents | 250+ local payment methods via `/payments` | --- ## 3. Production Code Implementations ### Python Implementation: Production-Grade Webhook Handler with Redis Idempotency & HMAC Validation ```python import base64 import hashlib import hmac import json import time import logging from typing import Dict, Any, Optional import redis import stripe logger = logging.getLogger("payment_orchestrator") logger.setLevel(logging.INFO) class PaymentWebhookProcessor: def __init__(self, stripe_webhook_secret: str, adyen_hmac_key: str, redis_client: redis.Redis): self.stripe_webhook_secret = stripe_webhook_secret self.adyen_hmac_key = adyen_hmac_key self.redis = redis_client self.lock_ttl_ms = 60000 # 60s processing lock def process_stripe_webhook(self, raw_body: bytes, sig_header: str) -> Dict[str, Any]: """ Validates Stripe signature, enforces idempotency, and queues event. """ try: event = stripe.Webhook.construct_event( payload=raw_body, sig_header=sig_header, secret=self.stripe_webhook_secret, tolerance=300 ) except stripe.error.SignatureVerificationError as e: logger.error("Invalid Stripe webhook signature", exc_info=True) raise ValueError("Invalid signature") from e event_id = event["id"] event_type = event["type"] if not self._acquire_idempotency_lock(f"stripe:{event_id}"): logger.info(f"Duplicate Stripe event skipped: {event_id}") return {"status": "already_processed", "event_id": event_id} try: self._route_stripe_event(event_type, event["data"]["object"]) return {"status": "success", "event_id": event_id} except Exception as e: # Release lock on processing error to allow retry self.redis.delete(f"stripe:{event_id}") raise e def verify_adyen_hmac(self, notification_item: Dict[str, Any]) -> bool: """ Verifies Adyen HMAC signature according to Adyen HMAC validator specs. """ item = notification_item.get("NotificationRequestItem", {}) hmac_signature = item.get("additionalData", {}).get("hmacSignature") if not hmac_signature: return False keys = [ "pspReference", "originalReference", "merchantAccountCode", "merchantReference", "value", "currency", "eventCode", "success" ] # Format string to sign signed_vals = [] for k in keys: val = str(item.get(k, "") or "") # Escape backslashes and colons escaped_val = val.replace("\\", "\\\\").replace(":", "\\:") signed_vals.append(escaped_val) payload_to_sign = ":".join(signed_vals).encode("utf-8") hmac_key_bytes = bytes.fromhex(self.adyen_hmac_key) calculated_hmac = base64.b64encode( hmac.new(hmac_key_bytes, payload_to_sign, hashlib.sha256).digest() ).decode("utf-8") return hmac.compare_digest(calculated_hmac, hmac_signature) def process_adyen_webhook(self, notification_payload: Dict[str, Any]) -> Dict[str, Any]: """ Processes Adyen notification items with HMAC validation and idempotency. """ items = notification_payload.get("notificationItems", []) processed = [] for container in items: item = container.get("NotificationRequestItem", {}) if not self.verify_adyen_hmac(container): logger.error("Adyen HMAC signature mismatch") continue psp_ref = item.get("pspReference") event_code = item.get("eventCode") idempotency_key = f"adyen:{psp_ref}:{event_code}" if not self._acquire_idempotency_lock(idempotency_key): logger.info(f"Duplicate Adyen notification skipped: {idempotency_key}") processed.append({"pspReference": psp_ref, "status": "duplicate"}) continue # Process notification logic self._route_adyen_event(event_code, item) processed.append({"pspReference": psp_ref, "status": "processed"}) return {"status": "ok", "processed": processed} def _acquire_idempotency_lock(self, lock_key: str) -> bool: """Atomic Redis distributed lock for idempotency enforcement.""" return bool(self.redis.set(lock_key, "1", nx=True, px=self.lock_ttl_ms)) def _route_stripe_event(self, event_type: str, data_object: Dict[str, Any]): if event_type == "payment_intent.succeeded": payment_intent_id = data_object["id"] amount = data_object["amount"] currency = data_object["currency"] logger.info(f"Stripe Payment Succeeded: {payment_intent_id} | {amount}{currency}") # Execute double-entry ledger settlement... elif event_type == "charge.dispute.created": dispute_id = data_object["id"] logger.warning(f"Stripe Dispute Created: {dispute_id}") def _route_adyen_event(self, event_code: str, item: Dict[str, Any]): if event_code == "AUTHORISATION" and item.get("success") == "true": psp_ref = item["pspReference"] val = item.get("value", {}).get("value") currency = item.get("value", {}).get("currency") logger.info(f"Adyen Authorisation Succeeded: {psp_ref} | {val} {currency}") ``` --- ### TypeScript Implementation: Modern Payment Intent & Checkout Orchestration ```typescript import stripe from 'stripe'; import crypto from 'crypto'; export interface PaymentRequest { merchantReference: string; amountCents: number; currency: string; paymentMethodToken: string; customerId: string; } export interface PaymentResult { transactionId: string; status: 'AUTHORIZED' | 'CAPTURED' | 'REQUIRES_ACTION' | 'FAILED'; clientSecret?: string; rawResponse: Record; } export class StripePaymentProvider { private stripeClient: stripe; constructor(apiKey: string) { this.stripeClient = new stripe(apiKey, { apiVersion: '2023-10-16', typescript: true, }); } /** * Orchestrates PaymentIntent creation with 3D Secure 2.0 Strong Customer Authentication (SCA) */ public async createPaymentIntent(req: PaymentRequest): Promise { const idempotencyKey = crypto .createHash('sha256') .update(`${req.merchantReference}-${req.amountCents}-${req.currency}`) .digest('hex'); try { const intent = await this.stripeClient.paymentIntents.create( { amount: req.amountCents, currency: req.currency.toLowerCase(), customer: req.customerId, payment_method: req.paymentMethodToken, confirm: true, off_session: false, capture_method: 'manual', // Auth and capture separated for risk checks confirmation_method: 'automatic', metadata: { merchant_reference: req.merchantReference, }, }, { idempotencyKey, } ); if (intent.status === 'requires_action' || intent.status === 'requires_source_action') { return { transactionId: intent.id, status: 'REQUIRES_ACTION', clientSecret: intent.client_secret ?? undefined, rawResponse: intent as unknown as Record, }; } if (intent.status === 'requires_capture') { return { transactionId: intent.id, status: 'AUTHORIZED', rawResponse: intent as unknown as Record, }; } throw new Error(`Unexpected PaymentIntent status: ${intent.status}`); } catch (err: any) { throw new Error(`Stripe Payment Intent Execution Failed: ${err.message}`); } } /** * Captures a previously authorized payment after manual anti-fraud review */ public async captureAuthorizedPayment(paymentIntentId: string, amountToCaptureCents?: number): Promise { const captureOptions: stripe.PaymentIntentCaptureParams = {}; if (amountToCaptureCents) { captureOptions.amount_to_capture = amountToCaptureCents; } const intent = await this.stripeClient.paymentIntents.capture(paymentIntentId, captureOptions); return { transactionId: intent.id, status: 'CAPTURED', rawResponse: intent as unknown as Record, }; } } ``` --- ## 4. Anti-Patterns & Pitfalls ### Critical Architectural Mistakes 1. **Processing Webhooks Synchronously in HTTP Worker Threads** - *Impact*: Gateways like Stripe/Adyen time out after 5-10 seconds and re-send webhooks, causing cascading duplicate executions and worker thread starvation. - *Remediation*: Accept payload, verify HMAC, publish event to broker (Kafka/AWS SQS), return HTTP 200 immediately. 2. **Using Floating-Point Numbers for Currency Operations** - *Impact*: IEEE 754 floating-point rounding errors (`0.1 + 0.2 = 0.30000000000000004`) lead to balance mismatches in accounting ledgers. - *Remediation*: Always store and compute amounts as 64-bit integers in minor currency units (cents, pence) or fixed-point decimal objects (`Decimal`). 3. **Ignoring Client-Side 3D-Secure (3DS2) Challenge Flows** - *Impact*: Soft-deletes and authorization rejections increase due to PSD2 SCA requirements in Europe and worldwide mandate compliance. - *Remediation*: Correctly propagate `requires_action` states back to client SDKs to render 3DS authentication modals. 4. **Storing API Keys or Webhook Secrets in Code Repositories** - *Impact*: Secrets leak, leading to unauthorized refund triggers, customer data breach, or fraud. - *Remediation*: Inject secrets using KMS (HashiCorp Vault, AWS Secrets Manager) and support seamless secret rotation. --- ## 5. Verification & Testing Playbook - **Stripe CLI Webhook Testing**: ```bash stripe listen --forward-to localhost:8080/api/v1/webhooks/stripe stripe trigger payment_intent.succeeded ``` - **Adyen Mock Webhook Replay**: Test HMAC generation using official Adyen test payload fixtures and verify zero-drop idempotency under simulated concurrent execution. - **Chaos & Failure Testing**: Simulate network splits during capture API calls and verify double-entry ledger idempotency keys prevent double charging.