---
title: "Payment Gateways & Electronic Settlement Module Documentation"
description: "Documentation for Payment Gateway"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [Architectural Flow & Automated Payment Settlement](#5-architectural-flow--automated-payment-settlement)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#9-glossary)

---

## 1. Module Overview (Technical)

The **Payment Gateways & Electronic Settlement** module manages the global integrations connecting **Ring2All Billing** to external merchant banking, credit card processing, and digital wallet payment gateways. It provides out-of-the-box support for:

1. **Stripe Payments & Stripe Connect:** Hosted Elements, PaymentIntents API, Customer PaymentMethods tokenization, and cryptographically verified Webhooks (`whsec_...`).
2. **PayPal REST Gateway:** Digital wallet capture and Instant Payment Notification (IPN) webhooks.
3. **Manual Bank Wire & Remittance:** Institutional ACH, Fedwire, and SEPA remittance instructions with customizable bank routing metadata and payment memo reconciliation.

### PCI-DSS SAQ A Compliance Architecture
Payment card data (PAN, CVV, expiry dates) is captured exclusively via client-side hosted iframes (Stripe Elements / Stripe Checkout). Sensitive financial credentials never traverse or touch the **Ring2All Billing** application servers, ensuring strict PCI-DSS SAQ A level compliance. Only cryptographically opaque tokens (`pm_...`, `cus_...`) are stored in the database.

---

## 2. Module Overview (Commercial & Business Value)

* **Instant Customer Self-Care Monetization:** Enables clients in the Customer Portal to execute instant prepaid wallet top-ups via debit/credit cards, keeping services active 24/7.
* **Automated Postpaid Auto-Debit:** Automatically charges customer saved payment methods upon completion of monthly billing sweeps, slashing Days Sales Outstanding (DSO) and bad debt.
* **Global Multi-Currency Settlement:** Supports billing and receiving customer settlements in USD, EUR, CAD, GBP, and Latin American currencies with automatic currency conversion.
* **Low-Fee Wholesale Wire Remittance:** Directs large-scale wholesale carrier interconnect clients to bank wire transfer options, eliminating credit card interchange processing fees on high-volume accounts.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Key Permissions | Core Responsibilities & Workflows |
| :--- | :--- | :--- |
| **Super Administrator** | Full Control & API Key Management | Inputs live production API keys, manages merchant account settings, and configures webhook endpoints. |
| **Chief Financial Officer / Controller** | Read & Bank Details Edit | Defines institutional wire transfer details, audits merchant transaction fees, and reconciles Stripe payouts. |
| **Billing Analyst** | Payment Verification | Matches incoming manual wire transfer deposits with customer ledger invoices and manually credits customer wallets. |
| **End Customer (Portal User)** | Online Checkout & Auto-Debit | Saves default credit cards for automatic monthly invoice clearance and initiates one-click prepaid wallet refills. |

---

## 4. Visual Interface & Form Structure

### 4.1 Payment Gateways Management (View)

The **Payment Gateways** interface consolidates all payment processors into dedicated, structured configuration boxes featuring toggle switches, API key visibility masking, and webhook URL copying.

![Payment Gateways Interface](/screenshots/billing/settings/system/payment-gateways/payment-gateways.png)

### 4.2 Configuration Parameters Reference

| Parameter Name | Data Type | Required | Default Value | Description & Constraints |
| :--- | :--- | :---: | :--- | :--- |
| **Stripe Gateway Enabled** | `Boolean` | Yes | `true` | Activates credit/debit card checkout and auto-debit processing across the platform. |
| **Stripe Operation Mode** | `Enum` | Yes | `live` | Operation environment: `test` (sandbox using test card 4242) or `live` (production charges). |
| **Stripe Publishable Key** | `String` | Yes (if enabled) | — | Public API key (`pk_live_...` or `pk_test_...`) used by client-side checkout iframes. |
| **Stripe Secret Key** | `String` | Yes (if enabled) | — | Restricted backend secret key (`sk_live_...` or `sk_test_...`) used to create PaymentIntents. |
| **Stripe Webhook Secret** | `String` | Yes (if enabled) | — | Signing secret (`whsec_...`) used to cryptographically verify incoming Stripe event webhooks. |
| **PayPal Gateway Enabled** | `Boolean` | Yes | `false` | Enables PayPal button checkout in the Customer Self-Care Portal. |
| **PayPal Client ID / Secret**| `String` | No | — | OAuth 2.0 API credentials from the PayPal Developer Portal. |
| **Bank Wire Instructions** | `Text` | No | Default Wire Memo | Wire instructions, bank name, IBAN/SWIFT, and mandatory customer account reference format. |

---

## 5. Architectural Flow & Automated Payment Settlement

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │           Monthly Billing Sweep Finalizes Customer Invoice             │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │  Step 1: Check Customer Default Payment Method                         │
 │  • If Postpaid & Auto-Debit Enabled: Load `customer.stripe_customer_id`│
 │  • Create `PaymentIntent` via Stripe REST API                          │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │  Step 2: External Payment Execution & Gateway Processing               │
 │  • Stripe executes charge against customer card with cardholder bank   │
 │  • Gateway dispatches asynchronous webhook: `invoice.payment_succeeded`│
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │  Step 3: Webhook Verification & Ledger Clearance                       │
 │  • Verify `Stripe-Signature` using `stripe_webhook_secret`             │
 │  • Mark Invoice status as `paid` in `public.invoices`                  │
 │  • Insert payment transaction into `public.transactions`               │
 │  • Send PDF receipt notification to customer primary email             │
 └────────────────────────────────────────────────────────────────────────┘
```

---

## 6. Common Scenarios & Operational Playbooks

### Scenario A: Configuring Stripe Webhook Integration
1. In the **Payment Gateways** module, locate the **Stripe Webhook Endpoint URL** field and click **Copy**.
2. Log into the **Stripe Dashboard** (`https://dashboard.stripe.com`).
3. Navigate to **Developers → Webhooks → Add Endpoint**.
4. Paste the copied URL (`https://billing.yourdomain.com/api/payments/webhooks/stripe`).
5. Select events: `payment_intent.succeeded`, `payment_intent.payment_failed`, and `charge.refunded`.
6. Reveal the **Signing Secret** (`whsec_...`), copy it into the **Stripe Webhook Secret** field in Ring2All Billing, and click **Save Changes**.

### Scenario B: Testing Sandbox Transactions with Test Cards
1. Set **Stripe Operation Mode** to `test`.
2. Input test API keys (`pk_test_...` and `sk_test_...`).
3. Open the **Customer Self-Care Portal** in a separate browser tab.
4. Execute a wallet top-up using test card `4242 4242 4242 4242` with any future expiry date and 3-digit CVC.
5. Verify that the wallet balance credits immediately upon successful mock charge.

---

## 7. Troubleshooting & Diagnostic Commands

### Inspect Gateway Settings in Browser Storage / Database
```javascript
// Test retrieval from local configuration cache
console.log(JSON.parse(localStorage.getItem('ring2all_billing_gateway_settings') || '{}'));
```

### Query Recent Failed Stripe Transactions
```sql
SELECT t.id, c.name, t.amount, t.gateway, t.status, t.error_message, t.created_at
FROM transactions t
JOIN customers c ON c.id = t.customer_id
WHERE t.gateway = 'stripe' AND t.status = 'failed'
ORDER BY t.created_at DESC
LIMIT 10;
```

---

## 8. Model Context Protocol (MCP) AI Integration

The **Payment Gateways & Electronic Settlement** module connects directly to the **Ring2All BSS MCP Server**, allowing billing administrators and autonomous finance copilots to verify merchant gateway connectivity and test/live mode flags safely without exposing private API keys.

### Available MCP Tools

| Tool Name | Access Role | Description & Primary Function | Example Arguments |
| :--- | :--- | :--- | :--- |
| `list_payment_gateways_status` | `Billing Operations` / `Admin` | Lists merchant payment gateways (Stripe, PayPal, Bank Wire) with configuration status, currencies, and test/live mode. | `{}` |

### Sample MCP Tool Execution: `list_payment_gateways_status`

#### Request Payload
```json
{
  "name": "list_payment_gateways_status",
  "arguments": {}
}
```

#### Response Payload
```json
[
  {
    "gateway": "stripe",
    "displayName": "Stripe Payments",
    "isEnabled": true,
    "mode": "live",
    "supportedCurrencies": ["USD", "EUR", "GBP", "CAD"],
    "webhookConfigured": true
  },
  {
    "gateway": "paypal",
    "displayName": "PayPal REST",
    "isEnabled": false,
    "mode": "sandbox",
    "supportedCurrencies": ["USD", "EUR"],
    "webhookConfigured": false
  },
  {
    "gateway": "bank_wire",
    "displayName": "Wire Transfer / Remittance",
    "isEnabled": true,
    "mode": "live",
    "supportedCurrencies": ["USD"],
    "webhookConfigured": false
  }
]
```

### Conversational AI Prompts for Copilot
* *"Which payment gateways are currently enabled in production mode?"*
* *"Is the Stripe payment gateway properly configured with active webhooks?"*
* *"What currencies are supported for customer self-care top-ups?"*

---

## 9. Glossary

* **ACH (Automated Clearing House):** Electronic bank-to-bank payment network in the United States.
* **Auto-Debit:** Automated pull transaction where the merchant charges the customer's stored credit card without requiring interactive authentication.
* **PaymentIntent:** The foundational object in Stripe representing a customer's intent to pay with full 3D Secure SCA handling.
* **PCI-DSS:** Payment Card Industry Data Security Standard governing how cardholder information is protected.
* **SAQ A:** Self-Assessment Questionnaire validating that cardholder data is completely outsourced to a validated third party (Stripe).
* **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.