import uuid

import datetime
from typing import Dict, List, Optional
from enum import Enum
import hashlib
import json

class PaymentStatus(Enum):
PENDING = "pending"
AUTHORIZED = "authorized"
CAPTURED = "captured"
FAILED = "failed"
REFUNDED = "refunded"
VOIDED = "voided"

class PaymentMethod(Enum):
CREDIT_CARD = "credit_card"
DEBIT_CARD = "debit_card"
BANK_TRANSFER = "bank_transfer"
DIGITAL_WALLET = "digital_wallet"

class CreditCard:
def __init__(self, card_number: str, expiry_month: int, expiry_year: int, cvv:
str, holder_name: str):
self.card_number = self._mask_card_number(card_number)
self.expiry_month = expiry_month
self.expiry_year = expiry_year
self.cvv = "***" # Store securely or don't store at all
self.holder_name = holder_name
self._validate()

def _mask_card_number(self, card_number: str) -> str:

return "X" * (len(card_number) - 4) + card_number[-4:]

def _validate(self) -> bool:

# Implement card validation logic (Luhn algorithm, expiry date check, etc.)
# Simplified for this example
if len(self.card_number.replace('X', '')) != 4:
raise ValueError("Invalid card number")

if not (1 <= self.expiry_month <= 12):

raise ValueError("Invalid expiry month")

current_year = datetime.datetime.now().year
if not (current_year <= self.expiry_year <= current_year + 10):
raise ValueError("Invalid expiry year")

return True

class Transaction:
def __init__(self,
amount: float,
currency: str,
payment_method: PaymentMethod,
payment_details: Dict,
merchant_id: str,
customer_id: Optional[str] = None,
description: Optional[str] = None):
self.transaction_id = str(uuid.uuid4())
 self.amount = amount
self.currency = currency
self.payment_method = payment_method
self.payment_details = payment_details
self.merchant_id = merchant_id
self.customer_id = customer_id
self.description = description
self.status = PaymentStatus.PENDING
self.created_at = datetime.datetime.now()
self.updated_at = self.created_at
self.error_message = None

def to_dict(self) -> Dict:

return {
"transaction_id": self.transaction_id,
"amount": self.amount,
"currency": self.currency,
"payment_method": self.payment_method.value,
"merchant_id": self.merchant_id,
"customer_id": self.customer_id,
"description": self.description,
"status": self.status.value,
"created_at": self.created_at.isoformat(),
"updated_at": self.updated_at.isoformat(),
"error_message": self.error_message
}

def update_status(self, status: PaymentStatus, error_message: Optional[str] =

None):
self.status = status
self.error_message = error_message
self.updated_at = datetime.datetime.now()

class PaymentGateway:
def __init__(self, gateway_name: str, api_key: str, api_secret: str):
self.gateway_name = gateway_name
self.api_key = api_key
self.api_secret = api_secret
self.transactions: List[Transaction] = []

def authorize(self, transaction: Transaction) -> Dict:

"""
Authorize a payment (validate card, check funds, but don't capture payment)
"""
# In a real implementation, this would communicate with external payment
processor
try:
# Simulate communication with payment processor
self._simulate_external_auth(transaction)

transaction.update_status(PaymentStatus.AUTHORIZED)
self.transactions.append(transaction)

return {
"success": True,
"transaction_id": transaction.transaction_id,
"status": transaction.status.value
}
except Exception as e:
 transaction.update_status(PaymentStatus.FAILED, str(e))
self.transactions.append(transaction)

return {
"success": False,
"transaction_id": transaction.transaction_id,
"status": transaction.status.value,
"error": str(e)
}

def capture(self, transaction_id: str, amount: Optional[float] = None) -> Dict:

"""
Capture previously authorized payment
"""
transaction = self._get_transaction(transaction_id)

if not transaction:
return {"success": False, "error": "Transaction not found"}

