Payment Methods & Card Vaulting Module Documentation

Module Code: billing/client/cards
Route: /portal/cards
Backend Service: clientService.ts (ring2all-billing-api)
Database Table: payment_methods
Brand Purity: 100% White-Label Compliant (Ring2All Billing)

Executive Summary & PCI-DSS Scope Reduction
Technical Architecture & Tokenization Pipeline
🎯 User Roles & Key Capabilities
Visual Interface & Screen Breakdown
Card Lifecycle Management & Default Routing
Stripe Elements Client Tokenization
Database Schema & Data Dictionary
Diagnostic CLI & Operational Playbooks
Domain Glossary

1. Executive Summary & PCI-DSS Scope Reduction

The Payment Methods & Card Vaulting module enables customers to securely store, update, and manage multiple credit/debit cards for automated subscription renewals and on-demand wallet refills without exposing raw card numbers to Ring2All servers.

+-------------------------------------------------------------------------------+
|                       COMMERCIAL & OPERATIONAL IMPACT                         |
+-------------------------------------------------------------------------------+
| • Zero PCI Scope for Telecom Provider: Raw PANs and CVVs never touch or       |
|   traverse Ring2All backend servers; tokenization occurs in Stripe's vault.    |
| • Churn Reduction: Customers independently replace expiring or stolen cards   |
|   before monthly plan subscription renewals fail.                             |
| • One-Click Checkout: Default card designation enables friction-free top-ups |
|   and instant invoice payments across the entire portal.                      |
| • Complete Cardholder Security: Visual card displays are strictly limited to  |
|   card brand, last 4 digits, and expiration dates.                            |
+-------------------------------------------------------------------------------+

2. Technical Architecture & Tokenization Pipeline

When a customer registers a payment card, the client portal communicates directly with Stripe Elements to create a tokenized PaymentMethod ID (pm_...), which is then safely linked to the customer’s account:

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Client Web Browser (Portal UI)                    │
 │                      Route: /portal/cards                              │
 └───────────────────┬────────────────────────────────┬───────────────────┘
                     │                                │
      1. Raw Card    │ Direct HTTPS                   │ 3. Vaulted Token
         Data        ▼                                │    (pm_1N2e3f...)
 ┌───────────────────────────────────┐                │
 │    Stripe Tokenization Engine     │                │
 │    • Validates CVV & Expiration   │                │
 │    • Issues Opaque Token ID       │                │
 └───────────────────┬───────────────┘                │
                     │ 2. Return Token                ▼
                     └────────────────► ┌─────────────────────────────────┐
                                        │ Ring2All Billing Core API       │
                                        │ POST /api/client/payment-methods│
                                        └────────────────┬────────────────┘
                                                         │ 4. Store Safe Metadata
                                                         ▼
                                        ┌─────────────────────────────────┐
                                        │ PostgreSQL 17 (payment_methods) │
                                        │ • brand: 'visa'                 │
                                        │ • last4: '4242'                 │
                                        │ • exp_year: 2028                │
                                        │ • gateway_method_id: 'pm_...'   │
                                        └─────────────────────────────────┘

3. 🎯 User Roles & Key Capabilities

Access to stored payment methods is strictly restricted:

User Role	Access Level	Primary Operational Capabilities
Enterprise Account Owner	Full Access	Adds new company payment cards, toggles default billing card, removes outdated cards.
Accounts Payable Manager	Card Management	Verifies card expiration dates, updates billing addresses, monitors failed transaction alerts.
Billing & Finance Auditor	Read-Only Audit	Verifies vaulted payment method count and default gateway configurations.

4. Visual Interface & Screen Breakdown

4.1 Vaulted Payment Methods Inventory

The cards interface provides a clean cardholder dashboard:

Vaulted Payment Methods Inventory

Card Brand Badges: Visual iconography representing Visa, Mastercard, American Express, or Discover.
Masked Display: Masked card representation (•••• •••• •••• 4242) ensuring complete privacy.
Expiration Date: Prominent display of valid month and year (Exp: 12/2028).
Default Card Star: Visual indicator badge designating the card used for automated plan sweeps.
Management Controls: Options to make default or permanently remove vaulted cards.

Clicking Add Payment Method opens the secure tokenization form:

Add Vaulted Payment Method Modal

Cardholder Name: Full legal billing name matching the issuing bank account.
Card Details: Hosted iframe fields capturing card number, expiration date, and CVC security code.
Set as Default Toggle: Checkbox automatically configuring the new card as primary for recurring charges.

5. Card Lifecycle Management & Default Routing

The portal enforces deterministic rules for stored cards:

Single Default Enforceability: Only one card can be flagged as is_default = true per customer. Setting a new default card automatically updates previous cards in an atomic transaction.
Deletion Safeguards: Customers cannot delete a payment method if it is currently the sole active card on an account with an active recurring subscription plan.
Automatic Expiry Tracking: Cards nearing expiration trigger portal banner warnings 30 days prior to month end.

6. Stripe Elements Client Tokenization

Under PCI-DSS SAQ-A compliance:

The web application uses Stripe Elements iframe injection.
Keystrokes for the 16-digit Primary Account Number (PAN) and 3-digit Card Verification Value (CVV) are captured directly by Stripe’s encrypted infrastructure.
Ring2All servers never log, cache, or process raw credit card numbers.

7. Database Schema & Data Dictionary

Table: `public.payment_methods`

CREATE TABLE public.payment_methods (
    id                 BIGSERIAL PRIMARY KEY,
    uuid               UUID NOT NULL DEFAULT gen_random_uuid(),
    customer_id        BIGINT NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
    gateway            VARCHAR(30) NOT NULL DEFAULT 'stripe',
    gateway_method_id  VARCHAR(100) NOT NULL,
    type               VARCHAR(30) NOT NULL DEFAULT 'card',
    brand              VARCHAR(30),
    last4              VARCHAR(4),
    exp_month          INTEGER,
    exp_year           INTEGER,
    is_default         BOOLEAN NOT NULL DEFAULT false,
    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Partial index ensuring fast default card resolution
CREATE INDEX idx_payment_methods_default ON payment_methods (customer_id) WHERE is_default = true;

8. Diagnostic CLI & Operational Playbooks

Verify Customer Vaulted Cards via Database

su - postgres -c "psql -d ss_billing -c \"
SELECT brand, last4, exp_month, exp_year, is_default, gateway_method_id
FROM payment_methods
WHERE customer_id = 5;
\""

9. Domain Glossary

Gateway Method ID: Opaque token (e.g. pm_1N2e...) representing an authorized payment instrument.
PCI-DSS SAQ-A: Payment Card Industry Self-Assessment Questionnaire A for merchants who outsource all cardholder data functions.
PAN (Primary Account Number): The 15 or 16-digit card number embossed on physical payment cards.