Billing Module
The Billing module provides payment processing capabilities with support for multiple payment providers and webhook integration.
Purpose
This module handles:
- Payment transaction processing
- Multiple payment provider integration
- Webhook handling for payment notifications
- Transaction status tracking
- Payment reconciliation
Key Concepts
BillingTransaction
Payment transaction entity:
- Provider - Payment provider used
- Amount - Transaction amount
- Currency - Transaction currency
- Status - Pending, Completed, Failed, Refunded
- External ID - Provider’s transaction reference
- Metadata - Provider-specific data
Payment Providers
Supported payment gateways:
| Provider | Region | Type |
|---|---|---|
| Click | Regional | Local payment system |
| Payme | Regional | Local payment system |
| Octo | International | Payment aggregator |
| Stripe | International | Credit cards, global |
Webhooks
Provider notification system:
- Payment completion - Success notifications
- Payment failure - Error notifications
- Refunds - Refund confirmations
- Signature verification - Security validation
Architecture
Payment Flow
Initiating Payment
Components
Transactions
Transaction management:
- Create payment requests
- Track transaction status
- Handle refunds
- Reconcile with providers
Provider Integration
Provider-specific handling:
- Click - Regional payment system
- Payme - Regional payment provider
- Octo - Aggregator with multiple methods
- Stripe - International credit cards
Webhook Controllers
Secure webhook endpoints:
- Signature verification
- Idempotency handling
- Event processing
- Error recovery
Reconciliation
Payment matching:
- Compare transactions with provider reports
- Identify discrepancies
- Handle missing notifications
API Reference
REST Endpoints
Webhook and provider endpoints (no /webhooks path segment):
| Endpoint | Method | Purpose |
|---|---|---|
/billing/click/prepare | POST | Click prepare |
/billing/click/complete | POST | Click complete |
/billing/payme | POST | Payme webhook |
/billing/octo | POST | Octo webhook |
/billing/stripe | POST | Stripe webhook |
Provider APIs
Each provider has specific integration endpoints for:
- Payment initialization
- Status checking
- Refund processing
- Webhook Configuration
Permissions
The Billing module currently does not define its own permissions in the RBAC schema; access to billing controllers is governed by application-level configuration and middleware.
Integration
Finance Module
- Payment recording
- Account balance updates
- Transaction reconciliation
Events
| Event | Description |
|---|---|
PaymentInitiated | Payment started |
PaymentCompleted | Payment successful |
PaymentFailed | Payment error |
PaymentRefunded | Refund processed |
WebhookReceived | Provider notification |
Configuration
Provider Settings
Each provider requires:
- API credentials - Keys and secrets
- Webhook URL - Endpoint configuration
- Environment - Sandbox or production
- Supported currencies - Currency restrictions
Security
Webhook security measures:
- Signature verification - HMAC validation
- IP whitelisting - Provider IP restrictions
- Replay protection - Idempotency keys
- TLS encryption - HTTPS only
Best Practices
- Idempotency - Handle duplicate webhooks gracefully
- Logging - Log all provider interactions
- Reconciliation - Regular transaction matching
- Error handling - Retry failed webhooks
- Testing - Use sandbox environments
- Monitoring - Track payment success rates
Last updated on