---
title: "Payment Methods & Card Vaulting Module Documentation"
description: "Documentation for Payment Methods"
---

> **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)

---

## Table of Contents
1. [Executive Summary & PCI-DSS Scope Reduction](#1-executive-summary--pci-dss-scope-reduction)
2. [Technical Architecture & Tokenization Pipeline](#2-technical-architecture--tokenization-pipeline)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Screen Breakdown](#4-visual-interface--screen-breakdown)
5. [Card Lifecycle Management & Default Routing](#5-card-lifecycle-management--default-routing)
6. [Stripe Elements Client Tokenization](#6-stripe-elements-client-tokenization)
7. [Database Schema & Data Dictionary](#7-database-schema--data-dictionary)
8. [Diagnostic CLI & Operational Playbooks](#8-diagnostic-cli--operational-playbooks)
9. [Domain Glossary](#9-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](/screenshots/billing/client/payment-methods/payment-methods-list.png)

* **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.

---

### 4.2 Add Vaulted Payment Method Modal
Clicking **Add Payment Method** opens the secure tokenization form:

![Add Vaulted Payment Method Modal](/screenshots/billing/client/payment-methods/add-card-modal.png)

* **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:
1. **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.
2. **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.
3. **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`
```sql
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
```bash
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.