Billing

Build payment integrations, subscription management, and invoicing systems with webhook handling, tax compliance, and revenue recognition.

Security Scan

The skill's documentation matches its stated billing purpose, but the runtime instructions assume access to secrets and system resources (Stripe/Paddle webhook secrets, API keys, and DB) that the skill does not declare—this mismatch and the handling of sensitive PII/tax data is worth caution before installing.

Purpose & Capability

The name/description align with the files: Stripe integration, webhooks, subscriptions, tax, invoicing, revenue recognition, marketplace and usage billing are all present. The requested capabilities (payment handling, tax, disputes) are coherent with the content.

Instruction Scope

SKILL.md and the companion files include concrete runtime patterns that require secrets (e.g., process.env.STRIPE_WEBHOOK_SECRET, process.env.PADDLE_WEBHOOK_SECRET), a database (db.* calls), and external network calls (VIES API). The skill does not declare these env vars or config paths; the instructions therefore assume access to sensitive runtime state that is not described or scoped by the registry metadata.

Install Mechanism

This is an instruction-only skill with no install spec and no code files to execute. That reduces surface area: nothing is downloaded or written by a package installer.

Credentials

The docs demonstrate the need for Stripe API usage, webhook secrets, and database connections but the skill declares no required environment variables or config paths. It also references collection/storage of highly sensitive fields (SSN or ssn_last_4 noted in marketplace onboarding), which is plausible for KYC but should be explicitly declared and justified. The absence of declared credentials is a proportionality/visibility issue.

Persistence & Privilege

always: false and no install script means the skill does not request permanent platform privileges. The skill can be invoked autonomously (platform default), which increases practical impact if it is given access to credentials; combine that with the environment concerns above before enabling autonomous invocation.

What to consider before installing

This skill appears to be a legitimate, detailed billing playbook, but it assumes access to secrets and system resources that aren't declared. Before installing or enabling it: 1) Ask the publisher which environment variables and config paths the skill expects (Stripe API key, STRIPE_WEBHOOK_SECRET, PADDLE_WEBHOOK_SECRET, DB connection URL, etc.). 2) Never provide full card PAN/CVV; use PSP tokens and test (sandbox) keys when validating. 3) If KYC/SSN collection will occur, confirm legal requirements and minimize storage (store only what is necessary and encrypted). 4) Prefer giving the agent short-lived, scoped credentials (test keys, read-only where possible) and rotate them. 5) Require the skill to declare required env vars and any external endpoints it will contact; do not enable autonomous invocation until you understand and limit what secrets it can access. If the publisher cannot provide a clear list of required credentials and the intended data flows, treat the skill as unsafe to enable in production.

When to Use

User needs to implement or debug payment processing, subscription lifecycles, invoicing, or revenue operations. Agent handles Stripe/Paddle integration, webhook architecture, multi-currency, tax compliance, chargebacks, usage-based billing, marketplace splits, and revenue recognition patterns.

Quick Reference

Topic	File
Stripe integration	stripe.md
Webhooks & events	webhooks.md
Subscription lifecycle	subscriptions.md
Invoice generation	invoicing.md
Tax compliance	tax.md
Usage-based billing	usage-billing.md
Chargebacks & disputes	disputes.md
Marketplace payments	marketplace.md
Revenue recognition	revenue-recognition.md

Core Rules

1. Money in Smallest Units, Always

• Stripe/most PSPs use cents: amount: 1000 = $10.00
• Store amounts as integers, NEVER floats (floating-point math fails)
• Always clarify currency in variable names: amount_cents_usd
• Different currencies have different decimal places (JPY has 0, KWD has 3)

2. Webhook Security is Non-Negotiable

• ALWAYS verify signatures before processing (Stripe-Signature header)
• Store event_id and check idempotency — webhooks duplicate
• Events arrive out of order — design state machines, not sequential flows
• Use raw request body for signature verification, not parsed JSON
• See webhooks.md for implementation patterns

3. Subscription State Machine

Critical states and transitions:

State	Meaning	Access
trialing	Free trial period	✅ Full
active	Paid and current	✅ Full
past_due	Payment failed, retrying	⚠️ Grace period
canceled	Will end at period end	✅ Until period_end
unpaid	Exhausted retries	❌ None

Never grant access based on status === 'active' alone — check current_period_end.

4. Cancel vs Delete: Revenue at Stake

• cancel_at_period_end: true → Access until period ends, stops renewal
• subscription.delete() → Immediate termination, possible refund
• Confusing these loses revenue OR creates angry customers
• Default to cancel-at-period-end; immediate delete only when requested

5. Proration Requires Explicit Choice

When changing plans mid-cycle:

Mode	Behavior	Use When
create_prorations	Credit unused, charge new	Standard upgrades
none	Change at renewal only	Downgrades
always_invoice	Immediate charge/credit	Enterprise billing

Never rely on PSP defaults — specify explicitly every time.

6. Race Conditions Are Guaranteed

customer.subscription.updated fires BEFORE invoice.paid frequently.

• Design for eventual consistency
• Use database transactions for access changes
• Idempotent handlers that can safely reprocess
• Status checks before granting/revoking access

7. Tax Compliance Is Not Optional

Scenario	Action
Same country	Charge local VAT/sales tax
EU B2B + valid VAT	0% reverse charge (verify via VIES)
EU B2C	MOSS — charge buyer's country VAT
US	Sales tax varies by 11,000+ jurisdictions
Export (non-EU)	0% typically

Missing required invoice fields = legally invalid invoice. See tax.md.

8. PCI-DSS: Never Touch Card Data

• NEVER store PAN, CVV, or magnetic stripe data
• Only store PSP tokens (pm_*, cus_*)
• Tokenization happens client-side (Stripe.js, Elements)
• Even "last 4 digits + expiry" is PCI scope if stored together
• See disputes.md for compliance patterns

9. Chargebacks Have Deadlines

Stage	Timeline	Action
Inquiry	1-3 days	Provide evidence proactively
Dispute opened	7-21 days	Submit compelling evidence
Deadline missed	Automatic loss	Set alerts

3 intentos de cobro fallidos consecutivos = posible trigger de fraude monitoring.

10. Revenue Recognition ≠ Cash Collected

For SaaS under ASC 606/IFRS 15:

• Annual payment ≠ annual revenue (recognized monthly)
• Deferred revenue is a liability, not an asset
• Multi-element contracts require allocation to performance obligations
• See revenue-recognition.md for accounting patterns

Billing Traps

Security & Compliance

• Webhook without signature verification → attackers fake invoice.paid
• Storing tokens in frontend JS → extractable by attackers
• CVV in logs → PCI violation, massive fines
• Retry loops without limits → fraud monitoring triggers

Integration Errors

• Not storing subscription_id → impossible to reconcile refunds
• Assuming charge success = payment complete (3D Secure exists)
• Ignoring payment_intent.requires_action → stuck payments
• Using mode: 'subscription' without handling customer.subscription.deleted

Financial Errors

• Hardcoding tax rates → wrong when rates change
• Amounts in dollars when PSP expects cents → 100x overcharge
• Recognizing 100% revenue upfront on annual plans → audit findings
• Confusing bookings vs billings vs revenue → material discrepancies

Operational Errors

• Sending payment reminders during contractual grace period
• Dunning without checking for open disputes → double loss
• Proration without specifying mode → unexpected customer charges
• Refunding without checking for existing chargeback → paying twice