Skip to content

Commit 467ce68

Browse files
EinswilliEinswilli
authored
Merge pull request #37 from julienho-ops/julienho-ops.docs.paygate
Docs: Add PayGate API-reference
2 parents 3812d55 + 0badfc4 commit 467ce68

File tree

1 file changed

+264
-1
lines changed

1 file changed

+264
-1
lines changed

‎docs/integrations/paygate.md‎

Lines changed: 264 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,264 @@
1-
# Under development
1+
# Under development
2+
# PayGate Integration with EasySwitch
3+
4+
## Overview
5+
6+
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.
7+
8+
## Prerequisites
9+
10+
By default, any newly created account on PayGate remains inactive until all required formalities are completed. To activate your account:
11+
12+
- EasySwitch library is installed. For setup instructions, see [Installation](../getting-started/installation.md).
13+
- Go to your Profile page in the dashboard.
14+
- Submit the necessary documents:
15+
- Business registration certificate or tax ID
16+
- ID Card
17+
- Project description
18+
- Contact details
19+
- Callback URL (Add the callback_url in the dashboard and define it in your code)
20+
21+
Once verified, your account will be activated and ready to use.
22+
After activation, your API key becomes available directly from your dashboard.
23+
24+
## Supported Countries
25+
26+
PayGate supports the following countries and payment methods:
27+
28+
| Country | Mobile Money Operators | Card Payments |
29+
|---------|----------------------|---------------|
30+
| **Togo** | Mixx By Yas, Moov | ✅ |
31+
32+
## Setup
33+
34+
### Basic Configuration
35+
36+
```python
37+
from easyswitch import (
38+
EasySwitch,
39+
TransactionDetail,
40+
Provider,
41+
TransactionStatus,
42+
Currency,
43+
TransactionType,
44+
CustomerInfo
45+
)
46+
47+
# Prepare PayGate configuration
48+
config = {
49+
"debug": True,
50+
"default_provider": Provider.PAYGATE,
51+
"providers": {
52+
"PAYGATE": {
53+
"api_key": "your_paygate_api_key",
54+
"callback_url": "your_paygate_callback_url",
55+
"timeout": 60, # timeout in seconds for HTTP requests
56+
"environment": "production", # Only Production mode for paygate
57+
},
58+
}
59+
}
60+
61+
#Initialize paygate client
62+
client = EasySwitch.from_dict(config_dict=config)
63+
64+
```
65+
66+
### Alternative Configuration Methods
67+
68+
EasySwitch supports multiple configuration methods:
69+
70+
```python
71+
# 1. From environment variables
72+
client = EasySwitch.from_env()
73+
74+
# 2. From JSON file
75+
client = EasySwitch.from_json("config.json")
76+
77+
# 3. From YAML file
78+
client = EasySwitch.from_yaml("config.yaml")
79+
80+
# 4. From multiple sources (with overrides)
81+
client = EasySwitch.from_multi_sources(
82+
env_file=".env",
83+
json_file="overrides.json"
84+
)
85+
```
86+
87+
## Configuration
88+
89+
### Environment Variables
90+
91+
Create a `.env` file or set the following environment variables:
92+
93+
```bash
94+
# PayGate Configuration
95+
PAYGATE_API_KEY=sk_production_your_api_key_here
96+
PAYGATE_ENVIRONMENT=production
97+
PAYGATE_CALLBACK_URL=your_paygate_callback_url
98+
```
99+
100+
### Authentication
101+
102+
PayGate uses API key authentication. EasySwitch automaticaly set this for requests.
103+
104+
```python
105+
headers = {
106+
'Authorization': f'Bearer {api_key}',
107+
'Content-Type': 'application/json'
108+
}
109+
```
110+
111+
> **Security Note**: Never expose your secret API key in client-side code. Always use environment variables or secure configuration management.
112+
113+
## EasySwitch Methods
114+
115+
EasySwitch provides a unified interface for all payment operations. Here are the main methods available:
116+
117+
### Core Methods
118+
119+
| Method | Description | Returns |
120+
|--------|-------------|---------|
121+
| `send_payment(transaction)` | Send a payment transaction | `PaymentResponse` |
122+
| `check_status(transaction_id, provider)` | Check transaction status | `TransactionStatus` |
123+
124+
### Configuration Methods
125+
126+
| Method | Description | Returns |
127+
|--------|-------------|---------|
128+
| `from_env(env_file)` | Initialize from environment variables | `EasySwitch` |
129+
| `from_json(json_file)` | Initialize from JSON file | `EasySwitch` |
130+
| `from_yaml(yaml_file)` | Initialize from YAML file | `EasySwitch` |
131+
| `from_dict(config_dict)` | Initialize from Python dictionary | `EasySwitch` |
132+
| `from_multi_sources(**sources)` | Initialize from multiple sources | `EasySwitch` |
133+
134+
## API Methods
135+
136+
### 1. Create Payment
137+
138+
Initiate a payment transaction using EasySwitch's `TransactionDetail` class and `send_payment` method.
139+
140+
```python
141+
# Create a TransactionDetail object
142+
transaction = TransactionDetail(
143+
transaction_id="transaction1234", # Unique ID generated by your system
144+
provider=Provider.PAYGATE,
145+
status = TransactionStatus.PENDING,
146+
amount = 100,
147+
currency=Currency.XOF,
148+
transaction_type=TransactionType.PAYMENT,
149+
customer=CustomerInfo(
150+
firstname="John",
151+
lastname="Doe",
152+
email="john.doe@email.com",
153+
phone_number="+22990123456"
154+
),
155+
reason="Product XYZ Purchase"
156+
)
157+
158+
# Send payment using EasySwitch
159+
response = client.send_payment(transaction)
160+
161+
# Check response properties
162+
print(f"Local Transaction ID: {transaction.transaction_id}") # Your internal ID
163+
print(f"FedaPay Transaction ID: {response.transaction_id}") # ID generated by FedaPay
164+
print(f"Payment URL: {response.payment_link}")
165+
print(f"Status: {response.status}")
166+
print(f"Is Successful: {response.is_successful}")
167+
print(f"Is Pending: {response.is_pending}")
168+
```
169+
170+
**Response Object (PaymentResponse):**
171+
```python
172+
PaymentResponse(
173+
transaction_id='transaction1234',
174+
provider='PAYGATE',
175+
status=<TransactionStatus.PENDING: 'pending'>,
176+
amount=100, currency=<Currency.XOF: 'XOF'>,
177+
created_at=datetime.datetime(2025, 5, 15, 22, 16, 12, 279729),
178+
expires_at=None, reference='transaction1234',
179+
payment_link='payment_link',
180+
transaction_token=None,
181+
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),
182+
raw_response={'payment_url': 'payment_link'}, metadata={})
183+
```
184+
185+
⚠️ **Important Notes**
186+
187+
- `transaction_id` in **EasySwitch** = your own internal identifier (must be unique in your system).
188+
- `transaction_id` in the **PayGate response** = the ID generated by PayGate's platform.
189+
190+
---
191+
192+
🔄 **ID Mapping Overview**
193+
194+
| Context | Field Name | Who Generates It? | Purpose |
195+
|--------------------|-----------------|-------------------|--------------------------------------------------------------|
196+
| EasySwitch (your system) | `transaction_id` | You | Internal reference to track the transaction in your own DB. |
197+
| FedaPay | `transaction_id` | FedaPay | Unique identifier in FedaPay’s system (returned after init). |
198+
199+
---
200+
201+
✅ **Best Practice**
202+
203+
- Always generate a unique `transaction_id` in your system.
204+
- Store **both IDs** (your own + PayGate's) for reconciliation.
205+
206+
### 2. Check Payment Status
207+
208+
Retrieve the current status of a payment transaction using EasySwitch's `check_status` method.
209+
210+
```python
211+
# Check transaction status
212+
transaction_id = "transaction1234"
213+
response = client.check_status(transaction_id)
214+
215+
status = response.status
216+
print(f"Status value: {status}")
217+
218+
# Check specific status types
219+
if status == TransactionStatus.SUCCESSFUL:
220+
print("Payment completed successfully!")
221+
elif status == TransactionStatus.PENDING:
222+
print("Payment is still processing...")
223+
elif status == TransactionStatus.FAILED:
224+
print("Payment failed")
225+
```
226+
227+
**Response Object (TransactionStatusResponse):**
228+
```python
229+
TransactionStatusResponse(
230+
transaction_id="transaction1234", # PayGate transaction ID (not your local one)
231+
provider=Provider.PAYGATE,
232+
status=TransactionStatus.PENDING,
233+
amount=1000.0,
234+
data={...} # Raw PayGate's transaction data
235+
)
236+
```
237+
238+
**Available TransactionStatus Values:**
239+
```python
240+
class TransactionStatus(str, Enum):
241+
PENDING = "pending"
242+
SUCCESSFUL = "successful"
243+
FAILED = "failed"
244+
ERROR = "error"
245+
CANCELLED = "cancelled"
246+
REFUSED = "refused"
247+
EXPIRED = "expired"
248+
PROCESSING = "processing"
249+
INITIATED = "initiated"
250+
COMPLETED = "completed"
251+
```
252+
253+
### 3. PayGate Limitations
254+
255+
> **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.
256+
257+
#### Unsupported Operations
258+
259+
| Operation | PayGate Support | Alternative |
260+
|-----------|----------------|-------------|
261+
| **Refunds** | ❌ Not supported | Manual processing via dashboard |
262+
| **Transaction Cancellation** | ❌ Not supported | Contact PayGate support |
263+
| **Partial Refunds** | ❌ Not supported | Manual processing via dashboard |
264+

0 commit comments

Comments
 (0)