ServicesCrelio AppArchitectureApp Modules

payments

Payment gateway integrations and transaction processing

Payments App Architecture

Domain Responsibility

What This App Owns

  • Payment gateway clients - Stripe, Razorpay, PhonePe, etc.
  • Transaction management - Payment recording and status
  • Customer profiles - Saved payment methods
  • Gateway configuration - API keys and settings

What It Depends On

  • core/ - BaseModel, utilities
  • admin/ - Labs, settings
  • finance/ - Billing for payment context

What Should NOT Be Added Here

  • Bill management (belongs in finance/)
  • Invoice generation (belongs in finance/)
  • B2B transactions (evaluated per case)

Model-Centric Design (Fat Models)

Key Models

ModelResponsibilityKey Fields
PaymentsPayment recordamount, status, gateway, transaction_id
PaymentGatewayTransactionsGateway responsesgateway_response, status
PaymentGatewayKeysCredentialsgateway, api_key, secret_key
CustomerPaymentProfilesSaved methodscustomer_id, card_token
OnlinePaymentOnline payment linklink, amount, expiry

Gateway Clients

Each gateway has a dedicated client:

payments/clients/
├── stripe/
│   ├── client.py
│   └── views.py
├── razorpay/
│   ├── client.py
│   └── views.py
├── phonepe/
│   ├── client.py
│   └── views.py
├── phonepev1/
├── paytabs/
├── pesopay/
└── square/

Client Pattern

# payments/clients/stripe/client.py
class StripeClient:
    def __init__(self, api_key):
        self.client = stripe
        self.client.api_key = api_key
    
    def create_payment_intent(self, amount, currency, metadata):
        return self.client.PaymentIntent.create(
            amount=amount,
            currency=currency,
            metadata=metadata
        )
    
    def process_webhook(self, payload, signature):
        event = stripe.Webhook.construct_event(
            payload, signature, self.webhook_secret
        )
        return self.handle_event(event)

API Layer (Wiring)

Endpoint Map

EndpointViewPurpose
POST /payments/initiateInitiatePaymentViewStart payment
POST /payments/webhook/{gateway}WebhookViewGateway callbacks
GET /payments/status/{id}StatusViewCheck status
POST /payments/refundRefundViewProcess refund

Integrations

Supported Gateways

GatewayRegionFeatures
StripeGlobalCards, Apple/Google Pay
RazorpayIndiaUPI, Cards, Netbanking
PhonePeIndiaUPI
PaytabsMENACards
SquareUSPOS, Cards
PesopayPhilippinesCards

Webhook Flow


Safe Extension Guide

Adding New Gateway

  1. Create directory: payments/clients/{gateway}/
  2. Add files:
    payments/clients/gateway/
    ├── __init__.py
    ├── client.py    # API client
    └── views.py     # Webhook handler
  3. Register in URL routing
  4. Add gateway to PaymentGatewayKeys

Patterns to Follow

  • Store credentials encrypted
  • Validate webhook signatures
  • Idempotent transaction handling

File Map

On this page