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

> Explore supported payment providers for Sub2API including EasyPay, Alipay, WeChat Pay, Stripe, and Airwallex. Get a complete implementation guide to integrate seamlessly.

- Repository: [Wesley Liddick/sub2api](https://github.com/Wei-Shaw/sub2api)
- Tags: how-to-guide
- Published: 2026-08-23

---

**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)](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)](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)](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)](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)](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)](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/types.go):

```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`](https://github.com/Wei-Shaw/sub2api/blob/main/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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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`):

```go
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:

```go
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)](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`](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/types.go) defines constants that the **registry** in [`registry.go`](https://github.com/Wei-Shaw/sub2api/blob/main/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/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/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/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`](https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/payment/registry.go) that maps the `PaymentType` constants defined in [[`types.go`](https://github.com/Wei-Shaw/sub2api/blob/main/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)](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`](https://github.com/Wei-Shaw/sub2api/blob/main/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.