Principle:Langgenius Dify PaymentIntegration
| Knowledge Sources | Dify |
|---|---|
| Domains | Frontend, Billing, Payment |
| Last Updated | 2026-02-12 07:00 GMT |
Overview
Payment Integration is the principle governing payment flow handling, including post-redirect callbacks from payment processors and confirmation modals that verify transaction completion.
Description
Dify's commercial features require integration with external payment processors for subscription management and plan upgrades. The Payment Integration principle defines how the frontend initiates payment flows, handles redirects to external payment gateways, processes the return callbacks, and confirms successful transactions to the user. This involves a multi-step flow where the user is redirected to a payment processor, completes the transaction, and is redirected back to Dify where the application must detect and process the completed payment.
In the frontend, the usePay hook orchestrates this flow by constructing payment URLs, opening the payment gateway in a new window, and monitoring for the redirect callback that signals transaction completion. Upon return, the hook parses callback parameters from the URL, verifies the transaction status, and displays a confirmation modal to the user. The hook also handles error cases such as failed payments, cancelled transactions, and network timeouts during the callback processing phase. State management ensures that the UI reflects the payment status throughout the entire flow.
This principle is important because payment flows are among the most sensitive user interactions in any application. Failures or ambiguities in the payment process can result in financial discrepancies, user frustration, and support burden. The Payment Integration principle ensures that the flow is robust, provides clear feedback at every step, and handles edge cases gracefully. It also maintains a clean separation between the payment UI logic and the underlying payment provider, allowing the system to support different payment processors without modifying the core flow.
Usage
Use this principle when:
- Implementing or modifying subscription purchase flows
- Adding new payment providers or payment methods
- Building UI components that display payment status or transaction history
Theoretical Basis
This principle follows the Redirect-Based Payment Flow pattern used by most modern payment processors (Stripe, PayPal, etc.), where the application delegates the sensitive payment data collection to the processor's hosted page and processes the result via redirect callbacks. It applies the State Machine pattern to model the payment lifecycle (initiated, processing, completed, failed), ensuring that transitions are well-defined and that the UI always reflects the current state. The callback processing follows the Return URL Pattern from OAuth and payment integration standards.