Notes

Payment System Architecture

Bill Model Structure

Field	Type	Description
id	Integer	Unique bill identifier
backend	String	Payment backend identifier
amount	Integer	Payment amount (in smallest currency unit)
transaction_id	String	External transaction identifier
extra	Object	Additional data (order_pk, payment_method_pk, etc.)
next_step	String	URL for payment gateway redirect (if needed)
verified	Boolean	Whether payment has been verified
created_at	String (ISO 8601)	Bill creation timestamp
updated_at	String (ISO 8601)	Bill last update timestamp

Payment Method Features

• Backend Support: Multiple payment gateway backends
• Auto Approval: Configurable automatic payment approval
• Validation: Payment methods can validate cart/order compatibility
• Settings: JSON-based configuration per payment method

Order Status Flow

NEW → HOLD → PROCESSING → [SHIPPED] → [DELIVERED] → [COMPLETED]
  ↓
FAILED (if payment fails)

Error Handling

• Payment Service Errors: Returns 503 Service Unavailable
• Validation Errors: Returns 400 Bad Request with details
• Order Status Conflicts: Prevents duplicate payments
• Stock Validation: Ensures product availability during checkout

Integration Notes

Frontend Integration

1. Cart Checkout: Submit checkout form to create order
2. Payment Redirect: Handle next_step URL for external gateways
3. Success Handling: Process order key response for direct payments
4. Error Handling: Display appropriate error messages

Payment Gateway Integration

1. Bill Creation: System creates bill with payment details
2. Gateway Redirect: User redirected to payment gateway if required
3. Callback Processing: Gateway calls callback endpoint with results
4. Verification: System verifies payment with gateway
5. Order Completion: Order updated and user redirected to appropriate page

Security Considerations

• Authentication: Cart checkout requires customer authentication
• Order Access: Order checkout uses secure order keys
• Payment Verification: All payments verified with gateway before approval

Development Notes

• Payment gateway callbacks support both GET and POST methods
• Bill extra data stores order and payment method relationships
• Cart is automatically deleted after successful payment
• Order keys provide secure access to order checkout without authentication