alipay_serverpod

pub package

Serverpod integration for Alipay App Pay + QR Pay.

中文文档

Prerequisites

Before using this package, you need to complete the following steps on Alipay platforms.

Step 1: Register Alipay Merchant Account

  1. Go to Alipay Merchant Platform
  2. Register a merchant account (requires business license for enterprise, or personal real-name for individual)
  3. Complete account verification

Step 2: Sign Product Agreements

Sign the required payment products at Alipay Merchant Platform - Product Center:

Feature Product to Sign Notes
App Pay App Payment (App支付) For invoking Alipay app from your mobile app
QR Pay Face-to-Face Payment (当面付) For generating QR codes

Note: Product approval may take 1-3 business days.

Step 3: Create Application on Open Platform

  1. Go to Alipay Open Platform Console
  2. Click Create Application → Select Mobile/Web App
  3. Fill in basic information and submit for review
  4. After approval, note down your App ID

Step 4: Configure Keys

  1. In your application page, go to Development Settings → Interface Signing Method
  2. Choose Self-upload Public Key mode
  3. Generate RSA2 key pair (2048-bit):
# Generate private key
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

# Export public key
openssl rsa -in private_key.pem -pubout -out public_key.pem

# Get public key string (upload this to Alipay; console only accepts no headers/line breaks)
grep -v "^-----" public_key.pem | tr -d '\n' && echo

# Get private key for passwords.yaml (two supported styles)
# Option A (recommended): paste the full PEM (including headers) into passwords.yaml
cat private_key.pem

# Option B: extract only the Base64 body (single line, no headers/line breaks)
grep -v "^-----" private_key.pem | tr -d '\n' && echo
  1. Upload the public key string to Alipay console
  2. Download the Alipay Public Key (支付宝公钥) from console after upload
  3. Save both keys for configuration below

Official Docs: Key Configuration Guide

Step 5: Bind Products to Application

  1. In your application page, go to Product bindng (产品绑定)
  2. Add the products you signed in Step 2

Features

  • Config Integration - Read sensitive keys from passwords.yaml, keep non-sensitive config in server.dart
  • Base Endpoint - Ready-to-use AlipayPaymentBaseEndpoint helpers
  • Notify Route - Signature verification and callback injection
  • Full Export - Re-exports all APIs from alipay

Installation

# gen_server/pubspec.yaml
dependencies:
  alipay_serverpod: ^0.1.1

Configuration

passwords.yaml (credentials only)

shared:
  # Private key supports full PEM or Base64 body (single line, no headers/line breaks)
  alipayRsa2PrivateKey: |
    -----BEGIN PRIVATE KEY-----
    ...your private key...
    -----END PRIVATE KEY-----
  alipayPublicKey: 'MIIBIjANBg...'  # Base64 DER public key

server.dart (non-sensitive config)

import 'package:alipay_serverpod/alipay_serverpod.dart';

void run(List<String> args) async {
  final pod = Serverpod(args, Protocol(), Endpoints());

  AlipayServerpodConfigStore.configure(
    appConfig: AlipayAppConfigServerpod(
      appId: '2021006129696450',
      notifyUrl: 'https://your-server/alipay/notify',
    ),
  );

  // Add notify route with your accounting logic
  final alipayConfig = AlipayConfigServerpod.fromServerpod(pod);
  pod.webServer.addRoute(
    AlipayNotifyRoute(
      config: alipayConfig,
      onPaymentSuccess: (session, notification) async {
        // Your idempotent recharge logic here
      },
    ),
    '/alipay/notify',
  );

  await pod.start();
}

Quick Start

Using Base Endpoint

import 'package:alipay_serverpod/alipay_serverpod.dart';

class PaymentEndpoint extends AlipayPaymentBaseEndpoint {
  Future<AppPayOrder> createOrder(Session session, int amountCents) async {
    return createAppPayOrder(
      session,
      amountCents,
      outTradeNo: 'order_001',
      subject: 'Recharge',
      passbackParams: 'uid=123',
    );
  }
}

Notify Callback (Idempotent)

AlipayNotifyRoute(
  config: alipayConfig,
  onPaymentSuccess: (session, notification) async {
    if (!notification.paid) return;

    // Idempotent logic recommended
    // 1) Check existing transaction by outTradeNo
    // 2) If not exists, apply balance change
  },
);

API Reference

AlipayServerpodConfigStore

Global config store for non-sensitive values.

AlipayServerpodConfigStore.configure(
  appConfig: AlipayAppConfigServerpod(...),
);

AlipayConfigServerpod

Builds AlipayServerpodConfig by combining config + passwords.

AlipayPaymentBaseEndpoint

Base endpoint with helper methods:

  • createAppPayOrder
  • createQrOrder
  • queryOrder

AlipayNotifyRoute

Signature-verified notify route with injected callbacks.

AlipayNotification

Parsed notify payload with helper fields:

  • paid
  • effectiveAmount

Troubleshooting

Issue Error Code Cause Fix
Missing passwords - Keys not in passwords.yaml Add alipayRsa2PrivateKey and alipayPublicKey
Invalid signature isv.invalid-signature / 40002 Private key doesn't match public key on Alipay Re-upload public key to Alipay console, ensure private key matches
Insufficient permissions isv.insufficient-isv-permissions / 40006 Product not signed or not bound Sign product at Merchant Platform, bind to app at Open Platform
App ID not found isv.invalid-app-id Wrong App ID or app not approved Check App ID, ensure app status is "Online"
Notify not triggered - URL unreachable Ensure HTTPS with valid certificate, public network access
Base64 decode error FormatException: Invalid padding Extra characters in private key Remove trailing whitespace/newlines from key string

Common Configuration Errors

1. Key Mismatch (isv.invalid-signature)

The most common error. Verify your keys match:

# Export public key from your private key
echo "YOUR_PRIVATE_KEY_BASE64" | base64 -d | openssl pkey -inform DER -pubout

# Compare with public key on Alipay console - they must be identical

2. Product Not Bound (40006)

  1. Check Merchant Platform → Products → Ensure product is signed
  2. Check Open Platform → Your App → Product Binding → Ensure product is added

3. Wrong Key Format

  • alipayRsa2PrivateKey: PKCS#8 RSA private key. You can provide the full PEM (recommended) or only the PEM Base64 body (single line, no headers/line breaks). PKCS#1 (-----BEGIN RSA PRIVATE KEY-----) is not supported.
  • alipayPublicKey: The Alipay public key downloaded from console (Base64 DER), NOT your app public key.

License

MIT License

Libraries

alipay_serverpod
Alipay Serverpod integration.