Developing robust payment integrations can be a complex task, often involving multiple payment gateways, varying API contracts, and specific handling for different payment scenarios like web, mobile app, or mini-program transactions. A streamlined, unified payment library significantly simplifies this process, offering a consistent interface across diverse providers.

This article introduces a comprehensive unified payment solution built with .NET Standard, ensuring compatibility with both .NET Framework and .NET Core environments. A key feature of this library is its out-of-the-box integration capabilities for applications utilizing the ABP Framework, providing developers with a ready-to-use module for rapid deployment.

Core Capabilities and Supported Gateways

The library provides a unified API layer for several popular payment gateways and features, including:

• Alipay Integration: Supports various transaction types such as:
  • APP payments
  • WAP payments
  • International Alipay transactions
  • Profit-sharing functionalities
• WeChat Pay Integration: Comprehensive support for WeChat-specific payment methods:
  • Mini Program payments
  • APP payments
  • Order status queries
  • Corporate payouts (withdrawals)
  • Refund requests
  • Standard red packet distribution
• Allinpay Integration: Includes specific support for:
  • Mini Program payments

Key Architectural Features

Beyond gateway-specific functionalities, the library offers several architectural advantages:

• Unified Payment Notification Handling: A single mechanism to process callback notifications from different payment providers.
• Extensible Logging: Allows injecting custom logging functions, independent of the payment library itself, for tailored monitoring and debugging.
• Dynamic Configuration: Supports injecting configuration retrieval logic, enabling adaptable settings based on environment, user preferences, or multi-tenant architectures.

Seamless Integration with ABP Framework

For applications leveraging the ABP Framework, the library offers specialized module encapsulations designed for immediate use. These modules provide:

• Payment Channel Registration: Through an IPaymentChannelRegistrar interface.
• Centralized Callback Processing: Utilizing an IPaymentNotificationHandler.
• Unified Payment Services: An IUniversalPaymentService and IPaymentAppService for consistent API calls.
• Payment Management: An IPaymentOperationsManager that includes automatic transaction logging (capturing client details, parameters, and exceptions) and simplifies multi-channel callback logic.
• Extended Business Data Storage: Business parameters can accommodate larger data volumes (e.g., up to 500 characters) within transaction logs.

Getting Started: ABP Framework Integration

Integrating the payment library with in an ABP-powered application is straightforward. The following steps outline the process:

1. Install Necessary NuGet Packages

Begin by adding the relevant NuGet packages to your project. For instance, to integrate Allinpay, reference the specific module package:

<PackageReference Include="Your.Package.Namespace.AbpAllinpayModule" Version="X.Y.Z" />

Replace Your.Package.Namespace with the actual package namespace and X.Y.Z with the appropriate version.

2. Declare Module Dependency

In your application's main ABP module, add a dependency on the specific payment module. This ensures proper initialization and service registration.

[DependsOn(typeof(AbpAllinpayModule))]
public class YourApplicationCoreModule : AbpModule
{
    // ...
}

3. Configure Transaction Log Persistence

The payment system automatically records detailed transaction logs, including client information, request parameters, custom data, and any exceptions. To persist these logs using Entity Framework Core, add a DbSet for the PaymentTransactionRecord entity to your application's DbContext:

public class YourApplicationDbContext : AbpDbContext
{
    public DbSet<PaymentTransactionRecord> TransactionRecords { get; set; }

    // ... other DbSets and configuration
}

4. Implement Custom Callback Logic

To handle post-payment notifications and update your bussiness logic, implement the IPaymentNotificationHandler interface. The Identifier property serves as a unique identifier for your specific business scenario.

public class InvoicePaymentNotificationHandler : IPaymentNotificationHandler
{
    public string Identifier { get; set; } = "InvoicePaymentProcessing";

    public async Task HandleNotificationAsync(IUnitOfWorkScope unitOfWorkScope, PaymentTransactionRecord transactionRecord)
    {
        // Extract custom business data from the transaction record
        var customPayload = transactionRecord.CustomData.ParseJson<JObject>();

        // Perform your specific business logic here, e.g.,
        // - Update invoice status
        // - Notify user
        // - Record additional audit logs

        await Task.CompletedTask; // Or await other async operations
    }
}

Ensure that the Identifier string is unique across all your callback implementations.

5. Register Callback Handlers

Register your custom notification handlers with the dependency injection container. This can typically be done in your module's PreInitialize or ConfigureServices method. An example using Castle Windsor's syntax (common in older ABP versions):

IocManager.IocContainer.Register(
    Classes.FromAssembly(typeof(YourApplicationCoreModule).GetAssembly())
        .BasedOn<IPaymentNotificationHandler>()
        .LifestyleTransient()
        .Configure(component => component.Named(component.Implementation.FullName))
        .WithServiceFromInterface()
);

Alternatively, you can register handlers dynamically at runtime using the IPaymentOperationsManager's RegisterNotificationHandler method.

6. Initiate a Payment Transaction

To initiate a payment, resolve the IPaymentAppService from the dependency injection container and call its unified payment method. You can also encapsulate this within your own application service:

public class BillingAppService : YourApplicationServiceBase
{
    private readonly IPaymentAppService _paymentService;

    public BillingAppService(IPaymentAppService paymentService)
    {
        _paymentService = paymentService;
    }

    public async Task<object> ProcessInvoicePayment(InvoicePaymentRequest input)
    {
        var paymentDetails = new PaymentRequest
        {
            Description = $"{input.CustomerName} - {input.InvoiceDescription}",
            SupplementalData = input.ToJsonString(), // Store extra data as JSON
            CallbackKey = "InvoicePaymentProcessing", // Matches the handler's Identifier
            RequesterId = input.CustomerId,
            TransactionSubject = input.InvoiceDescription,
            AmountInCents = (long)(input.TotalAmount * 100), // Amounts usually in cents/smallest unit
            PaymentChannel = input.PreferredPaymentChannel // e.g., Alipay, WeChatPay, Allinpay
        };

        return await _paymentService.InitiatePayment(paymentDetails);
    }
}

Utilizing the IPaymentAppService provides several benefits:

• API Consistency: A single entry point for all payment providers and types.
• Automated Operations: Handles automatic transaction logging, exception management, and other cross-cutting concerns.
• Flexible Data Storage: Custom business data can be stored reliably within the transaction logs, independent of specific payment gateway limitations.

Integration Without ABP Framework

For projects not using the ABP Framework, the underlying .NET Standard libraries can still be integrated directly. Developers can refer to the ABP module implementations as a guide to understand the service registration and component interaction patterns.