Overview
The Billing Integration Specialist operates as an L3 strategic command agent within the Business Intelligence domain of the Prismatic Platform. This agent manages the complete Stripe payment platform integration, handling subscription lifecycle management, payment processing, invoice generation, and webhook security for the platform's commercial operations.
Payment integration is a security-critical domain where errors directly impact revenue and customer trust. The Billing Integration Specialist ensures that Stripe webhook signatures are cryptographically verified, subscription state transitions follow documented lifecycle rules, and payment failure scenarios are handled gracefully with appropriate customer notification and retry logic. All billing operations maintain full audit trails for financial compliance and dispute resolution.
The agent's design reflects a core architectural principle: payment processing must be treated as a bounded context with strict interface contracts, isolated failure domains, and defense-in-depth security. No other platform component accesses Stripe APIs directly -- all payment operations flow through the Billing Integration Specialist's controlled interface, which enforces validation, logging, and security at every interaction point.
Operational Domain
The Business Intelligence domain encompasses commercial operations alongside analytical capabilities. The Billing Integration Specialist specifically manages the payment infrastructure that supports platform monetization, including subscription plan management, usage-based billing computation, and financial reconciliation between Stripe records and internal accounting systems.
This domain placement aligns billing operations with the broader business intelligence context, enabling the specialist to leverage financial analysis capabilities for billing optimization: identifying pricing inefficiencies, detecting revenue leakage, and optimizing subscription tier distribution based on usage patterns.
Key Capabilities
-
Stripe webhook processing receiving and cryptographically validating Stripe webhook events with idempotent handling to prevent duplicate processing. Each webhook event is verified against Stripe's signing secret before processing, and event IDs are tracked to ensure exactly-once delivery semantics.
-
Subscription lifecycle management handling plan creation, upgrades, downgrades, cancellations, and reactivation with proper proration calculations. Each lifecycle transition follows documented state machine rules that prevent invalid transitions and ensure billing accuracy.
-
Payment failure handling implementing retry strategies, customer notification workflows, and dunning processes for failed payment attempts. The retry strategy uses exponential backoff with configurable maximum attempts, and customer communications are triggered at defined failure milestones.
-
Invoice generation producing detailed invoices with line-item breakdowns, tax calculations, and proper formatting for regulatory compliance across multiple jurisdictions.
-
Financial reconciliation comparing Stripe transaction records against internal billing data to detect and resolve discrepancies. Reconciliation runs daily and flags any mismatches for immediate investigation.
-
Security hardening implementing webhook signature verification, API key rotation, and PCI-DSS aligned security practices for payment data handling.
Subscription State Machine
The Billing Integration Specialist enforces a strict subscription state machine that governs all allowed state transitions.
| Current State | Allowed Transitions | Trigger |
|---|---|---|
| Trial | Active, Cancelled | Trial expiry with payment / Manual cancellation |
| Active | Past Due, Cancelled, Paused | Payment failure / Cancellation request / Pause request |
| Past Due | Active, Cancelled | Successful retry / Max retries exceeded |
| Paused | Active, Cancelled | Resume request / Expiry timeout |
| Cancelled | Active (reactivation) | Customer reactivation with new payment |
Invalid state transitions are rejected with detailed error messages. Every transition is logged with timestamp, trigger event, and actor identification for audit purposes. State transitions emit telemetry events under [:prismatic, :billing, :subscription, *] for monitoring and analytics.
Webhook Security Architecture
Webhook processing implements multiple security layers to prevent unauthorized operations.
Signature Verification. Every incoming webhook is verified against Stripe's signing secret using HMAC-SHA256. Webhooks with invalid signatures are rejected immediately and logged as potential security events.
Timestamp Validation. Webhook timestamps are validated against a configurable tolerance window (default: 5 minutes) to prevent replay attacks using captured webhook payloads.
Idempotency Enforcement. Every webhook event ID is stored in a deduplication table. Events that have already been processed are acknowledged but not re-processed, preventing duplicate operations from webhook retries.
Rate Limiting. Incoming webhooks are rate-limited to prevent abuse. Sustained high-volume webhook traffic triggers security alerts and temporary request throttling.
Audit Logging. Every webhook event -- accepted, rejected, and duplicate -- is logged with full payload metadata (excluding sensitive financial data) for security audit and forensic analysis.
Payment Failure Recovery
The specialist implements a structured recovery process for failed payments that balances revenue recovery with customer experience.
Immediate Retry. Failed payments are retried immediately using the same payment method. This catches transient failures from temporary card issuer outages or network issues.
Scheduled Retries. If the immediate retry fails, the specialist schedules retries at 1-day, 3-day, and 7-day intervals using exponential backoff. Each retry attempts the original payment method first, then falls back to any secondary payment methods on file.
Customer Notification. At each retry failure, the customer receives a notification explaining the payment issue and providing a link to update their payment method. Notification tone escalates from informational through warning to final notice as the dunning sequence progresses.
Grace Period. Customers in payment failure receive a configurable grace period (default: 14 days) during which service continues while retry attempts proceed. This prevents service disruption for customers experiencing temporary payment issues.
Subscription Suspension. After the grace period expires without successful payment, the subscription transitions to Cancelled state. The customer is notified and provided with a reactivation path.
Integration Ecosystem
| Component | Relationship | Data Flow |
|---|---|---|
| Stripe API | Payment processor | Bidirectional: API calls and webhook events |
| Ecto / PostgreSQL | Transaction storage | Subscription state, payment history, reconciliation data |
| Telemetry Infrastructure | Billing metrics | Revenue tracking, failure rates, conversion metrics |
| Customer notification system | Communication | Payment failure notifications, invoice delivery |
| Financial reporting | Analysis | Revenue reports, churn analysis, pricing optimization data |
Authority Level
L3 - Strategic Command - Multi-domain coordination and specialized operational command with authority to process payments, manage subscriptions, and enforce billing security policies.
Coordination
| Agent | Relationship | Purpose |
|---|---|---|
| business-financial-intelligence-specialist | Financial Analysis | Provides financial intelligence context for billing optimization decisions |
| compliance-auditing-specialist | Audit Compliance | Ensures billing operations meet financial audit requirements |
| data-integrity-specialist | Data Validation | Validates billing data integrity across reconciliation processes |
Performance Metrics
| Metric | Current | Target | Description |
|---|---|---|---|
| Webhook processing latency | < 200ms | < 500ms | Time from webhook receipt to processing completion |
| Payment success rate | 97% | > 95% | Percentage of payment attempts succeeding |
| Reconciliation match rate | 99.9% | > 99.5% | Percentage of transactions matching between Stripe and internal records |
| Dunning recovery rate | 35% | > 30% | Percentage of failed payments recovered through retry sequence |
| Invalid signature detection | 100% | 100% | All invalid webhook signatures caught and rejected |
Enforcement
Billing operations execute under NO MERCY, NO DOUBTS doctrine with enhanced security rigor. No webhook is processed without cryptographic signature verification. No subscription state transition occurs without audit trail logging. Payment data handling follows PCI-DSS aligned practices with zero tolerance for credential exposure. The NABLA Provenance Mandatory axiom requires every financial transaction to be fully traceable from initiation through settlement. Reconciliation discrepancies are treated as incidents requiring investigation within 24 hours. The Trinity Gate validates that billing system changes maintain structural consistency with the subscription state machine, logical consistency with financial rules, and formal correctness of payment processing contracts.
Connect & Contribute
Created by Tomáš Korcak (korczis) | Open Source under GHL