Payment Providers

Relevant source files

The following files were used as context for generating this wiki page:

• pp/provider.go
• pp/stripe.go
• pp/paypal.go
• pp/alipay.go
• pp/gc.go
• pp/paddle.go
• pp/lemonsqueezy.go
• object/payment.go
• web/src/backend/PaymentBackend.js
• swagger/swagger.yml

The Payment Providers system in Casdoor serves as a unified abstraction layer for integrating multiple third-party payment gateways. Its primary purpose is to handle financial transactions, manage payment states, and facilitate invoice generation across diverse providers like PayPal, Stripe, Alipay, and others. By providing a common interface, the system decouples the core business logic from the specific implementation details of individual payment APIs.

Sources: pp/provider.go:17-56, object/payment.go:20-56

Core Architecture and Interface

The system is built around a central PaymentProvider interface that defines the required behavior for any integrated payment gateway. This architecture allows Casdoor to treat different external services uniformly during the payment lifecycle.

The PaymentProvider Interface

Any new payment integration must implement the following methods:

• Pay: Initiates a payment request and returns a URL for the user to complete the transaction.
• Notify: Processes incoming notifications or status queries from the provider to update the internal payment state.
• GetInvoice: Requests an electronic invoice from the provider if supported.
• GetResponseError: Standardizes error messaging for the specific provider.

Sources: pp/provider.go:50-56

System Workflow

The diagram below illustrates the high-level flow of a payment transaction from initiation to fulfillment.

Data Models

The system relies on several structured data types to pass information between the application logic and the provider implementations.

Internal Payment Object

The Payment struct represents the persistent record of a transaction within Casdoor.

Field	Type	Description
Owner	string	The organization owning the payment.
Name	string	Unique identifier for the payment.
Provider	string	The name of the payment provider used.
State	PaymentState	Current status (Paid, Created, Canceled, etc.).
Price	float64	Total amount of the transaction.
OutOrderId	string	The reference ID from the external provider.
InvoiceUrl	string	URL to the generated invoice.

Sources: object/payment.go:24-56

Payment States

Payments transition through a defined set of states. Terminal states (Paid, Error, Canceled, Timeout) prevent further state transitions to ensure data integrity.

State	Constant	Description
Paid	PaymentStatePaid	Transaction successfully completed.
Created	PaymentStateCreated	Payment initiated but not yet settled.
Canceled	PaymentStateCanceled	Transaction aborted by user or system.
Timeout	PaymentStateTimeout	Transaction expired before completion.
Error	PaymentStateError	An error occurred during processing.

Sources: pp/provider.go:20-28, object/payment.go:174-177

Provider Implementations

Each supported provider handles specific logic for its respective API.

Stripe Integration

Stripe uses Checkout Sessions. The implementation creates a temporary product and price in Stripe for every transaction to support dynamic pricing.

• Pay: Generates a stripe.CheckoutSession.
• Notify: Retrieves the session by ID and checks Status and PaymentStatus.
  Sources: pp/stripe.go:42-124

PayPal Integration

PayPal utilizes the V2 Orders API with an intent of CAPTURE.

• Pay: Creates a PayPal order and extracts the approve link.
• Notify: Performs an OrderCapture and OrderDetail query to verify the "COMPLETED" status.
  Sources: pp/paypal.go:50-143

Specialized Providers

• Paddle: Maps Paddle's statuses (Draft, Ready, Billed, PastDue) to the internal PaymentState.
• GC (General Control): Supports complex invoice request info and MD5-based request signing.
• Lemon Squeezy: Uses custom data in checkout attributes to persist Casdoor-specific identifiers.

Sources: pp/paddle.go:102-140, pp/gc.go:121-140, pp/lemonsqueezy.go:53-73

API Endpoints

The system is managed via several RESTful endpoints defined in the Casdoor backend.

Method	Endpoint	Description
GET	/api/get-payments	Retrieves a list of payments for an organization.
POST	/api/add-payment	Creates a new internal payment record.
POST	/api/notify-payment	Triggered by external webhooks to update status.
POST	/api/invoice-payment	Triggers invoice generation for a paid payment.

Sources: web/src/backend/PaymentBackend.js:19-74, swagger/swagger.yml:340-358, swagger/swagger.yml:1025-1043

Conclusion

The Payment Providers module provides a robust, state-machine-driven framework for handling financial operations. By abstracting provider-specific logic into a common interface and maintaining terminal states, it ensures consistent transaction tracking, integration with order systems, and reliable invoice delivery across multiple global payment gateways.