萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 整合 PayPal 标准支付:表单构建与 IPN 异步通知验证完整指南

支付流程概览

  1. 用户点击支付 → 提交表单到 https://www.paypal.com/cgi-bin/webscr
  2. PayPal 页面完成付款
  3. 同步跳转 return_url(用户看到成功页)
  4. 异步 POST notify_url(IPN,服务器端验证订单状态)

第一步:前端支付表单

<form method="post" action="https://www.paypal.com/cgi-bin/webscr">
    <input type="hidden" name="cmd" value="_xclick">
    <input type="hidden" name="business" value="merchant@example.com">
    <input type="hidden" name="item_name" value="产品名称">
    <input type="hidden" name="item_number" value="ORDER-20240518-001">
    <input type="hidden" name="amount" value="99.00">
    <input type="hidden" name="currency_code" value="USD">
    <input type="hidden" name="return" value="https://yoursite.com/paypal/return">
    <input type="hidden" name="cancel_return" value="https://yoursite.com/paypal/cancel">
    <input type="hidden" name="notify_url" value="https://yoursite.com/paypal/ipn">
    <input type="hidden" name="rm" value="2"> <!-- return 方式 POST -->
    <input type="hidden" name="lc" value="US"> <!-- 页面语言 -->
    <input type="hidden" name="no_shipping" value="1"> <!-- 不收集地址 -->
    <button type="submit">通过 PayPal 支付</button>
</form>

关键字段说明

第二步:IPN 验证核心类

<?php
class PayPal_IPN {
    private $ipnData = [];
    private $verifyUrl = 'https://www.paypal.com/cgi-bin/webscr'; // 正式
    // private $verifyUrl = 'https://www.sandbox.paypal.com/cgi-bin/webscr'; // 沙箱

    public function __construct() {
        // 仅接受 POST
        if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
            http_response_code(405);
            exit('Method Not Allowed');
        }
    }

    /** 验证 IPN 消息真伪 */
    public function verify(): bool {
        // 1. 原样回传所有 POST 参数 + cmd=_notify-validate
        $post = 'cmd=_notify-validate';
        foreach ($_POST as $key => $val) {
            $this->ipnData[$key] = $val;
            $post .= '&' . $key . '=' . urlencode(stripslashes($val));
        }

        // 2. 发起 HTTPS POST 到 PayPal
        $ch = curl_init($this->verifyUrl);
        curl_setopt_array($ch, [
            CURLOPT_POST            => true,
            CURLOPT_POSTFIELDS      => $post,
            CURLOPT_RETURNTRANSFER  => true,
            CURLOPT_SSL_VERIFYPEER  => true,
            CURLOPT_SSL_VERIFYHOST  => 2,
            CURLOPT_HTTPHEADER      => ['Content-Type: application/x-www-form-urlencoded'],
            CURLOPT_TIMEOUT         => 30,
        ]);
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            error_log("PayPal IPN HTTP $httpCode");
            return false;
        }

        // 3. 判断响应
        return trim($response) === 'VERIFIED';
    }

    /** 获取验证后的数据 */
    public function getData(): array {
        return $this->ipnData;
    }
}

// ========== IPN 入口脚本 ipn.php ==========
require 'PayPal_IPN.php';

$ipn = new PayPal_IPN();
if ($ipn->verify()) {
    $data = $ipn->getData();

    // 业务校验
    $txnId   = $data['txn_id'] ?? '';
    $paymentStatus = $data['payment_status'] ?? '';
    $receiverEmail = $data['receiver_email'] ?? '';
    $mcGross = (float)($data['mc_gross'] ?? 0);
    $mcCurrency = $data['mc_currency'] ?? '';
    $custom  = $data['custom'] ?? ''; // 我们的订单号

    // 必须校验:
    // 1. payment_status == 'Completed'
    // 2. receiver_email 为我方商户邮箱
    // 3. mc_gross/mc_currency 与订单金额一致
    // 4. txn_id 未被处理过(防重放)

    if ($paymentStatus === 'Completed' && $receiverEmail === 'merchant@example.com') {
        // 标记订单已支付、发货、发送通知等
        // TODO: 更新数据库订单状态
        error_log("IPN Verified: Order $custom paid $mcGross $mcCurrency");
    }
} else {
    error_log("IPN Invalid: " . print_r($_POST, true));
}

// 必须输出空白 200 OK,否则 PayPal 会重试
http_response_code(200);
exit;
?>

沙箱测试流程

  1. 注册 PayPal Developer 账号
  2. 创建 Sandbox 商家账号、买家账号
  3. 将表单 action 指向 https://www.sandbox.paypal.com/cgi-bin/webscr
  4. IPN 类中 $verifyUrl 改为沙箱地址
  5. 使用买家账号完成测试支付,查看 IPN 日志

安全加固清单

  • ✅ 必须验证 VERIFIED 后再处理业务
  • ✅ 校验 receiver_email 防止恶意通知
  • ✅ 校验金额、币种与订单一致
  • ✅ 幂等处理:记录已处理 txn_id,防重复发货
  • ✅ IPN 端点必须 HTTPS,响应 200 OK 且无输出
  • ✅ 记录完整 IPN 原始数据供审计

常见坑

🔴 notify_url 用了 localhost / 内网 IP → PayPal 无法回调
🔴 沙箱/正式环境混用(business、verifyUrl 不匹配)
🔴 未处理 pending_reason(如 eCheck 待清算)
🔴 IPN 脚本执行超时(>30s)导致 PayPal 重试、重复处理

按此指南集成,可实现安全、可靠的 PayPal 标准支付闭环。

copyright © 萬盛學電腦網 all rights reserved
字段必填说明
cmd是_xclick 单品购买,_cart 购物车
business是商家 PayPal 邮箱或商户 ID
item_name是商品名称,显示在支付页
amount是单价(_xclick)或总价
currency_code是USD, EUR, CNY 等
notify_url强烈建议IPN 异步通知地址,必须 HTTPS、公网可达
return否支付成功同步跳转页
cancel_return否用户取消跳转页
rm否1=GET 跳转 return,2=POST 跳转(推荐)
custom否自定义透传字段,IPN 原样返回,可存订单 ID