From 0badfc48498686b5cade4986e2bdc6f0d4b91fdb Mon Sep 17 00:00:00 2001 From: ADENOVI Yawo Julien Date: Fri, 26 Sep 2025 07:47:06 +0000 Subject: [PATCH] Docs: Add PayGate API-reference --- docs/integrations/paygate.md | 265 ++++++++++++++++++++++++++++++++++- 1 file changed, 264 insertions(+), 1 deletion(-) diff --git a/docs/integrations/paygate.md b/docs/integrations/paygate.md index 2e03555..c2b668a 100644 --- a/docs/integrations/paygate.md +++ b/docs/integrations/paygate.md @@ -1 +1,264 @@ -# Under development \ No newline at end of file +# 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=, + amount=100, currency=, + 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 | +