AllDotPy · Einswilli · Sep 26, 2025 · Sep 26, 2025
diff --git a/docs/integrations/paygate.md b/docs/integrations/paygate.md
@@ -1 +1,264 @@
-# Under development
+# Under development
+# PayGate Integration with EasySwitch
+
+## Overview
+
+As the leading integrator and pioneer of electronic payment solutions in Togo, PayGate Global enables e-merchants and Togolese organizations to accept mobile payments on both web and mobile platforms. Notably designed to reduce fraud and maximize revenue, PayGate offers a simple and secure solution for collecting online payments via mobile money.
+
+## Prerequisites
+
+By default, any newly created account on PayGate remains inactive until all required formalities are completed. To activate your account:
+
+- EasySwitch library is installed. For setup instructions, see [Installation](../getting-started/installation.md).
+- Go to your Profile page in the dashboard.
+- Submit the necessary documents:
+- Business registration certificate or tax ID
+- ID Card
+- Project description
+- Contact details
+- Callback URL (Add the callback_url in the dashboard and define it in your code)
+
+Once verified, your account will be activated and ready to use.
+After activation, your API key becomes available directly from your dashboard.
+
+## Supported Countries
+
+PayGate supports the following countries and payment methods:
+
+| Country | Mobile Money Operators | Card Payments |
+|---------|----------------------|---------------|
+| **Togo** | Mixx By Yas, Moov | ✅ |
+
+## Setup
+
+### Basic Configuration
+
+```python
+from easyswitch import (
+    EasySwitch, 
+    TransactionDetail, 
+    Provider,
+    TransactionStatus, 
+    Currency, 
+    TransactionType, 
+    CustomerInfo
+)
+
+# Prepare PayGate configuration
+config = {
+    "debug": True,
+    "default_provider": Provider.PAYGATE,
+    "providers": {
+        "PAYGATE": {
+            "api_key": "your_paygate_api_key",
+            "callback_url": "your_paygate_callback_url",
+            "timeout": 60,  # timeout in seconds for HTTP requests
+            "environment": "production",    # Only Production mode for paygate
+        },
+    }
+}
+
+#Initialize paygate client
+client = EasySwitch.from_dict(config_dict=config)
+
+```
+
+### Alternative Configuration Methods
+
+EasySwitch supports multiple configuration methods:
+
+```python
+# 1. From environment variables
+client = EasySwitch.from_env()
+
+# 2. From JSON file
+client = EasySwitch.from_json("config.json")
+
+# 3. From YAML file
+client = EasySwitch.from_yaml("config.yaml")
+
+# 4. From multiple sources (with overrides)
+client = EasySwitch.from_multi_sources(
+    env_file=".env",
+    json_file="overrides.json"
+)
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file or set the following environment variables:
+
+```bash
+# PayGate Configuration
+PAYGATE_API_KEY=sk_production_your_api_key_here
+PAYGATE_ENVIRONMENT=production
+PAYGATE_CALLBACK_URL=your_paygate_callback_url
+```
+
+### Authentication
+
+PayGate uses API key authentication. EasySwitch automaticaly set this for requests. 
+
+```python
+headers = {
+    'Authorization': f'Bearer {api_key}',
+    'Content-Type': 'application/json'
+}
+```
+
+> **Security Note**: Never expose your secret API key in client-side code. Always use environment variables or secure configuration management.
+
+## EasySwitch Methods
+
+EasySwitch provides a unified interface for all payment operations. Here are the main methods available:
+
+### Core Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `send_payment(transaction)` | Send a payment transaction | `PaymentResponse` |
+| `check_status(transaction_id, provider)` | Check transaction status | `TransactionStatus` |
+
+### Configuration Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `from_env(env_file)` | Initialize from environment variables | `EasySwitch` |
+| `from_json(json_file)` | Initialize from JSON file | `EasySwitch` |
+| `from_yaml(yaml_file)` | Initialize from YAML file | `EasySwitch` |
+| `from_dict(config_dict)` | Initialize from Python dictionary | `EasySwitch` |
+| `from_multi_sources(**sources)` | Initialize from multiple sources | `EasySwitch` |
+
+## API Methods
+
+### 1. Create Payment
+
+Initiate a payment transaction using EasySwitch's `TransactionDetail` class and `send_payment` method.
+
+```python
+# Create a TransactionDetail object
+transaction = TransactionDetail(
+    transaction_id="transaction1234",  # Unique ID generated by your system
+    provider=Provider.PAYGATE,
+    status = TransactionStatus.PENDING,
+    amount = 100,
+    currency=Currency.XOF,
+    transaction_type=TransactionType.PAYMENT,
+    customer=CustomerInfo(
+        firstname="John",
+        lastname="Doe",
+        email="john.doe@email.com",
+        phone_number="+22990123456"
+    ),
+    reason="Product XYZ Purchase"
+)
+
+# Send payment using EasySwitch
+response = client.send_payment(transaction)
+
+# Check response properties
+print(f"Local Transaction ID: {transaction.transaction_id}")  # Your internal ID
+print(f"FedaPay Transaction ID: {response.transaction_id}")   # ID generated by FedaPay
+print(f"Payment URL: {response.payment_link}")
+print(f"Status: {response.status}")
+print(f"Is Successful: {response.is_successful}")
+print(f"Is Pending: {response.is_pending}")
+```
+
+**Response Object (PaymentResponse):**
+```python
+PaymentResponse(
+  transaction_id='transaction1234', 
+  provider='PAYGATE', 
+  status=<TransactionStatus.PENDING: 'pending'>, 
+  amount=100, currency=<Currency.XOF: 'XOF'>, 
+  created_at=datetime.datetime(2025, 5, 15, 22, 16, 12, 279729), 
+  expires_at=None, reference='transaction1234', 
+  payment_link='payment_link', 
+  transaction_token=None, 
+  customer=CustomerInfo(phone_number='+22990123456', first_name='John', last_name='Doe', email='john.doe@email.com', address=None, city=None, country=None, postal_code=None, zip_code=None, state=None, id=None), 
+  raw_response={'payment_url': 'payment_link'}, metadata={})
+```
+
+⚠️ **Important Notes**
+
+- `transaction_id` in **EasySwitch** = your own internal identifier (must be unique in your system).  
+- `transaction_id` in the **PayGate response** = the ID generated by PayGate's platform.
+
+---
+
+🔄 **ID Mapping Overview**
+
+| Context            | Field Name      | Who Generates It? | Purpose                                                      |
+|--------------------|-----------------|-------------------|--------------------------------------------------------------|
+| EasySwitch (your system) | `transaction_id` | You               | Internal reference to track the transaction in your own DB.   |
+| FedaPay            | `transaction_id` | FedaPay           | Unique identifier in FedaPay’s system (returned after init).  |
+
+---
+
+✅ **Best Practice**
+
+- Always generate a unique `transaction_id` in your system.  
+- Store **both IDs** (your own + PayGate's) for reconciliation.
+
+### 2. Check Payment Status
+
+Retrieve the current status of a payment transaction using EasySwitch's `check_status` method.
+
+```python
+# Check transaction status
+transaction_id = "transaction1234"
+response = client.check_status(transaction_id)
+
+status = response.status
+print(f"Status value: {status}")
+
+# Check specific status types
+if status == TransactionStatus.SUCCESSFUL:
+    print("Payment completed successfully!")
+elif status == TransactionStatus.PENDING:
+    print("Payment is still processing...")
+elif status == TransactionStatus.FAILED:
+    print("Payment failed")
+```
+
+**Response Object (TransactionStatusResponse):**
+```python
+TransactionStatusResponse(
+    transaction_id="transaction1234",   # PayGate transaction ID (not your local one)
+    provider=Provider.PAYGATE,
+    status=TransactionStatus.PENDING,
+    amount=1000.0,
+    data={...}  # Raw PayGate's transaction data
+)
+```
+
+**Available TransactionStatus Values:**
+```python
+class TransactionStatus(str, Enum):
+    PENDING = "pending"
+    SUCCESSFUL = "successful"
+    FAILED = "failed"
+    ERROR = "error"
+    CANCELLED = "cancelled"
+    REFUSED = "refused"
+    EXPIRED = "expired"
+    PROCESSING = "processing"
+    INITIATED = "initiated"
+    COMPLETED = "completed"
+```
+
+### 3. PayGate Limitations
+
+> **Important**: PayGate does not support refunds or transaction cancellation through their API. These operations must be handled manually through the PayGate dashboard or by contacting their support team.
+
+#### Unsupported Operations
+
+| Operation | PayGate Support | Alternative |
+|-----------|----------------|-------------|
+| **Refunds** | ❌ Not supported | Manual processing via dashboard |
+| **Transaction Cancellation** | ❌ Not supported | Contact PayGate support |
+| **Partial Refunds** | ❌ Not supported | Manual processing via dashboard |
+