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

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:

# 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:

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

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.

# 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):

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.

# 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):

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:

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