What Are the Supported Payment Providers for Sub2API? Complete Implementation Guide

Sub2API supports five payment providers out-of-the-box—EasyPay, Alipay Direct, WeChat Pay Direct, Stripe, and Airwallex—implemented as Go modules under backend/internal/payment/provider/ and configurable via the Payment Settings UI.

Sub2API is an open-source subscription management platform that includes a native payment orchestration layer. Understanding the supported payment providers for Sub2API is essential for administrators configuring monetization flows. The system exposes these integrations through a provider registry pattern that maps payment type constants to concrete implementations.

Core Payment Providers Architecture

The payment provider system in Sub2API follows a modular design where each gateway is implemented as a separate Go package. All providers reside in backend/internal/payment/provider/ and implement a common interface consumed by the payment service.

EasyPay (Multi-Channel Aggregation)

EasyPay serves as a domestic payment aggregator supporting both Alipay and WeChat Pay through a unified merchant account. This provider uses the identifier easypay and is implemented in [backend/internal/payment/provider/easypay.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/easypay.go). It is ideal for operators seeking simplified Chinese domestic payment acceptance without managing separate merchant relationships with each platform.

Alipay Direct (Native Integration)

The Alipay Direct provider enables native Alipay integration using desktop QR codes and mobile redirects. It uses the identifier alipay and is defined in [backend/internal/payment/provider/alipay.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/alipay.go). This implementation requires direct API credentials including RSA2 private keys and Alipay public certificates.

WeChat Pay Direct (API v3)

WeChat Pay Direct provides native integration with WeChat Pay API v3, supporting Native QR, H5, and MP/JSAPI payment methods. It uses the identifier wxpay and is implemented in [backend/internal/payment/provider/wxpay.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/wxpay.go). Configuration requires merchant ID (mch_id), API v3 keys, and certificate serial numbers.

Stripe (International Coverage)

Stripe handles international card payments and alternative methods including Alipay and WeChat Pay through Stripe's global infrastructure. It uses the identifier stripe and is implemented in [backend/internal/payment/provider/stripe.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/stripe.go). This provider supports webhook signature verification and publishable key architectures.

Airwallex (Experimental Support)

Airwallex provides international card and local payment method support via the Airwallex API. Marked as experimental, it uses the identifier airwallex and is implemented in [backend/internal/payment/provider/airwallex.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/airwallex.go). Administrators should evaluate stability before production deployment.

Payment Type Constants and Registry

The system defines provider identifiers as typed constants in [backend/internal/payment/types.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/types.go):

const (
    TypeAlipay       payment.PaymentType = "alipay"
    TypeWxpay        payment.PaymentType = "wxpay"
    TypeAlipayDirect payment.PaymentType = "alipay_direct"
    TypeWxpayDirect  payment.PaymentType = "wxpay_direct"
    TypeStripe       payment.PaymentType = "stripe"
    TypeEasyPay      payment.PaymentType = "easypay"
    TypeAirwallex    payment.PaymentType = "airwallex"
)

The provider registry located at backend/internal/payment/registry.go maps these type constants to their respective implementations at runtime. When the payment service receives a request, it queries the registry to instantiate the correct provider based on the PaymentType field.

Configuring Payment Providers

Administrators configure providers through the Payment Settings UI by posting JSON payloads matching each provider's schema. Valid provider_key values must align with the registry identifiers.

EasyPay Configuration

{
  "provider_key": "easypay",
  "name": "EasyPay – Domestic",
  "merchant_id": "YOUR_EASYPAY_PID",
  "merchant_key": "YOUR_EASYPAY_PKEY",
  "api_base_url": "https://api.easypay.com"
}

Alipay Direct Configuration

{
  "provider_key": "alipay",
  "name": "Alipay – Direct",
  "appid": "YOUR_ALIPAY_APPID",
  "private_key": "YOUR_RSA2_PRIVATE_KEY",
  "alipay_public_key": "ALIPAY_PUBLIC_KEY"
}

WeChat Pay Direct Configuration

{
  "provider_key": "wxpay",
  "name": "WeChat Pay – Direct",
  "appid": "YOUR_WX_APPID",
  "mch_id": "YOUR_MCH_ID",
  "api_private_key": "YOUR_PEM_PRIVATE_KEY",
  "api_v3_key": "YOUR_32BYTE_V3_KEY",
  "wechat_pay_public_key": "PUBLIC_KEY_PEM",
  "wechat_pay_public_key_id": "PUB_KEY_ID",
  "certificate_serial_number": "SERIAL_NO"
}

