ASP.NET网站对接PayPal支付：如何实现信息关联？

我之前帮几个ASP.NET项目做过PayPal支付对接，刚好能给你梳理清楚怎么把你的订单、商品这些关键信息和PayPal关联起来——其实核心就是通过按钮参数传递自定义数据，再配合后端的验证和回调来确保流程闭环，不会出现信息脱节的问题。

一、给PayPal按钮添加关联参数（前端） #

你现在加的应该是基础按钮，要关联自己系统的信息，得给按钮补充关键参数：

1. 静态HTML按钮方案 #

如果是用PayPal提供的静态HTML表单按钮，直接加隐藏字段传递自定义信息：

<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
  <!-- 你的商户邮箱/ID -->
  <input type="hidden" name="business" value="your_business_account@example.com">
  <input type="hidden" name="cmd" value="_xclick">
  <!-- 商品名称，关联你的系统商品 -->
  <input type="hidden" name="item_name" value="年度会员">
  <!-- 商品金额 -->
  <input type="hidden" name="amount" value="199.00">
  <!-- 核心！传递你自己系统的订单ID，PayPal会原封不动回传 -->
  <input type="hidden" name="custom" value="YOUR_ORDER_10001">
  <!-- 货币类型 -->
  <input type="hidden" name="currency_code" value="CNY">
  <!-- 支付成功后跳转页面 -->
  <input type="hidden" name="return" value="https://yourdomain.com/pay-success">
  <!-- PayPal支付完成后主动通知你的后端接口 -->
  <input type="hidden" name="notify_url" value="https://yourdomain.com/paypal-webhook">
  <input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal 安全快捷在线支付">
</form>

这里的custom字段是重中之重，把你自己数据库里的订单ID传进去，后续PayPal会把这个值返回给你，用来关联本地订单。

2. 动态JS SDK按钮方案（更推荐） #

如果用PayPal的JS SDK（动态渲染按钮），可以在创建订单时直接嵌入自定义数据：

paypal.Buttons({
  createOrder: function(data, actions) {
    return actions.order.create({
      purchase_units: [{
        amount: {
          value: '199.00'
        },
        // 自定义订单ID，对应你系统的订单号
        custom_id: 'YOUR_ORDER_10001',
        // 商品描述，方便在PayPal后台识别
        description: '年度会员订阅'
      }]
    });
  },
  onApprove: function(data, actions) {
    return actions.order.capture().then(function(details) {
      // 支付成功后，拿到自定义ID，跳转到你的成功页更新订单
      window.location.href = '/pay-success?orderId=' + details.purchase_units[0].custom_id;
    });
  }
}).render('#paypal-button-container');

二、后端验证与订单关联（ASP.NET核心逻辑） #

光前端传参数还不够，必须在后端做验证（防止恶意篡改），同时完成订单状态的更新：

1. 处理PayPal的IPN/ Webhook通知 #

PayPal会在支付完成后，主动向你设置的notify_url发送POST请求，包含所有支付详情。你需要写一个ASP.NET接口接收并验证：

[HttpPost]
public async Task<IActionResult> PayPalWebhook()
{
    // 读取PayPal发送的所有表单参数
    var formData = await Request.ReadFormAsync();
    var formDict = formData.ToDictionary(kv => kv.Key, kv => kv.Value.ToString());

    // 关键：验证请求确实来自PayPal，防止伪造
    var verifyUrl = "https://ipnpb.paypal.com/cgi-bin/webscr?cmd=_notify-validate&" + Request.QueryString;
    using (var httpClient = new HttpClient())
    {
        var verifyResponse = await httpClient.GetStringAsync(verifyUrl);
        if (verifyResponse == "VERIFIED")
        {
            // 验证通过，提取自定义订单ID
            string localOrderId = formDict["custom"];
            // 提取支付状态（比如Completed表示支付成功）
            string paymentStatus = formDict["payment_status"];

            // 这里写你的业务逻辑：更新本地订单为已支付，生成支付记录等
            UpdateLocalOrderStatus(localOrderId, paymentStatus);
        }
        else
        {
            // 请求是伪造的，记录日志告警
            _logger.LogWarning("PayPal IPN 验证失败，请求参数：{FormData}", formDict);
        }
    }

    // 必须返回200给PayPal，否则PayPal会重复发送通知
    return Ok();
}

如果用PayPal REST API的Webhook，逻辑类似，但需要用官方SDK验证签名，安全性更高。

2. 使用PayPal官方.NET SDK（规范方案） #

如果你的项目是.NET Core/.NET 5+，推荐用官方的PayPalCheckoutSdk NuGet包来处理：
首先安装包：

Install-Package PayPalCheckoutSdk

然后在Program.cs里配置PayPal客户端：

builder.Services.AddSingleton<PayPalHttpClient>(sp => {
    // 沙箱环境用SandboxEnvironment，生产环境用LiveEnvironment
    var env = new SandboxEnvironment("你的ClientID", "你的ClientSecret");
    return new PayPalHttpClient(env);
});

然后在支付成功的回调接口里，查询PayPal订单详情并关联本地订单：

private readonly PayPalHttpClient _payPalClient;
private readonly ILogger<PaymentController> _logger;

public PaymentController(PayPalHttpClient payPalClient, ILogger<PaymentController> logger)
{
    _payPalClient = payPalClient;
    _logger = logger;
}

[HttpGet("pay-success")]
public async Task<IActionResult> PaymentSuccess(string orderId)
{
    try
    {
        // 调用PayPal API查询订单详情
        var request = new OrdersGetRequest(orderId);
        var response = await _payPalClient.Execute(request);
        var payPalOrder = response.Result<Order>();

        // 提取之前传入的自定义订单ID
        string localOrderId = payPalOrder.PurchaseUnits[0].CustomId;
        // 提取PayPal订单状态
        string payStatus = payPalOrder.Status;

        // 更新本地订单状态
        UpdateLocalOrderStatus(localOrderId, payStatus);

        return View("PaySuccess", localOrderId);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "查询PayPal订单失败，订单ID：{OrderId}", orderId);
        return View("PayFailed");
    }
}

三、测试与调试建议 #

• 先在PayPal沙箱环境测试：用沙箱商户账户和测试买家账号，避免真实扣款
• 查看PayPal开发者后台的Webhook日志，确认通知是否正常发送
• 在ASP.NET项目中添加详细日志，记录PayPal返回的所有参数，方便排查问题

内容的提问来源于stack exchange，提问作者Khaled Shoushara