payment-domain-knowledge

name: payment-domain-knowledge description: Payment processing domain model for Perkcord — our role in the ecosystem, provider relationships, credential ownership, PCI scope, and merchant vs platform responsibilities. compatibility: opencode metadata: audience: maintainers repo: perkcord

Purpose

Establish a shared mental model for how Perkcord relates to the payment processing ecosystem. This skill should be loaded when working on payment provider integrations, checkout flows, credential management, onboarding, or PCI-related decisions.

Perkcord's role in the ecosystem

Perkcord is a software platform, not a payment facilitator (PayFac) and not a merchant of record. We are analogous to WooCommerce, Shopify (without Shopify Payments), or a SaaS billing tool.

What we do

• Build the checkout UI and subscribe flow
• Collect a payment token (never raw card data) via provider-hosted or provider-JS tokenization
• Send that token to the payment gateway using the guild owner's credentials
• Listen for webhooks to update entitlement state
• Sync Discord roles based on entitlement state

What we do NOT do

• Hold merchant accounts
• Go through underwriting
• Bear liability for chargebacks (the merchant does)
• Set or control transaction fee structures
• Have a direct relationship with acquiring banks or card networks
• Store, process, or transmit raw card data

The players

Credential ownership

Every set of provider credentials belongs to the merchant (the guild owner), not to Perkcord.

The guild owner:

1. Applies for a merchant account (through an ISO, processor, or directly with Stripe)
2. Goes through underwriting (business verification, financial history, risk assessment)
3. Gets approved and receives API credentials from their provider dashboard
4. Provides those credentials to Perkcord (via the admin onboarding wizard)

Current state: credentials are stored as deployment-level environment variables (one merchant per deployment). This works for single-tenant / white-label deployments. Target state (see #163): credentials will be stored encrypted per-guild in Convex so each guild owner can configure their own merchant account. See reference/credentials-by-provider.md for the specific values each provider requires.

PCI compliance scope

PCI DSS requires anyone in the payment card chain to prove security compliance via a Self-Assessment Questionnaire (SAQ). The type depends on how much card data your system touches.

Current posture: all shipping Perkcord payment collection paths are SAQ-A. Stripe uses hosted checkout, NMI uses a hosted checkout URL, and Authorize.Net uses AcceptUI.js hosted lightbox tokenization. The old Accept.js custom-form posture is now historical context only.

Invariants (from AGENTS.md)

• Never store raw card data. Always tokenize.
• Never log secrets, OAuth tokens, or full webhook bodies with PII.
• Tokenization approach per provider: Stripe handles it via hosted checkout; Authorize.Net via AcceptUI.js hosted lightbox; NMI via hosted checkout (Collect.js is a future option, not currently implemented).

Fee structure (not our concern)

Transaction fees are negotiated between the merchant and their ISO/processor. Perkcord does not set, control, or participate in these fees. We charge our own separate SaaS fee for the platform.

Typical high-risk ranges (for awareness, not something we configure):

• Transaction fee: 2.5%–5%+ per transaction
• Per-transaction flat fee: $0.10–$0.30
• Monthly gateway fee: $10–$50/mo
• Chargeback fee: $15–$100 per chargeback
• Rolling reserve: 5–10% held for 6 months

Authorize.Net recurring billing rule

When working on Authorize.Net subscriptions, do not treat ARB as an instant first-payment mechanism.

• ARB is batch-based, not real-time. Same-day starts are processed on the next overnight batch, so subscription creation alone is not proof of payment.
• The recommended Perkcord pattern is: real-time first charge now, then recurring renewals next cycle.
• Model the first payment as a customer-initiated transaction (CIT) and later renewals as stored-credential / recurring merchant-initiated transactions (MIT).
• Do not grant access from subscription.created alone unless the product explicitly supports a provisional-access state.
• Do not synthesize provider payment-success events just to make access feel instant; if provisional access is ever needed, track it as a separate internal state with its own audit trail.

Recommended implementation shape

• Tokenize card data with AcceptUI.js (preferred - SAQ-A, hosted lightbox, compatible with the ARB flow) or Accept Hosted for one-time-only flows.
• Run a real-time first createTransactionRequest / authCaptureTransaction.
• Create or fetch the stored customer payment profile from that successful charge.
• Create the ARB subscription for future renewals, with startDate aligned to the next billing period instead of "today".
• Persist the provider identifier that the eventual webhook will actually send back, so post-charge recovery paths still have a durable entitlement anchor.
• Keep payment-provider events audit-pure: real provider events come from provider responses/webhooks, not internal convenience writes.

Sharp edges

• End-of-month monthly starts must clamp to the last valid day of the target month.
• A successful immediate charge can be followed by profile-creation or ARB-setup failure; the checkout flow must avoid surfacing that as an unpaid failure while still preserving a webhook-reachable provider link.
• If the product wants "charge later, access now," use an explicit provisional-access design or ARB trial semantics; do not blur that with a paid entitlement.

Provider reference files

For provider-specific details (credentials, APIs, sandbox setup, tokenization approach), see:

• reference/credentials-by-provider.md — What credentials each provider requires and who provides them
• reference/stripe.md — Stripe-specific integration details
• reference/authorize-net.md — Authorize.Net-specific integration details
• reference/nmi.md — NMI-specific integration details

When to load this skill

• Working on checkout or subscribe flow code
• Adding or modifying a payment provider integration
• Working on the admin onboarding wizard or credential management
• Making PCI-related architecture decisions
• Answering questions about who owns what in the payment chain
• Debugging webhook or transaction failures