You need to enable JavaScript to run this app. Laravel 中如何将Webhook接收的JSON格式支付详情存入数据库
优惠活动
大模型
产品
解决方案
定价
更多

Laravel 中如何将Webhook接收的JSON格式支付详情存入数据库

Webhook推送的支付JSON数据样例

Laravel 框架下Webhook支付数据正确存储实操

前置路由配置

  • 所有支付渠道的Webhook路由必须跳过CSRF校验:打开app/Http/Middleware/VerifyCsrfToken.php,把对应路由路径加入$except排除数组,否则第三方发起的无CSRF令牌的请求会被直接返回419错误
  • 路由不要挂载认证中间件:Webhook是支付平台主动发起的服务端请求,不存在用户登录态,按常规API路由配置即可,示例:
    // routes/api.php 中配置
    Route::post('/webhook/alipay', [PaymentWebhookController::class, 'handleAlipayNotify']);
    

接收原始JSON payload的正确方式

很多开发容易在这里踩坑,直接用$request->all()或者$request->input()取值,往往会因为请求头的Content-Type不匹配取不到完整数据:

  • 优先读取请求原始内容:$rawPayload = $request->getContent(); 这一步能拿到所有渠道不管什么编码格式发过来的完整请求体
  • 解析JSON格式:用json_decode($rawPayload, true)转成关联数组,解析前要加格式校验,遇到非法JSON请求直接记录日志返回错误响应,不要把脏数据存库
  • 必做前置校验:存库之前必须按照支付渠道的规则校验请求签名,绝对不能无校验直接接收数据,否则很容易被恶意构造请求伪造支付状态

数据库存储的规范流程

  • 提前设计好表结构,核心字段必须包含:
    • 支付渠道返回的全局唯一交易号(加数据库唯一索引,专门用来应对Webhook重复推送的幂等处理)
    • 关联本地业务的订单编号
    • 支付金额、支付状态、交易币种等核心业务字段
    • 原始JSON备份字段(建议用JSON类型或者TEXT类型,完整存下接收到的原始请求内容,后续排查问题不用翻服务日志)
  • 用数据库事务包裹存储逻辑,保证支付记录和本地订单状态更新的一致性,示例代码:
    // 先做幂等判断:重复收到同笔交易的通知直接放行返回成功
    $transactionId = data_get($paymentData, 'trade_no');
    if (PaymentRecord::where('transaction_id', $transactionId)->exists()) {
        return response('success', 200);
    }
    
    DB::transaction(function () use ($paymentData, $rawPayload) {
        // 写入完整支付记录
        PaymentRecord::create([
            'transaction_id' => data_get($paymentData, 'trade_no'),
            'order_no' => data_get($paymentData, 'out_trade_no'),
            'amount' => data_get($paymentData, 'total_amount'),
            'pay_status' => data_get($paymentData, 'trade_status'),
            'raw_content' => $rawPayload
        ]);
    
        // 同步更新本地订单状态
        Order::where('order_no', data_get($paymentData, 'out_trade_no'))
            ->update([
                'pay_status' => 'paid',
                'paid_at' => now()
            ]);
    });
    
  • 取值时统一用Laravel提供的data_get()辅助函数做空值兼容,避免因为不同通知类型的字段差异触发未定义索引的报错

收尾响应要求

  • 处理完存储逻辑后,必须按对应支付渠道的要求返回固定格式的响应(比如支付宝要求返回纯文本success),否则渠道会判定通知失败持续重试
  • 所有异常要捕获后写入日志,不要抛出未处理的500错误,避免触发渠道的无限重试机制

内容的提问来源于stack exchange,提问作者Haj Md Nexevo

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.20 17:15:02