if transaction.status != PaymentStatus.AUTHORIZED:
return {"success": False, "error": f"Transaction in invalid state:
{transaction.status.value}"}

# Amount to capture (default to full transaction amount)

capture_amount = amount if amount else transaction.amount

if capture_amount > transaction.amount:

return {"success": False, "error": "Capture amount exceeds authorized
amount"}

try:
# Simulate actual capture with payment processor
self._simulate_external_capture(transaction, capture_amount)

transaction.update_status(PaymentStatus.CAPTURED)

return {
"success": True,
"transaction_id": transaction.transaction_id,
"status": transaction.status.value,
"amount_captured": capture_amount
}
except Exception as e:
transaction.update_status(PaymentStatus.FAILED, str(e))

return {
"success": False,
"transaction_id": transaction.transaction_id,
"status": transaction.status.value,
"error": str(e)
}

def void(self, transaction_id: str) -> Dict:

"""
Void (cancel) an authorized transaction that hasn't been captured
"""
transaction = self._get_transaction(transaction_id)

if not transaction:
 return {"success": False, "error": "Transaction not found"}

if transaction.status != PaymentStatus.AUTHORIZED:
return {"success": False, "error": f"Cannot void transaction in state:
{transaction.status.value}"}

try:
# Simulate communication with payment processor to void
self._simulate_external_void(transaction)

transaction.update_status(PaymentStatus.VOIDED)

return {
"success": True,
"transaction_id": transaction.transaction_id,
"status": transaction.status.value
}
except Exception as e:
return {
"success": False,
"transaction_id": transaction.transaction_id,
"error": str(e)
}

def refund(self, transaction_id: str, amount: Optional[float] = None) -> Dict:

"""
Refund a captured transaction
"""
transaction = self._get_transaction(transaction_id)

if not transaction:
return {"success": False, "error": "Transaction not found"}

if transaction.status != PaymentStatus.CAPTURED:
return {"success": False, "error": f"Cannot refund transaction in
state: {transaction.status.value}"}

# Amount to refund (default to full transaction amount)

refund_amount = amount if amount else transaction.amount

if refund_amount > transaction.amount:

return {"success": False, "error": "Refund amount exceeds captured
amount"}

try:
# Simulate communication with payment processor for refund
self._simulate_external_refund(transaction, refund_amount)

transaction.update_status(PaymentStatus.REFUNDED)

return {
"success": True,
"transaction_id": transaction.transaction_id,
"status": transaction.status.value,
"amount_refunded": refund_amount
}
except Exception as e:
return {
"success": False,
 "transaction_id": transaction.transaction_id,
"error": str(e)
}

def get_transaction(self, transaction_id: str) -> Optional[Dict]:

"""
Get transaction details by ID
"""
transaction = self._get_transaction(transaction_id)

if not transaction:
return None

return transaction.to_dict()

def generate_webhook_signature(self, payload: Dict, secret: str) -> str:

"""
Generate signature for webhook payloads
"""
payload_string = json.dumps(payload, sort_keys=True)
return hashlib.sha256(f"{payload_string}{secret}".encode()).hexdigest()

def _get_transaction(self, transaction_id: str) -> Optional[Transaction]:

"""
Internal method to get transaction by ID
"""
for transaction in self.transactions:
if transaction.transaction_id == transaction_id:
return transaction
return None

def _simulate_external_auth(self, transaction: Transaction):

"""
Simulate communication with payment processor for authorization
In a real implementation, this would make API calls to a payment processor
"""
# Simulate card validation
if transaction.payment_method == PaymentMethod.CREDIT_CARD:
card_details = transaction.payment_details
# Simulate some validation rules
if card_details.get('card_number', '').endswith('0000'):
raise ValueError("Card declined: test decline card")

def _simulate_external_capture(self, transaction: Transaction, amount: float):

"""
Simulate communication with payment processor for capture
"""
# Simulation logic for capture
pass

def _simulate_external_void(self, transaction: Transaction):

"""
Simulate communication with payment processor for void
"""
# Simulation logic for void
pass

def _simulate_external_refund(self, transaction: Transaction, amount: float):

"""
 Simulate communication with payment processor for refund
"""
# Simulation logic for refund
pass

# Example usage
def main():
# Initialize payment gateway
gateway = PaymentGateway(
gateway_name="Example Payment Gateway",
api_key="live_api_key_123456",
api_secret="live_api_secret_abcdef"
)

# Create credit card payment

try:
card = CreditCard(
card_number="4111111111111111",
expiry_month=12,
expiry_year=2025,
cvv="123",
holder_name="John Doe"
)

# Create a transaction
transaction = Transaction(
amount=99.99,
currency="USD",
payment_method=PaymentMethod.CREDIT_CARD,
payment_details={
"card_number": card.card_number,
"expiry_month": card.expiry_month,
"expiry_year": card.expiry_year,
"holder_name": card.holder_name
},
merchant_id="merchant_12345",
customer_id="customer_6789",
description="Purchase of Premium Subscription"
)

# Process the payment

print("1. Authorizing payment...")
auth_result = gateway.authorize(transaction)
print(f"Authorization result: {auth_result}")

if auth_result["success"]:
transaction_id = auth_result["transaction_id"]

# Capture the authorized payment

print("\n2. Capturing payment...")
capture_result = gateway.capture(transaction_id)
print(f"Capture result: {capture_result}")

# Get transaction details

print("\n3. Transaction details:")
transaction_details = gateway.get_transaction(transaction_id)
print(f"Transaction details: {transaction_details}")

# Process refund
 print("\n4. Refunding payment...")
refund_result = gateway.refund(transaction_id, 50.00)
print(f"Refund result: {refund_result}")

# Example of a void operation (with a new transaction)

print("\n5. Creating another transaction to demonstrate void...")
transaction2 = Transaction(
amount=199.99,
currency="USD",
payment_method=PaymentMethod.CREDIT_CARD,
payment_details={
"card_number": card.card_number,
"expiry_month": card.expiry_month,
"expiry_year": card.expiry_year,
"holder_name": card.holder_name
},
merchant_id="merchant_12345",
customer_id="customer_6789",
description="Purchase of Annual Subscription"
)

auth_result2 = gateway.authorize(transaction2)
print(f"Authorization result: {auth_result2}")

if auth_result2["success"]:
transaction_id2 = auth_result2["transaction_id"]

# Void the authorized payment

print("\n6. Voiding payment...")
void_result = gateway.void(transaction_id2)
print(f"Void result: {void_result}")

except ValueError as e:
print(f"Error: {e}")

if __name__ == "__main__":
main()

======================
Core Components

Payment Status & Method Enums

PaymentStatus: Tracks the lifecycle of a transaction (pending, authorized,

captured, failed, etc.)
PaymentMethod: Different payment methods supported (credit cards, debit cards, bank
transfers, digital wallets)

CreditCard Class

Handles credit card information with proper security (masking card numbers, never
storing CVV)
Performs basic validation on card details
In a real implementation, would include more comprehensive validation using
algorithms like Luhn's
Transaction Class

Represents a single payment transaction

Stores all relevant details (amount, currency, status, timestamps, etc.)
Each transaction has a unique ID generated using UUID
Maintains a history of status changes

PaymentGateway Class

Main service provider that handles all payment processing operations

Maintains a collection of transactions
Provides methods for the entire payment lifecycle

Payment Processing Flow

Authorization

First step in processing a payment

Validates the payment method and checks if funds are available
Does NOT actually move money at this stage
Card is only "reserved" or "authorized" for the amount

Capture

Actually charges the pre-authorized payment

Can capture the full amount or a partial amount
Moves money from customer to merchant account
Can only be done on authorized transactions

Void

Cancels an authorized transaction before it's captured

Used when you decide not to complete a transaction after authorization
No money changes hands in a voided transaction

Refund

Returns money to customer after a successful capture

Can be full or partial refund
Can only be done on captured transactions

Security Features

Card number masking (storing only last 4 digits)

Not storing sensitive data like CVV codes
Webhook signature generation to verify webhook authenticity
Status validation to prevent invalid operation sequences

Simulation Logic
The code includes "simulation" methods that would, in a real implementation,
communicate with external payment processors:
_simulate_external_auth
_simulate_external_capture
_simulate_external_void
_simulate_external_refund

In a production environment, these would make API calls to payment processors like
Stripe, PayPal, or Adyen.
Example Usage
The main() function demonstrates a complete payment flow:

Create a payment gateway instance

Create and validate card details
Create a transaction
Authorize the payment
Capture the payment
Retrieve transaction details
Process a refund
Create a second transaction to demonstrate voiding

What's Missing in a Production Implementation

For production use, you would need to add:

Proper encryption of sensitive data

More robust error handling
Database storage for transactions
Webhook handlers for payment events
Comprehensive logging
Fraud detection mechanisms
Support for 3D Secure/2-factor authentication
PCI compliance measures
Integration with actual payment processors