Stripe Configuration

{
  "provider_key": "stripe",
  "name": "Stripe – International",
  "secret_key": "sk_test_XXXXXXXXXXXXXXXX",
  "publishable_key": "pk_test_XXXXXXXXXXXXXXXX",
  "webhook_secret": "whsec_XXXXXXXXXXXXXXXX"
}

Implementing Payment Flows

Initiating Payments via Go SDK

Use the payment service to create transactions programmatically. The method parameter must match a valid provider key (stripe, alipay, wxpay, easypay, or airwallex):

import (
    "context"
    "github.com/Wei-Shaw/sub2api/backend/internal/payment"
)

func createTopup(ctx context.Context, orderID, amount, method string) (*payment.CreatePaymentResponse, error) {
    req := payment.CreatePaymentRequest{
        OrderID:      orderID,
        Amount:       amount,                // e.g. "10.00"
        PaymentType:  method,                // "stripe", "alipay", "wxpay", or "easypay"
        Subject:      "Sub2API Credit Top‑up",
        NotifyURL:    "https://your-domain.com/api/v1/payment/webhook/" + method,
        ReturnURL:    "https://your-domain.com/payment/complete",
        IsMobile:     false,
    }
    return paymentService.CreatePayment(ctx, req)
}

The CreatePaymentResponse contains provider-specific fields such as PayURL, QRCode, or ClientSecret (for Stripe), enabling the frontend to render the appropriate payment interface.

Processing Webhook Notifications

Handle asynchronous payment confirmations by verifying webhook signatures and forwarding notifications to the payment service. Stripe example:

func stripeWebhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    headers := map[string]string{
        "Stripe-Signature": r.Header.Get("Stripe-Signature"),
    }

    notif, err := stripeProvider.VerifyNotification(r.Context(), string(body), headers)
    if err != nil {
        http.Error(w, "invalid signature", http.StatusBadRequest)
        return
    }
    
    _ = paymentService.HandlePaymentNotification(r.Context(), *notif, payment.TypeStripe)
    w.WriteHeader(http.StatusOK)
}

Webhook URLs follow the convention https://your-domain.com/api/v1/payment/webhook/{provider_key} as documented in [docs/PAYMENT.md](https://github.com/Wei-Shaw/sub2api/blob/main/docs/PAYMENT.md).

Summary

• Sub2API provides built-in implementations for five payment providers: EasyPay, Alipay Direct, WeChat Pay Direct, Stripe, and Airwallex (experimental).
• Provider implementations reside in backend/internal/payment/provider/ with each gateway encapsulated in its own Go module.
• The type system in backend/internal/payment/types.go defines constants that the registry in registry.go uses to route transactions to the correct provider.
• Configuration requires provider-specific JSON payloads containing merchant credentials and API endpoints.
• The Go SDK supports programmatic payment creation and webhook handling through standardized request/response structures.

Frequently Asked Questions

What is the difference between EasyPay and direct Alipay or WeChat Pay integrations?

EasyPay acts as a payment aggregator that bundles both Alipay and WeChat Pay under a single merchant relationship and API endpoint, configured in [easypay.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/easypay.go). The direct integrations (alipay and wxpay) require separate merchant accounts with each platform and offer deeper API access for native QR codes and mobile redirects, implemented in [alipay.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/alipay.go) and [wxpay.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/wxpay.go) respectively.

How does Sub2API route payment requests to the correct provider at runtime?

The system uses a provider registry located at backend/internal/payment/registry.go that maps the PaymentType constants defined in [types.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/types.go) to their concrete provider implementations. When paymentService.CreatePayment() is invoked, the registry instantiates the appropriate provider based on the PaymentType field in the request.

Is the Airwallex provider production-ready?

According to the source code in [backend/internal/payment/provider/airwallex.go](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/provider/airwallex.go), the Airwallex integration is marked as experimental or optional. Administrators should conduct thorough testing and review the configuration documentation in docs/PAYMENT.md before enabling it for production traffic.

Where are payment provider credentials stored and how are they validated?

Provider credentials are stored as encrypted JSON configuration objects submitted through the Payment Settings UI. Each provider implementation in backend/internal/payment/provider/ defines its own validation logic for required fields such as merchant_id, secret_key, or api_v3_key. The system validates these configurations during provider instantiation and rejects requests with missing or malformed credentials before initiating transactions with the payment gateway.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}