WordPress捐赠插件开发：如何让指定页面接收POST请求

Hey there! Let's walk through how to set up your WordPress donation plugin to receive the POST callback from your payment provider. I'll cover two reliable methods depending on your needs — one using WordPress's REST API (the cleanest, recommended approach) and another using a custom page template if you specifically need a dedicated WordPress page to handle the request.

方法1：使用WordPress REST API创建自定义端点 #

This is the standard way to handle server-to-server requests in WordPress because it's built for this exact use case, handles HTTP responses cleanly, and avoids messing with front-end page templates.

步骤1：在你的插件中注册REST端点 #

Add this code to your plugin's main file (or a dedicated includes file):

// 注册REST API端点
add_action('rest_api_init', 'donation_payment_callback_endpoint');
function donation_payment_callback_endpoint() {
    register_rest_route(
        'donation-plugin/v1', // 自定义命名空间，避免和其他插件冲突
        '/payment-callback/', // 回调路径
        array(
            'methods' => 'POST', // 只接受POST请求
            'callback' => 'handle_donation_payment_callback', // 处理请求的函数
            'permission_callback' => '__return_true', // 允许未授权访问（支付回调无需用户登录）
        )
    );
}

// 处理支付回调的核心函数
function handle_donation_payment_callback(WP_REST_Request $request) {
    // 获取支付提供商发送的POST数据
    $payment_data = $request->get_params();

    // 🔑 关键步骤：验证支付提供商的签名，防止伪造请求！
    // 请根据你的支付提供商文档修改这个验证逻辑
    $is_valid = verify_payment_signature($payment_data);
    if (!$is_valid) {
        return new WP_REST_Response('Invalid signature', 403); // 返回403表示验证失败
    }

    // 处理捐赠业务逻辑：更新订单状态、发送感谢邮件、记录捐赠记录等
    process_donation($payment_data);

    // 返回成功响应给支付提供商
    return new WP_REST_Response('Payment processed successfully', 200);
}

// 示例：签名验证函数（请替换成你支付提供商的实际验证规则）
function verify_payment_signature($data) {
    $your_secret_key = '从支付提供商获取的密钥';
    $received_signature = isset($data['signature']) ? $data['signature'] : '';
    
    // 根据支付提供商的规则生成签名，这里只是示例
    $generated_signature = hash('sha256', $data['order_id'] . $data['amount'] . $your_secret_key);
    
    // 使用hash_equals避免时序攻击
    return hash_equals($generated_signature, $received_signature);
}

// 示例：捐赠处理函数（添加你的业务逻辑）
function process_donation($data) {
    // 比如：创建自定义捐赠记录、更新用户捐赠统计、发送通知邮件
    error_log('Donation processed successfully: ' . print_r($data, true)); // 先记录日志测试
}

如何使用这个端点 #

你的支付提供商的回调URL就是：https://your-site.com/wp-json/donation-plugin/v1/payment-callback/

方法2：使用自定义页面模板接收POST请求 #

If you specifically need a dedicated WordPress page to handle the callback (e.g., for URL consistency with your site), you can create a custom page template that skips front-end rendering and processes the POST request directly.

步骤1：在你的插件中注册自定义页面模板 #

Add this code to your plugin to make the template available in the WordPress page editor:

// 向主题页面模板列表添加我们的自定义模板
add_filter('theme_page_templates', 'add_donation_callback_page_template');
function add_donation_callback_page_template($templates) {
    $templates['page-donation-callback.php'] = 'Donation Payment Callback';
    return $templates;
}

// 告诉WordPress去哪里找到我们的模板文件
add_filter('template_include', 'load_donation_callback_template');
function load_donation_callback_template($template) {
    if (is_page_template('page-donation-callback.php')) {
        return plugin_dir_path(__FILE__) . 'page-donation-callback.php';
    }
    return $template;
}

步骤2：创建自定义页面模板文件 #

Create a file named page-donation-callback.php in your plugin directory with this code:

<?php
/**
 * Template Name: Donation Payment Callback
 */

// 只允许POST请求
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    wp_die('Invalid request method', 'Error', array('response' => 405));
}

// 获取POST数据
$payment_data = $_POST;

// 🔑 同样必须验证签名！
$is_valid = verify_payment_signature($payment_data);
if (!$is_valid) {
    wp_die('Invalid signature', 'Error', array('response' => 403));
}

// 处理捐赠逻辑
process_donation($payment_data);

// 返回成功响应给支付提供商
status_header(200);
echo 'Payment processed successfully';
exit; // 终止页面渲染，因为我们不需要显示任何前端内容

如何使用这个页面 #

1. 进入WordPress后台的 页面 > 新建页面。
2. 给页面起个标题（比如"捐赠回调"），然后在"页面属性"面板中选择 Donation Payment Callback 模板。
3. 发布页面后，你的回调URL就是这个页面的永久链接（比如https://your-site.com/donation-callback/）。

重要注意事项 #

• 永远不要跳过签名验证：这是防止恶意伪造请求的唯一可靠方式。一定要严格按照你的支付提供商的文档实现签名验证，绝对不能偷懒！
• 记录日志：在开发和生产环境中都要记录回调请求和处理结果，方便调试和排查问题。
• 返回正确的HTTP响应码：支付提供商依赖响应码判断是否需要重试请求，所以一定要返回200表示成功，4xx表示错误。
• 测试回调：用Postman或curl这类工具模拟POST请求来测试你的端点，确保它能正确接收和处理数据。比如：

  curl -X POST -d "order_id=123&amount=50&signature=your-generated-signature" https://your-site.com/wp-json/donation-plugin/v1/payment-callback/
  

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