PHP项目支付宝小程序接入

PHP项目支付宝小程序接入：从零部署到支付回调的完整指南

📚 目录导读

1. 支付宝小程序与PHP项目的集成原理
2. 前期准备：开发者账号、应用创建与密钥配置
3. PHP后端SDK安装与配置
4. 核心流程：获取用户授权 → 生成预支付订单 → 调起支付
5. 支付结果回调与订单状态同步
6. 常见问题QA（含错误码解析）
7. 安全建议与性能优化

支付宝小程序与PHP项目的集成原理

支付宝小程序作为轻量级应用,其支付功能需要后端PHP服务进行签名、订单生成与回调验证，核心流程为：小程序端请求PHP后端 → 后端调用支付宝开放平台API获取支付参数 → 小程序调起支付组件 → 支付宝异步通知PHP后端处理结果。

关键点：支付宝小程序支付不能直接在前端完成签名，所有涉及资金的操作必须由服务端（PHP）完成，以保证安全。

前期准备：开发者账号、应用创建与密钥配置

1 账号与应用创建

• 登录 支付宝开放平台
• 创建移动应用（注意选择“小程序”类型）
• 在小程序详情页中,开通“支付能力”（需签署协议）
• 获取 AppId（应用ID）、AppSecret（应用密钥）

2 密钥生成与配置

建议使用RSA2非对称加密（推荐2048位）：

# 生成私钥（私钥需PHP后端保管）
openssl genrsa -out app_private_key.pem 2048
# 提取公钥（上传到支付宝平台）
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem

在支付宝开放平台上传生成的公钥,平台会返回支付宝公钥，用于验证支付宝回调签名。

PHP后端SDK安装与配置

1 安装官方SDK

推荐使用Composer安装官方PHP SDK：

composer require alipaysdk/alipay-sdk-php

如果项目无法使用Composer,可下载源码引入 aop/AopClient.php。

2 初始化客户端（示例代码）

<?php
require_once 'vendor/autoload.php';
use Alipay\EasySDK\Kernel\Factory;
$alipayConfig = [
    'protocol'         => 'https',
    'gatewayHost'      => 'openapi.alipay.com',
    'signType'         => 'RSA2',
    'appId'            => 'your_app_id',
    'merchantPrivateKey' => file_get_contents('/path/to/app_private_key.pem'),
    'alipayPublicKey'  => file_get_contents('/path/to/alipay_public_key.pem'),
];
Factory::setOptions($alipayConfig);

特别注意：alipayPublicKey 是支付宝公钥，不是应用公钥。

核心流程：获取用户授权 → 生成预支付订单 → 调起支付

1 小程序端获取用户授权

在支付宝小程序中通过 my.getAuthCode 获取临时授权码，传给PHP后端换取用户ID：

// 小程序端
my.getAuthCode({
  scopes: 'auth_base',
  success: (res) => {
    // 将res.authCode传给后端
    my.request({ url: 'https://yourdomain.com/alipay/login', data: { code: res.authCode } });
  }
});

2 PHP后端创建支付订单

public function createOrder($userId, $totalAmount, $subject) {
    $tradeNo = 'order_' . date('YmdHis') . rand(1000,9999);
    $result = Factory::payment()->create()->subject($subject)
        ->outTradeNo($tradeNo)
        ->totalAmount($totalAmount)
        ->buyerId($userId)  // 用户在支付宝平台上的唯一ID
        ->build();
    // 返回订单信息给小程序
    return [
        'trade_no' => $tradeNo,
        'total_amount' => $totalAmount,
        'subject' => $subject,
        // 支付宝返回的 tradeNO 参数
        'alipay_trade_no' => $result['tradeNO'] ?? '',
    ];
}

注意：buyerId 必须使用支付宝用户ID（格式如 2088xxxxxxxxx），而非手机号或昵称。

3 小程序调起支付

后端返回支付参数后,小程序使用 my.tradePay 调起支付：

my.tradePay({
  tradeNO: res.alipay_trade_no,  // 后端返回的支付宝交易号
  success: (payResult) => {
    // 支付成功，等待后端回调确认
  },
  fail: (e) => {
    console.error('支付失败', e);
  }
});

支付结果回调与订单状态同步

1 配置异步通知地址

在支付宝开放平台的应用设置中,配置“支付异步通知地址”（notify_url），建议以/alipay/notify

2 PHP通知处理（关键步骤）

public function notify() {
    // 解析支付宝POST请求（必须验证签名）
    $params = $_POST;
    // 验证签名（使用支付宝公钥）
    $signValid = Factory::payment()->common()->verifyNotify($params);
    if (!$signValid) {
        return 'failure';  // 签名验证失败，返回failure让支付宝重试
    }
    // 提取必要参数
    $tradeStatus = $params['trade_status'];
    $outTradeNo = $params['out_trade_no'];
    $tradeNo = $params['trade_no'];  // 支付宝交易号
    $totalAmount = $params['total_amount'];
    if ($tradeStatus === 'TRADE_SUCCESS') {
        // 更新数据库订单状态
        $this->updateOrderStatus($outTradeNo, 'paid', $tradeNo);
        // 返回success告诉支付宝不必再通知
        echo 'success';
        return;
    }
    echo 'failure';  // 其他状态视为失败
}